diff --git a/doc/main/CHANGELOG.md b/doc/main/CHANGELOG.md index f2411fe..3d29dfe 100644 --- a/doc/main/CHANGELOG.md +++ b/doc/main/CHANGELOG.md @@ -3,8 +3,11 @@ ## Added: - MicroPython module documentation. - Examples for hub system functions including stop button and shutdown. + +## Changed: - Build IDE docs as main docs with minor changes, instead of a completely separate build. +- Moved motor control documentation to the motor page. # 1.5.0 - 2021-07-01 diff --git a/doc/main/index.rst b/doc/main/index.rst index eab50ac..fac86ef 100644 --- a/doc/main/index.rst +++ b/doc/main/index.rst @@ -132,5 +132,4 @@ Pybricks Documentation :hidden: signaltypes - motors .. frames diff --git a/doc/main/motors.rst b/doc/main/motors.rst deleted file mode 100644 index 06d5177..0000000 --- a/doc/main/motors.rst +++ /dev/null @@ -1,47 +0,0 @@ -More about Motors -=========================================== - -.. _control: - -The Control Class -^^^^^^^^^^^^^^^^^ - -The ``Motor`` class uses PID control to accurately track your commanded target -angles. Similarly, the ``DriveBase`` class uses two of such controllers: -one to control the heading and one to control the traveled distance. - -You can change the control settings through the following attributes, which are -instances of the ``Control`` class given below.: - - - ``Motor.control`` - - ``DriveBase.heading_control`` - - ``DriveBase.distance_control`` - -You can only change the settings while the controller is stopped. For example, -you can set the settings at the beginning of your program. Alternatively, first -call ``stop()`` to make your ``Motor`` or ``DriveBase`` stop, and then change -the settings. - -.. autoclass:: pybricks._common.Control - :no-members: - - .. autoattribute:: pybricks._common.Control.scale - :annotation: - - .. rubric:: Status - - .. automethod:: pybricks._common.Control.done - - .. automethod:: pybricks._common.Control.stalled - - .. automethod:: pybricks._common.Control.load - - .. rubric:: Settings - - .. automethod:: pybricks._common.Control.limits - - .. automethod:: pybricks._common.Control.pid - - .. automethod:: pybricks._common.Control.target_tolerances - - .. automethod:: pybricks._common.Control.stall_tolerances diff --git a/doc/main/pupdevices/motor.rst b/doc/main/pupdevices/motor.rst index 392e777..13541ec 100644 --- a/doc/main/pupdevices/motor.rst +++ b/doc/main/pupdevices/motor.rst @@ -40,21 +40,41 @@ Motors with Rotation Sensors .. automethod:: pybricks.pupdevices.Motor.run_target + .. automethod:: pybricks.pupdevices.Motor.track_target + .. automethod:: pybricks.pupdevices.Motor.run_until_stalled .. automethod:: pybricks.pupdevices.Motor.dc - .. rubric:: Advanced motion control + .. _settings: - .. automethod:: pybricks.pupdevices.Motor.track_target + .. rubric:: Motor status - .. autoattribute:: pybricks.ev3devices.Motor.control - :annotation: - :noindex: + .. attribute:: control.scale -.. FIXME: above should point to pupdevices but inherited class attributes - do not work yet (https://github.com/sphinx-doc/sphinx/issues/741). + Number of degrees that the motor turns to complete one degree at the + output of the gear train. This is the gear ratio determined from the + ``gears`` argument when initializing the motor. + .. automethod:: pybricks.pupdevices.Motor.control.done + + .. automethod:: pybricks.pupdevices.Motor.control.stalled + + .. automethod:: pybricks.pupdevices.Motor.control.load + + .. rubric:: Motor settings + + You can only change these settings while the controller is stopped. For + example, you can change them at the start of your program. Alternatively, + first call :meth:`stop() `, and then change the settings. + + .. automethod:: pybricks.pupdevices.Motor.control.limits + + .. automethod:: pybricks.pupdevices.Motor.control.pid + + .. automethod:: pybricks.pupdevices.Motor.control.target_tolerances + + .. automethod:: pybricks.pupdevices.Motor.control.stall_tolerances Initialization Examples ----------------------- diff --git a/doc/main/robotics.rst b/doc/main/robotics.rst index 23a2470..98077e3 100644 --- a/doc/main/robotics.rst +++ b/doc/main/robotics.rst @@ -90,7 +90,7 @@ The :meth:`.settings` method is used to adjust commonly used settings like the default speed and acceleration for straight maneuvers and turns. - Use the following attributes to adjust more advanced control setttings. + Use the following attributes to adjust more advanced control settings. You can only change the settings while the robot is stopped. This is either before you begin driving or after you call :meth:`.stop`. diff --git a/src/pybricks/_common.py b/src/pybricks/_common.py index 962d2fc..2714614 100644 --- a/src/pybricks/_common.py +++ b/src/pybricks/_common.py @@ -190,10 +190,8 @@ class Control: pass def load(self): - """Gets the load acting on the ``Motor`` or ``DriveBase``. - - This value is determined from the feedback torque that is - needed to track the speed or position command given by the user. + """Estimates the load based on the torque required to maintain the + specified speed or angle. When coasting, braking, or controlling the duty cycle manually, the load cannot be estimated in this way. Then this method returns zero. diff --git a/src/pybricks/robotics.py b/src/pybricks/robotics.py index 1231f54..7ec9a9a 100644 --- a/src/pybricks/robotics.py +++ b/src/pybricks/robotics.py @@ -26,12 +26,19 @@ class DriveBase: distance_control = _Control() """The traveled distance and drive speed are controlled by a PID controller. You can use this attribute to change its settings. - See :ref:`control` for an overview of available methods.""" + See the :ref:`motor control ` attribute for an overview of + available methods. The ``distance_control`` attribute has the same + functionality, but the settings apply to every millimeter driven by the + drive base, instead of degrees turned by one motor.""" heading_control = _Control() """The robot turn angle and turn rate are controlled by a PID controller. You can use this attribute to change its settings. - See :ref:`control` for an overview of available methods.""" + See the :ref:`motor control ` attribute for an overview of + available methods. The ``heading_control`` attribute has the same + functionality, but the settings apply to every degree of rotation of the + whole drive base (viewed from the top) instead of degrees turned by one + motor.""" def __init__(self, left_motor, right_motor, wheel_diameter, axle_track): """DriveBase(left_motor, right_motor, wheel_diameter, axle_track)