diff --git a/doc/api/motors.rst b/doc/api/motors.rst index a2d2ade..e9b8cf0 100644 --- a/doc/api/motors.rst +++ b/doc/api/motors.rst @@ -17,7 +17,7 @@ The Motor Class .. automethod:: pybricks.builtins.Motor.stalled - .. rubric:: Moving the motor + .. rubric:: Motion .. automethod:: pybricks.builtins.Motor.stop @@ -29,14 +29,17 @@ The Motor Class .. automethod:: pybricks.builtins.Motor.run_target + .. 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:: Moving the motor (advanced) - .. automethod:: pybricks.builtins.Motor.track_target - .. automethod:: pybricks.builtins.Motor.run_until_stalled - .. rubric:: Changing motor settings .. automethod:: pybricks.builtins.Motor.set_run_settings diff --git a/doc/api/pupdevices.rst b/doc/api/pupdevices.rst index b343f78..bffc6e0 100644 --- a/doc/api/pupdevices.rst +++ b/doc/api/pupdevices.rst @@ -4,6 +4,16 @@ .. automodule:: pybricks.pupdevices :no-members: +DCMotor +^^^^^^^^^^^^ + +.. autoclass:: pybricks.builtins.DCMotor + :noindex: + :no-members: + + .. automethod:: pybricks.builtins.DCMotor.dc + :noindex: + Motor ^^^^^^^^^^^^ @@ -11,8 +21,6 @@ Motor :noindex: :no-members: - .. rubric:: Methods for motors with rotation sensors - .. automethod:: pybricks._instances.Motor.angle :noindex: @@ -37,6 +45,10 @@ Motor .. automethod:: pybricks._instances.Motor.run_target :noindex: + .. automethod:: pybricks.builtins.Motor.dc + :noindex: + + This method lets you use a motor as if it is a simple DC motor. Color and Distance Sensor ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/pybricks/_instances.py b/pybricks/_instances.py index 33940cd..a79cd05 100644 --- a/pybricks/_instances.py +++ b/pybricks/_instances.py @@ -30,12 +30,11 @@ display = make_instance(Display) class Motor(Motor): + """Generic class to control motors with built-in rotation sensors.""" def __init__(self, port, positive_direction=Direction.CLOCKWISE): """Motor(port, positive_direction=Direction.CLOCKWISE) - Create a motor instance. - Arguments: port (Port): Port to which the motor is connected. positive_direction (Direction): Which direction the motor should diff --git a/pybricks/builtins.py b/pybricks/builtins.py index 0e74bb6..068af98 100644 --- a/pybricks/builtins.py +++ b/pybricks/builtins.py @@ -4,8 +4,62 @@ speakers, and batteries.""" from .parameters import Align, Direction, Stop, Axis -class Motor(): - """Generic class to control motors with built-in encoders.""" +class DCMotor(): + """Generic class to control simple motors without rotation sensors, such + as train motors.""" + + def __init__(self, port, + positive_direction=Direction.CLOCKWISE): + """DCMotor(port, positive_direction=Direction.CLOCKWISE) + + Arguments: + port (Port): Port to which the motor is connected. + positive_direction (Direction): Which direction the motor should + turn when you give a positive duty cycle value. + """ + pass + + def dc(self, duty): + """Rotate the motor at a given duty cycle (also known as "power"). + + Arguments: + duty (:ref:`percentage`): The duty cycle (-100.0 to 100). + """ + pass + + def set_dc_settings(self, duty_limit, duty_offset): + """Configure the settings to adjust the behavior of the :meth:`.dc` + command. This also affects all of the ``run`` commands, which use + the :meth:`.dc` method in the background. + + Arguments: + duty_limit (:ref:`percentage`): Relative torque limit during + subsequent motor commands. This + sets the maximum duty cycle that is + applied during any subsequent motor + command. This reduces the maximum + torque output to a percentage of + the absolute maximum stall torque. + This is useful to avoid applying + the full motor torque to a geared + or lever mechanism, or to prevent + your LEGO® train from + unintentionally going at full + speed. (*Default*: 100). + duty_offset (:ref:`percentage`): Minimum duty cycle given when you + use :meth:`.dc`. This adds a small + feed forward torque so that your + motor will move even for very low + duty cycle values, which can be + useful when you create your own + feedback controllers + (*Default*: 0). + """ + pass + + +class Motor(DCMotor): + """Generic class to control motors with built-in rotation sensors.""" def __init__(self, port, positive_direction=Direction.CLOCKWISE, @@ -31,14 +85,6 @@ class Motor(): """ pass - def dc(self, duty): - """Set the duty cycle of the motor. - - Arguments: - duty (:ref:`percentage`): The duty cycle (-100.0 to 100). - """ - pass - def angle(self): """Get the rotation angle of the motor. @@ -229,36 +275,6 @@ class Motor(): """ pass - def set_dc_settings(self, duty_limit, duty_offset): - """Configure the settings to adjust the behavior of the :meth:`.dc` - command. This also affects all of the ``run`` commands, which use - the :meth:`.dc` method in the background. - - Arguments: - duty_limit (:ref:`percentage`): Relative torque limit during - subsequent motor commands. This - sets the maximum duty cycle that is - applied during any subsequent motor - command. This reduces the maximum - torque output to a percentage of - the absolute maximum stall torque. - This is useful to avoid applying - the full motor torque to a geared - or lever mechanism, or to prevent - your LEGO® train from - unintentionally going at full - speed. (*Default*: 100). - duty_offset (:ref:`percentage`): Minimum duty cycle given when you - use :meth:`.dc`. This adds a small - feed forward torque so that your - motor will move even for very low - duty cycle values, which can be - useful when you create your own - feedback controllers - (*Default*: 0). - """ - pass - def set_run_settings(self, max_speed, acceleration): """Configure the maximum speed and acceleration/deceleration of the motor for all run commands.