From 46dba95342eacb9e9cdfd2728778bf2fc05c9672 Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Wed, 1 Jan 2020 13:18:41 +0100 Subject: [PATCH] api/builtins: add DCMotor This is a strict subset of Motor, covering functionality of DC motors only. This is useful for motors without encoders, such as train motors. It is inherited by Motor, which adds functionality that requires encoders. --- doc/api/motors.rst | 13 +++--- doc/api/pupdevices.rst | 16 ++++++- pybricks/_instances.py | 3 +- pybricks/builtins.py | 96 ++++++++++++++++++++++++------------------ 4 files changed, 79 insertions(+), 49 deletions(-) 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.