pybricks-api/pybricks/robotics.py at master · thesynman/pybricks-api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# SPDX-License-Identifier: MIT
# Copyright (c) 2018-2020 The Pybricks Authors

"""Robotics module for the Pybricks API."""

from ._common import Control as _Control


class DriveBase:
    """A robotic vehicle with two powered wheels and an optional support
    wheel or caster.

    By specifying the dimensions of your robot, this class
    makes it easy to drive a given distance in millimeters or turn by a given
    number of degrees.

    **Positive** distances and drive speeds mean
    driving **forward**. **Negative** means **backward**.

    **Positive** angles and turn rates mean turning **right**.
    **Negative** means **left**. So when viewed from the top,
    positive means clockwise and negative means counterclockwise.

    """

    distance_control = _Control()
    """The traveled distance and drive speed are controlled by a PID
    controller. You can use this attribute to change its settings.
    See :ref:`control` for an overview of available methods."""

    heading_control = _Control()
    """The robot turn angle and turn rate are controlled by a PID
    controller. You can use this attribute to change its settings.
    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)

        Arguments:
            left_motor (Motor):
                The motor that drives the left wheel.
            right_motor (Motor):
                The motor that drives the right wheel.
            wheel_diameter (:ref:`dimension`): Diameter of the wheels.
            axle_track (:ref:`dimension`): Distance between the points where
                both wheels touch the ground.
        """

    def drive(self, speed, turn_rate):
        """Starts 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.
            turn_rate (:ref:`speed`): Turn rate of the robot.
        """
        pass

    def stop(self):
        """Stops the robot by letting the motors spin freely."""
        pass

    def distance(self):
        """Gets the estimated driven distance.

        Returns:
            :ref:`distance`: Driven distance since last reset.
        """
        pass

    def angle(self):
        """Gets the estimated rotation angle of the drive base.

        Returns:
            :ref:`angle`: Accumulated angle since last reset.
        """
        pass

    def state(self):
        """Gets the state of the robot.

        This returns the current :meth:`.distance`, the drive speed, the
        :meth:`.angle`, and the turn rate.

        :returns: Distance, drive speed, angle, turn rate
        :rtype: (:ref:`distance`, :ref:`linspeed`, :ref:`angle`, :ref:`speed`)
        """
        pass

    def reset(self):
        """Resets the estimated driven distance and angle to 0."""
        pass

    def settings(self, straight_speed, straight_acceleration, turn_rate,
                 turn_acceleration):
        """Configures the speed and acceleration used
        by :meth:`.straight` and :meth:`.turn`.

        If you give no arguments, this returns the current values as a tuple.

        You can only change the settings while the robot is stopped. This is
        either before you begin driving or after you call :meth:`.stop`.

        Arguments:
            straight_speed (:ref:`linspeed`): Speed of the robot during
                :meth:`.straight`.
            straight_acceleration (:ref:`linacceleration`): Acceleration and
                deceleration of the robot at the start and end
                of :meth:`.straight`.
            turn_rate (:ref:`speed`): Turn rate of the robot
                during :meth:`.turn`.
            turn_acceleration (:ref:`acceleration`): Angular acceleration and
                deceleration of the robot at the start and end
                of :meth:`.turn`.
        """
        pass

    def straight(self, distance):
        """Drives straight for a given distance and then stops.

        Arguments:
            distance (:ref:`distance`): Distance to travel.
        """
        pass

    def turn(self, angle):
        """Turns in place by a given angle and then stops.

        Arguments:
            angle (:ref:`angle`): Angle of the turn.
        """
        pass