From f12c5791593fdf47f731cb07fde0003b4b52071b Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Mon, 11 Nov 2019 13:22:08 +0100 Subject: [PATCH] doc: move Motor to dedicated page. Instead, show shorter, simpler Motor docs platform-devices pages. For the moment, this just means deleting the advanced methods section from those pages, but we may choose to simplify further. This change makes it easier to navigate the ev3devices/pupdevices pages because the motor sections aren't overly long. Details will still be available on the Motor pages for those who wish to use the more advanced motor capabilities such as adjusting the PID settings. --- doc/api/ev3devices.rst | 48 +--------------------- doc/api/index.rst | 3 +- doc/api/motors.rst | 92 ++++++++++++++++++++++++++++++++++++++++++ doc/api/pupdevices.rst | 48 +--------------------- pybricks/_instances.py | 20 ++++++++- 5 files changed, 116 insertions(+), 95 deletions(-) create mode 100644 doc/api/motors.rst diff --git a/doc/api/ev3devices.rst b/doc/api/ev3devices.rst index 675afbf..9226dd4 100644 --- a/doc/api/ev3devices.rst +++ b/doc/api/ev3devices.rst @@ -7,7 +7,8 @@ Motor ^^^^^^^^^^^^ -.. autoclass:: pybricks.ev3devices.Motor +.. autoclass:: pybricks._instances.Motor + :noindex: :no-members: Example:: @@ -48,51 +49,6 @@ Motor .. automethod:: pybricks.ev3devices.Motor.run_target - .. rubric:: Advanced methods for motors with rotation sensors - - .. automethod:: pybricks.ev3devices.Motor.track_target - - Example:: - - # Initialize motor and timer - from math import sin - motor = Motor(Port.A) - watch = StopWatch() - amplitude = 90 - - # In a fast loop, compute a reference angle - # and make the motor track it. - while True: - # Get the time in seconds - seconds = watch.time()/1000 - # Compute a reference angle. This produces - # a sine wave that makes the motor move - # smoothly between -90 and +90 degrees. - angle_now = sin(seconds)*amplitude - # Make the motor track the given angle - motor.track_target(angle_now) - - .. automethod:: pybricks.ev3devices.Motor.stalled - - .. automethod:: pybricks.ev3devices.Motor.run_until_stalled - - .. automethod:: pybricks.ev3devices.Motor.set_dc_settings - - .. automethod:: pybricks.ev3devices.Motor.set_run_settings - - Example:: - - # Set the maximum speed to 200 deg/s and - # acceleration to 400 deg/s/s. - example_motor.set_run_settings(200, 400) - - # Make the motor run for 5 seconds. Even though the - # speed argument is 300 deg/s in this example, the - # motor will move at only 200 deg/s because of - # the settings above. - example_motor.run_time(300, 5000) - - .. automethod:: pybricks.ev3devices.Motor.set_pid_settings Touch Sensor ^^^^^^^^^^^^ diff --git a/doc/api/index.rst b/doc/api/index.rst index 991f147..7381ab4 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -30,10 +30,11 @@ Intro .. toctree:: :maxdepth: 1 - :caption: Engineering Essentials + :caption: Engineering Extras :hidden: signaltypes + motors .. toctree:: :maxdepth: 1 diff --git a/doc/api/motors.rst b/doc/api/motors.rst new file mode 100644 index 0000000..afff49d --- /dev/null +++ b/doc/api/motors.rst @@ -0,0 +1,92 @@ +More about Motors +=========================================== + +Motor +^^^^^^^^^^^^ + +.. autoclass:: pybricks.builtins.Motor + :no-members: + + Example:: + + # Initialize a motor (by default this means is, without any gears). + example_motor = Motor(Port.A) + + # Initialize a motor with positive speed as counterclockwise + right_motor = Motor(Port.B, Direction.COUNTERCLOCKWISE) + + # Initialize a motor with a gear train + robot_arm = Motor(Port.C, Direction.CLOCKWISE, [12, 36]) + + .. rubric:: Methods for motors without rotation sensors + + .. automethod:: pybricks.builtins.Motor.dc + + Example:: + + # Set the motor duty cycle to 75%. + example_motor.duty(75) + + .. rubric:: Methods for motors with rotation sensors + + .. automethod:: pybricks.builtins.Motor.angle + + .. automethod:: pybricks.builtins.Motor.reset_angle + + .. automethod:: pybricks.builtins.Motor.speed + + .. automethod:: pybricks.builtins.Motor.stop + + .. automethod:: pybricks.builtins.Motor.run + + .. automethod:: pybricks.builtins.Motor.run_time + + .. automethod:: pybricks.builtins.Motor.run_angle + + .. automethod:: pybricks.builtins.Motor.run_target + + .. rubric:: Advanced methods for motors with rotation sensors + + .. automethod:: pybricks.builtins.Motor.track_target + + Example:: + + # Initialize motor and timer + from math import sin + motor = Motor(Port.A) + watch = StopWatch() + amplitude = 90 + + # In a fast loop, compute a reference angle + # and make the motor track it. + while True: + # Get the time in seconds + seconds = watch.time()/1000 + # Compute a reference angle. This produces + # a sine wave that makes the motor move + # smoothly between -90 and +90 degrees. + angle_now = sin(seconds)*amplitude + # Make the motor track the given angle + motor.track_target(angle_now) + + .. automethod:: pybricks.builtins.Motor.stalled + + .. automethod:: pybricks.builtins.Motor.run_until_stalled + + .. automethod:: pybricks.builtins.Motor.set_dc_settings + + .. automethod:: pybricks.builtins.Motor.set_run_settings + + Example:: + + # Set the maximum speed to 200 deg/s and + # acceleration to 400 deg/s/s. + example_motor.set_run_settings(200, 400) + + # Make the motor run for 5 seconds. Even though the + # speed argument is 300 deg/s in this example, the + # motor will move at only 200 deg/s because of + # the settings above. + example_motor.run_time(300, 5000) + + .. automethod:: pybricks.builtins.Motor.set_pid_settings diff --git a/doc/api/pupdevices.rst b/doc/api/pupdevices.rst index 3922819..412db43 100644 --- a/doc/api/pupdevices.rst +++ b/doc/api/pupdevices.rst @@ -7,7 +7,8 @@ Motor ^^^^^^^^^^^^ -.. autoclass:: pybricks.pupdevices.Motor +.. autoclass:: pybricks._instances.Motor + :noindex: :no-members: Example:: @@ -48,51 +49,6 @@ Motor .. automethod:: pybricks.pupdevices.Motor.run_target - .. rubric:: Advanced methods for motors with rotation sensors - - .. automethod:: pybricks.pupdevices.Motor.track_target - - Example:: - - # Initialize motor and timer - from math import sin - motor = Motor(Port.A) - watch = StopWatch() - amplitude = 90 - - # In a fast loop, compute a reference angle - # and make the motor track it. - while True: - # Get the time in seconds - seconds = watch.time()/1000 - # Compute a reference angle. This produces - # a sine wave that makes the motor move - # smoothly between -90 and +90 degrees. - angle_now = sin(seconds)*amplitude - # Make the motor track the given angle - motor.track_target(angle_now) - - .. automethod:: pybricks.pupdevices.Motor.stalled - - .. automethod:: pybricks.pupdevices.Motor.run_until_stalled - - .. automethod:: pybricks.pupdevices.Motor.set_dc_settings - - .. automethod:: pybricks.pupdevices.Motor.set_run_settings - - Example:: - - # Set the maximum speed to 200 deg/s and - # acceleration to 400 deg/s/s. - example_motor.set_run_settings(200, 400) - - # Make the motor run for 5 seconds. Even though the - # speed argument is 300 deg/s in this example, the - # motor will move at only 200 deg/s because of - # the settings above. - example_motor.run_time(300, 5000) - - .. automethod:: pybricks.pupdevices.Motor.set_pid_settings Color and Distance Sensor ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/pybricks/_instances.py b/pybricks/_instances.py index e9c77c3..63e19e1 100644 --- a/pybricks/_instances.py +++ b/pybricks/_instances.py @@ -1,7 +1,8 @@ """Sphinx workaround to document instance attributes such as self.light""" -from .builtins import Speaker, Display, Battery, ColorLight, KeyPad, LightArray - +from .builtins import (Motor, Speaker, Display, Battery, ColorLight, + KeyPad, LightArray) +from .parameters import Direction from types import ModuleType @@ -26,3 +27,18 @@ battery = make_instance(Battery) speaker = make_instance(Speaker) display = make_instance(Display) + + +class Motor(Motor): + + def __init__(self, port, direction=Direction.CLOCKWISE): + """Motor(port, direction=Direction.CLOCKWISE) + + Create a motor instance. + + Arguments: + port (Port): Port to which the motor is connected. + direction (Direction): Positive speed direction + (*Default*: `Direction.CLOCKWISE`). + """ + pass