mirror of
https://github.com/pybricks/pybricks-api.git
synced 2026-09-12 01:24:17 +00:00
pybricks.pupdevices.Motor: Document control here.
Based on user feedback, we learned that the control attribute is used more frequently than anticipated. Therefore it makes sense to document it here, just like we do with instances of pybricks.common classes in hubs. This makes it a bit easier to find and see how it is used, along with some of the existing examples.
This commit is contained in:
Laurens Valk
@@ -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
|
||||
|
||||
|
||||
@@ -132,5 +132,4 @@ Pybricks Documentation
|
||||
:hidden:
|
||||
|
||||
signaltypes
|
||||
motors
|
||||
.. frames
|
||||
|
||||
@@ -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
|
||||
@@ -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() <pybricks.pupdevices.Motor.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
|
||||
-----------------------
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 <settings>` 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 <settings>` 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)
|
||||
|
||||
Reference in New Issue
Block a user