diff --git a/doc/api/motors.rst b/doc/api/motors.rst index ed113d2..813c8db 100644 --- a/doc/api/motors.rst +++ b/doc/api/motors.rst @@ -17,7 +17,7 @@ The Motor Class .. automethod:: pybricks.builtins.Motor.stalled - .. rubric:: Motion + .. rubric:: Action .. automethod:: pybricks.builtins.Motor.stop @@ -31,21 +31,14 @@ The Motor Class .. automethod:: pybricks.builtins.Motor.run_until_stalled - .. rubric:: Manual motion control - - The following methods are useful if you want full manual control of - the motor. - .. automethod:: pybricks.builtins.Motor.dc + .. rubric:: Advanced motion control + .. automethod:: pybricks.builtins.Motor.track_target - .. attribute:: control - - The motors use PID control to accurately track the speed and - angle targets that you specify. You can change its behavior through the - ``control`` attribute of the motor. See :ref:`control` for an overview - of available methods. + .. autoattribute:: control + :annotation: Motor Tips & Tricks ^^^^^^^^^^^^^^^^^^^ diff --git a/pybricks/builtins.py b/pybricks/builtins.py index 89ca465..aed23f0 100644 --- a/pybricks/builtins.py +++ b/pybricks/builtins.py @@ -155,6 +155,10 @@ class Motor(DCMotor): """Generic class to control motors with built-in rotation sensors.""" control = Control() + """The motors use PID control to accurately track the speed and + angle targets that you specify. You can change its behavior through the + ``control`` attribute of the motor. See :ref:`control` for an overview + of available methods.""" def __init__(self, port, positive_direction=Direction.CLOCKWISE, @@ -190,7 +194,7 @@ class Motor(DCMotor): pass def speed(self): - """Get the speed (angular velocity) of the motor. + """Get the speed of the motor. Returns: :ref:`speed`: Motor speed. @@ -199,12 +203,7 @@ class Motor(DCMotor): pass def stalled(self): - """Check whether the motor is currently stalled. - - A motor is stalled when it cannot move even with the maximum torque. - For example, when something is blocking the motor or your mechanism - simply cannot turn any further. See :ref:`stalled` for more - information. + """Check whether the motor is currently :ref:`stalled `. Returns: bool: ``True`` if the motor is stalled, ``False`` if it is not. @@ -216,9 +215,7 @@ class Motor(DCMotor): """Reset the accumulated rotation angle of the motor. Arguments: - angle (:ref:`angle`): Value to which the angle should be reset. If - you don't specify an angle, the absolute - value will be used if the motor supports it. + angle (:ref:`angle`): Value to which the angle should be reset. """ pass @@ -232,12 +229,9 @@ class Motor(DCMotor): pass def run(self, speed): - """Keep the motor running at a constant speed (angular velocity). + """Keep the motor running at a constant speed. - The motor will accelerate towards the requested speed and the duty - cycle is automatically adjusted to keep the speed constant, even under - some load. This continues in the background until you give the motor a - new command or the program stops. + The motor keeps running until you give a new command. Arguments: speed (:ref:`speed`): Speed of the motor. @@ -245,13 +239,7 @@ class Motor(DCMotor): pass def run_time(self, speed, time, stop_type=Stop.COAST, wait=True): - """Run the motor at a constant speed (angular velocity) for a given - amount of time. - - The motor will accelerate towards the requested speed and the duty - cycle is automatically adjusted to keep the speed constant, even under - some load. It begins to decelerate just in time to reach standstill - after the specified duration. + """Run the motor at a constant speed for a given amount of time. Arguments: speed (:ref:`speed`): Speed of the motor. @@ -261,20 +249,12 @@ class Motor(DCMotor): :class:`Stop.COAST <.parameters.Stop>`). wait (bool): Wait for the maneuver to complete before continuing with the rest of the program (*Default*: ``True``). - This means that your program waits for the - specified ``time``. """ pass def run_angle(self, speed, rotation_angle, stop_type=Stop.COAST, wait=True): - """Run the motor at a constant speed (angular velocity) by a given - angle. - - The motor will accelerate towards the requested speed and the duty - cycle is automatically adjusted to keep the speed constant, even under - some load. It begins to decelerate just in time so that it comes to a - standstill after traversing the given angle. + """Run the motor at a constant speed by a given angle. Arguments: speed (:ref:`speed`): Speed of the motor. @@ -285,70 +265,49 @@ class Motor(DCMotor): :class:`Stop.COAST <.parameters.Stop>`). wait (bool): Wait for the maneuver to complete before continuing with the rest of the program (*Default*: ``True``). - This means that your program waits until the motor has - traveled precisely the requested angle. """ pass def run_target(self, speed, target_angle, stop_type=Stop.COAST, wait=True): - """ Run the motor at a constant speed (angular velocity) towards a + """ Run the motor at a constant speed towards a given target angle. - The motor will accelerate towards the requested speed and the duty - cycle is automatically adjusted to keep the speed constant, even under - some load. It begins to decelerate just in time so that it comes to a - standstill at the given target angle. - The direction of rotation is automatically selected based on the target - angle. + angle. It does matter if ``speed`` is positive or negative. Arguments: - speed (:ref:`speed`): Absolute speed of the motor. The direction - will be automatically selected based on the - target angle: it makes no difference if you - specify a positive or negative speed. - target_angle (:ref:`angle`): Target angle that the motor should - rotate to, regardless of its current - angle. + speed (:ref:`speed`): Speed of the motor. + target_angle (:ref:`angle`): Angle that the motor should + rotate to. stop_type (Stop): Whether to coast, brake, or hold after coming to a standstill (*Default*: :class:`Stop.COAST <.parameters.Stop>`). - wait (bool): Wait for the maneuver to complete before continuing - with the rest of the program (*Default*: ``True``). - This means that your program waits until the motor - has reached the target angle. + wait (bool): Wait for the motor to reach the target + before continuing with the rest of the + program (*Default*: ``True``). """ pass def run_until_stalled(self, speed, stop_type=Stop.COAST, duty_limit=None): - """Run the motor at a constant speed (angular velocity) until it - stalls. The motor is considered stalled when it cannot move even with - the maximum torque. See :meth:`.stalled` for a more precise definition. - - The ``duty_limit`` argument lets you temporarily limit the motor torque - during this maneuver. This is useful to avoid applying the full motor - torque to a geared or lever mechanism. + """Run the motor at a constant speed until it + :ref:`stalls ` Arguments: speed (:ref:`speed`): Speed of the motor. stop_type (Stop): Whether to coast, brake, or hold after coming to a standstill (*Default*: :class:`Stop.COAST <.parameters.Stop>`). - duty_limit (:ref:`percentage`): Relative torque limit during this - command. + duty_limit (:ref:`percentage`): Torque limit during this + command. This is useful to avoid applying the full motor + torque to a geared or lever mechanism. """ pass def track_target(self, target_angle): - """Track a target angle that varies in time. - - This function is quite similar to :meth:`.run_target`, but speed and - acceleration settings are ignored: it will move to the target angle as - fast as possible. Instead, you adjust speed and acceleration by - choosing how fast or slow you vary the ``target_angle``. - - This method is useful in fast loops where the motor target changes - continuously. + """Track a target angle. This is similar to :meth:`.run_target`, but + the usual smooth acceleration is skipped: it will move to the target + angle as fast as possible. This method is useful if you want to + continuously change the target angle. Arguments: target_angle (:ref:`angle`): Target angle that the motor should @@ -413,6 +372,15 @@ class Motor(DCMotor): """ pass + def dc(self, duty): + """Rotate the motor at a given duty cycle (also known as "power"). + + This method lets you use a motor just like a simple DC motor. + + Arguments: + duty (:ref:`percentage`): The duty cycle (-100.0 to 100). + """ + class Speaker(): """Play beeps and sounds using a speaker.""" diff --git a/pybricks/pupdevices.py b/pybricks/pupdevices.py index 7494c8b..086397b 100644 --- a/pybricks/pupdevices.py +++ b/pybricks/pupdevices.py @@ -7,6 +7,16 @@ from .builtins import Motor as CommonMotor class Motor(CommonMotor): """LEGO® Powered Up Motors""" + def reset_angle(self, angle): + """Reset the accumulated rotation angle of the motor. + + Arguments: + angle (:ref:`angle`): Value to which the angle should be reset. If + you don't specify an angle, the absolute + value will be used if the motor supports it. + """ + pass + class RemoteControl(): """LEGO® Powered Up Bluetooth Remote Control/Handset (6214560)"""