From 74231616153d334477f92db1ca9ff123768b34b1 Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Wed, 5 Feb 2020 16:44:50 +0100 Subject: [PATCH] api/robotics: simplify API drop methods that will not be implemented for next release and simplify descriptions of methods that will be implemented. --- doc/api/robotics.rst | 44 ++++++++++++++++------------ pybricks/robotics.py | 69 ++++++++++++++++---------------------------- 2 files changed, 50 insertions(+), 63 deletions(-) diff --git a/doc/api/robotics.rst b/doc/api/robotics.rst index 76bf411..4d0738a 100644 --- a/doc/api/robotics.rst +++ b/doc/api/robotics.rst @@ -8,35 +8,28 @@ .. autoclass:: pybricks.robotics.DriveBase :no-members: - .. automethod:: pybricks.robotics.DriveBase.drive + .. rubric:: Driving for a given distance or by an angle -.. .. autoclass:: pybricks.robotics.DriveBase - :no-members: - - .. rubric:: Automatic drive control + Use these commands to drive a given distance, or turn by a given angle. + + This is measured using the internal rotation sensors. Because wheels may + slip while moving, the traveled distance and angle are only estimates. .. automethod:: pybricks.robotics.DriveBase.straight .. automethod:: pybricks.robotics.DriveBase.turn - .. rubric:: Manual drive control - The methods :meth:`.drive`, :meth:`.arc`, and :meth:`.tank` make your - drive base move at a desired speed and and steering level. It keeps moving - until you stop it. For example, you can keep moving until an obstacle is - detected with a sensor. - Then use :meth:`.stop` to make your drive base stop. + .. rubric:: Drive forever - The only difference between :meth:`.drive`, :meth:`.arc`, and :meth:`.tank` - is how you specify the desired speed and steering. You can choose the - method which fits your application best. + Use :meth:`.drive` to begin driving at a desired speed and steering. + + It keeps going until you use :meth:`.stop` or change course by + using :meth:`.drive` again. For example, you can drive until a + sensor is triggered and then stop or turn around. .. automethod:: pybricks.robotics.DriveBase.drive - .. automethod:: pybricks.robotics.DriveBase.arc - - .. automethod:: pybricks.robotics.DriveBase.tank - .. automethod:: pybricks.robotics.DriveBase.stop .. rubric:: Measuring @@ -49,4 +42,17 @@ .. rubric:: Settings - .. automethod:: pybricks.robotics.DriveBase.set_drive_settings + .. automethod:: pybricks.robotics.DriveBase.settings + + .. rubric:: Advanced Settings + + The :meth:`.settings` method can be used to adjust the most commonly used + settings. It interacts with both of the attributes below to set the + desired speed and acceleration values. You can also adjust the control + settings manually using these attributes. + + .. autoattribute:: pybricks.robotics.DriveBase.distance_control + :annotation: + + .. autoattribute:: pybricks.robotics.DriveBase.heading_control + :annotation: diff --git a/pybricks/robotics.py b/pybricks/robotics.py index 10cefbd..2fc5b77 100644 --- a/pybricks/robotics.py +++ b/pybricks/robotics.py @@ -1,11 +1,23 @@ """Robotics module for the Pybricks API.""" from .parameters import Stop +from .builtins import Control class DriveBase(): - """Class representing a robotic vehicle with two powered wheels and - optional wheel caster(s).""" + """A robotic vehicle with two powered wheels and an optional support + wheel or caster.""" + + distance_control = Control() + """PID control is used to track the desired speed and travel the control + required distance You can change the behavior through this attribute. + See :ref:`control` for an overview of available methods.""" + + heading_control = Control() + """PID control is used to synchronize the wheel speed, + track the turn rate, and reach the turn angle. You can change the control + behavior through this attribute. See :ref:`control` for an overview of + available methods.""" def __init__(self, left_motor, right_motor, wheel_diameter, axle_track): """DriveBase(left_motor, right_motor, wheel_diameter, axle_track) @@ -18,54 +30,20 @@ class DriveBase(): wheel_diameter (:ref:`dimension`): Diameter of the wheels. axle_track (:ref:`dimension`): Distance between the midpoints of the two wheels. - """ - def drive(self, speed, steering): - """Start driving at the specified speed and turn rate, both measured at - the center point between the wheels of the robot. - - This method is useful in applications where you often change the speed - and steering. For example, when following a line using a light sensor. + def drive(self, drive_speed, turn_rate): + """Start driving at the specified speed and turn rate. Both values are + measured at the center point between the wheels of the robot. Arguments: - speed (:ref:`linspeed`): Speed of the robot. Positive is forward, + drive_speed (:ref:`linspeed`): Speed of the robot. Positive is forward, negative is backward. - steering (:ref:`speed`): Turn rate of the robot. Positive is to the + turn_rate (:ref:`speed`): Turn rate of the robot. Positive is to the right, negative is to the left. """ pass - def arc(self, speed, radius): - """Start driving along an arc/circle with a given radius. - - This method is useful in applications where you want to drive smoothly - around a known obstacle. Instead of going straight, turning, and then - straight again. For example, you can make it drive in a semi-circle - with a given radius and stop when a sensor detects an obstacle. - - Arguments: - speed (:ref:`linspeed`): Speed of the robot along the arc. - Positive is forward, negative is backward. - radius (:ref:`dimension`): Radius of the arc. A positive radius - value makes your robot go right. A negative radius value makes - it go left. - """ - pass - - def tank(self, left, right): - """Start driving with the given speed for each wheel. - - This method is useful in applications where you just want to set the - speed of the wheels or tank tracks, rather than the speed of the - whole drive base. - - Arguments: - left (:ref:`speed`): Speed of the left wheel. - right (:ref:`speed`): Speed of the right wheel. - """ - pass - def stop(self, stop_type=Stop.COAST): """Stop the robot. @@ -95,9 +73,12 @@ class DriveBase(): """Reset the estimated driven distance and angle to 0.""" pass - def set_drive_settings(self, drive_speed, drive_acceleration, turn_rate, - turn_acceleration, stop_type): - """Configure the default speed and acceleration. + def settings(self, drive_speed, drive_acceleration, turn_rate, + turn_acceleration, stop_type): + """Configure the acceleration and maximum speed used + by :meth:`.straight`, :meth:`.turn`, and :meth:`.drive`. + + If you give no arguments, this returns the current values as a tuple. Arguments: drive_speed (:ref:`linspeed`): Drive speed of the robot.