pybricks.robotics: Add Car class.

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## Unreleased
 
+## Added
+
+- Added `pybricks.robotics.Car` class.
+
 ### Changed
 
 - Changed `pybricks.robotics.DriveBase` icon to two wheels instead of steering

doc/common/extensions/blockimg.py

@@ -1,4 +1,3 @@
-import os
 import xml.etree.ElementTree as ET
 
 from docutils.parsers.rst import directives

doc/common/extensions/requirements-static.py

@@ -14,6 +14,7 @@ FEATURES_MEDIUM = FEATURES_SMALL | {
     "pybricks-iodevices",
     "stm32-extra",
     "stm32-float",
+    "pybricks-frozen",
 }
 
 # Large feature set.
@@ -31,12 +32,10 @@ HUB_FEATURES = {
 
 
 class PybricksRequirementsStaticDirective(Directive):
-
     required_arguments = 0
     optional_arguments = 10
 
     def run(self):
-
         # Copy required resources to static
         # CC BY-SA 4.0 via https://stackoverflow.com/a/63728208
         env = self.state.document.settings.env

doc/main/robotics.rst

@@ -85,6 +85,8 @@
 
     .. automethod:: pybricks.robotics.DriveBase.stalled
 
+    .. pybricks-requirements:: gyro
+
     .. rubric:: Driving with the gyro
 
     .. blockimg:: pybricks_blockDriveBaseUseGyro
@@ -175,16 +177,47 @@
 
         The :meth:`done` and :meth:`stalled` methods have been moved.
 
+.. pybricks-requirements:: pybricks-frozen
 
-.. pybricks-requirements:: gyro
+.. blockimg:: pybricks_variables_set_car
+
+.. autoclass:: pybricks.robotics.Car
+    :no-members:
+
+    .. blockimg:: pybricks_blockCarSteer
+
+    .. automethod:: pybricks.robotics.Car.steer
+
+    .. blockimg:: pybricks_blockCarDrive_car_drive_at_power
+
+    .. automethod:: pybricks.robotics.Car.drive_power
+
+    .. blockimg:: pybricks_blockCarDrive_car_drive_at_speed
+
+    .. automethod:: pybricks.robotics.Car.drive_speed
 
 Examples
 -------------------
 
-Driving straight and turning in place
-**********************************************
+Driving straight and turning in place with a drive base
+********************************************************
 
-The following program shows the basics of driving and turning.
+This program shows the basics of driving and turning.
 
 .. literalinclude::
     ../../examples/pup/robotics/drivebase_basics.py
+
+Remote controlling a car with front wheel steering
+**************************************************
+
+This program shows how you can drive a car with front wheel steering
+using the :class:`remote control <pybricks.pupdevices.Remote>`.
+
+In this program, the ports match those of the `LEGO Technic 42099 Off-Roader
+<https://pybricks.com/projects/sets/technic/42099-off-roader/>`_, but you can
+use any other car with front wheel steering. If your vehicle has only one
+drive motor, you can use a single motor instead of a tuple of the motors used
+below.
+
+.. literalinclude::
+    ../../examples/pup/robotics/car_remote.py

examples/pup/robotics/car_remote.py

@@ -0,0 +1,40 @@
+from pybricks.parameters import Direction, Port, Button
+from pybricks.pupdevices import Motor, Remote
+from pybricks.robotics import Car
+from pybricks.tools import wait
+
+# Set up motors.
+front = Motor(Port.A, Direction.COUNTERCLOCKWISE)
+rear = Motor(Port.B, Direction.COUNTERCLOCKWISE)
+steer = Motor(Port.C, Direction.CLOCKWISE)
+
+# Connect to the remote.
+remote = Remote()
+
+# Set up the car.
+car = Car(steer, [front, rear])
+
+# The main program starts here.
+while True:
+    # Read remote state.
+    pressed = remote.buttons.pressed()
+
+    # Steer using the left pad. Steering is the percentage
+    # of the angle determined while initializing.
+    steering = 0
+    if Button.LEFT_PLUS in pressed:
+        steering += 100
+    elif Button.LEFT_MINUS in pressed:
+        steering -= 100
+    car.steer(steering)
+
+    # Drive using the right pad.
+    power = 0
+    if Button.RIGHT_PLUS in pressed:
+        power += 100
+    elif Button.RIGHT_MINUS in pressed:
+        power -= 100
+    car.drive_power(power)
+
+    # Wait briefly.
+    wait(10)

jedi/tests/test_complete_import.py

@@ -148,7 +148,7 @@ def test_from_pybricks_pupdevices_import():
 def test_from_pybricks_robotics_import():
     code = "from pybricks.robotics import "
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
-    assert [c["insertText"] for c in completions] == ["DriveBase"]
+    assert [c["insertText"] for c in completions] == ["Car", "DriveBase"]
 
 
 def test_from_pybricks_tools_import():

src/pybricks/robotics.py

@@ -241,6 +241,67 @@ class DriveBase:
         """
 
 
+class Car:
+    """A vehicle with one steering motor, and one or more motors for driving.
+
+    When you use this class, the steering motor will automatically find the
+    center position. This also determines which angle corresponds to 100%
+    steering.
+    """
+
+    def __init__(self, steering_motor: Motor, drive_motors: Motor | Tuple[Motor, ...]):
+        """Car(steering_motor, drive_motors)
+
+        Arguments:
+            steering_motor (Motor):
+                The motor that steers the front wheels.
+            drive_motors (Motor): The motor that drives the wheels. Use a tuple
+                for multiple motors.
+        """
+
+    def steer(self, percentage: Number) -> None:
+        """steer(percentage)
+
+        Steers the front wheels by a given amount. For 100% steering, it
+        steers right by the angle that was determined on initialization.
+        For -100% steering, it steers left and 0% means straight.
+
+        Arguments:
+            steering (Number, %): Amount to steer the front wheels.
+        """
+
+    def drive_power(self, power: Number) -> None:
+        """drive_power(power)
+
+        Drives the car at a given "power" level, as a percentage of the
+        battery voltage. Positive values drive forward, negative values drive
+        backward.
+
+        For ``power`` values below 30%, the car will coast the wheels in order
+        to roll out smoothly instead of braking abruptly.
+
+        This command is useful for remote control applications where you want
+        instant response to button presses or joystick movements.
+
+        Arguments:
+            speed (Number, %): Speed of the car.
+        """
+
+    def drive_speed(self, speed: Number) -> None:
+        """drive_speed(speed)
+
+        Drives the car at a given motor speed. Positive values drive forward,
+        negative values drive backward.
+
+        This command is useful for more precise driving with gentle
+        acceleration and deceleration. This automatically increases the power
+        to maintain speed as you drive across obstacles.
+
+        Arguments:
+            speed (Number, deg/s): Angular velocity of the drive motors.
+        """
+
+
 # HACK: hide from jedi
 if TYPE_CHECKING:
     del Motor