Merge branch 'master' of https://github.com/LEGO-Robotics/Pybricks-API

.readthedocs.yml

@@ -19,7 +19,6 @@ build:
 # Build documentation in the doc/main/ directory with Sphinx
 sphinx:
   configuration: doc/main/conf.py
-  fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF
 formats:

CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## Unreleased
 
+## 3.3.0b9 - 2023-10-26
+
+### Changed
+- Changed the beta feature for using the hub's gyro. Gyro control can now be
+  toggled using `use_gyro` instead of using a separate `GyroDriveBase` class.
+- Documentation updates to match firmware 3.3.0b5--3.3.0b9 updates.
+
+## Added
+- Added `set` to `ubuiltins` module.
+- Basic multitasking docs.
+- Awaitable keyword for awaitable methods and functions.
+
 ## 3.3.0b5 - 2023-05-16
 
 ### Added

doc/common/conf.py

@@ -145,13 +145,10 @@
 
 # -- Options for HTML output ----------------------------------------------
 
-if ON_RTD:
-    html_theme = "default"
-else:
-    import sphinx_rtd_theme
+import sphinx_rtd_theme
 
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 html_context = {
     "disclaimer": _DISCLAIMER,
@@ -343,13 +340,16 @@ def on_missing_reference(
         "Ω",
         "N",
     ]:
-
-        # If they match on raw source, we are dealing with argument types.
-        if unit == contnode.rawsource:
-            # Return as-is to suppress missing cross reference warning. We
-            # could make this more fancy by returning an xref node that links
-            # to the signals page.
-            return contnode
+        try:
+            # If they match on raw source, we are dealing with argument types.
+            if unit == contnode.rawsource:
+                # Return as-is to suppress missing cross reference warning. We
+                # could make this more fancy by returning an xref node that links
+                # to the signals page.
+                return contnode
+
+        except AttributeError:
+            pass
 
         # Return types are denoted as "int: deg"
         try:

doc/main/hubs/cityhub.rst

@@ -21,8 +21,7 @@ City Hub
 
     .. rubric:: Using connectionless Bluetooth messaging
 
-    ``ble.broadcast()`` does not work on ``CityHub`` due to a bug in the
-    Bluetooth chip firmware.
+    .. automethod:: pybricks.hubs::CityHub.ble.broadcast
 
     .. automethod:: pybricks.hubs::CityHub.ble.observe
 
@@ -85,6 +84,12 @@ Creating light animations
 Bluetooth examples
 ------------------
 
+Broadcasting data to other hubs
+*******************************
+
+.. literalinclude::
+    ../../../examples/pup/hub_common/build/ble_broadcast_cityhub.py
+
 Observing data from other hubs
 ******************************
 

doc/main/micropython/builtins.rst

@@ -72,6 +72,10 @@ Sequences
 
 .. pybricks-requirements:: stm32-extra
 
+.. autoclass:: ubuiltins.set
+
+.. pybricks-requirements:: stm32-extra
+
 .. autoclass:: ubuiltins.slice
 
 .. pybricks-requirements::

doc/main/robotics.rst

@@ -39,6 +39,8 @@
 
     .. automethod:: pybricks.robotics.DriveBase.stop
 
+    .. automethod:: pybricks.robotics.DriveBase.brake
+
     .. rubric:: Measuring
 
     .. automethod:: pybricks.robotics.DriveBase.distance
@@ -51,6 +53,33 @@
 
     .. automethod:: pybricks.robotics.DriveBase.stalled
 
+    .. rubric:: Driving with the gyro
+
+    .. automethod:: pybricks.robotics.DriveBase.use_gyro
+
+    If your hub is not mounted flat in your robot, make sure to specify
+    the ``top_side`` and ``front_side`` parameters when you initialize the
+    :class:`PrimeHub() <pybricks.hubs.PrimeHub>`,
+    :class:`InventorHub() <pybricks.hubs.PrimeHub>`,
+    :class:`EssentialHub() <pybricks.hubs.EssentialHub>`, or
+    :class:`TechnicHub() <pybricks.hubs.TechnicHub>`. This way your robot
+    knows which rotation to measure when turning.
+
+    The gyro in each hub is a bit different, which can cause it to be a few
+    degrees off for big turns, or many small turns in the same
+    direction. For example, you may need to use
+    :meth:`turn(357) <pybricks.robotics.DriveBase.turn>` or
+    :meth:`turn(362) <pybricks.robotics.DriveBase.turn>`
+    on your robot to make a full turn.
+
+    By default, this class tries to maintain the robot's position after a move
+    completes. This means the wheels will spin if you pick the robot up, in an
+    effort to maintain its heading angle. To avoid this, you can choose
+    ``then=Stop.COAST`` in your last
+    :meth:`straight <pybricks.robotics.DriveBase.straight>`,
+    :meth:`turn <pybricks.robotics.DriveBase.turn>`, or
+    :meth:`curve <pybricks.robotics.DriveBase.curve>` command.
+
     .. _measuring:
 
     .. rubric:: Measuring and validating the robot dimensions
@@ -115,34 +144,6 @@
 
 .. pybricks-requirements:: gyro
 
-.. class:: GyroDriveBase
-
-    This class works just like the :class:`DriveBase`, but it uses the hub's
-    built-in gyroscope to drive straight and turn more accurately.
-
-    If your hub is not mounted flat in your robot, make sure to specify
-    the ``top_side`` and ``front_side`` parameters when you initialize the
-    :class:`PrimeHub() <pybricks.hubs.PrimeHub>`,
-    :class:`InventorHub() <pybricks.hubs.PrimeHub>`,
-    :class:`EssentialHub() <pybricks.hubs.EssentialHub>`, or
-    :class:`TechnicHub() <pybricks.hubs.TechnicHub>`. This way your robot
-    knows which rotation to measure when turning.
-
-    The gyro in each hub is a bit different, which can cause it to be a few
-    degrees off for big turns, or many small turns in the same
-    direction. For example, you may need to use
-    :meth:`turn(357) <pybricks.robotics.DriveBase.turn>` or
-    :meth:`turn(362) <pybricks.robotics.DriveBase.turn>`
-    on your robot to make a full turn.
-
-    By default, this class tries to maintain the robot's position after a move
-    completes. This means the wheels will spin if you pick the robot up, in an
-    effort to maintain its heading angle. To avoid this, you can choose
-    ``then=Stop.COAST`` in your last
-    :meth:`straight <pybricks.robotics.DriveBase.straight>`,
-    :meth:`turn <pybricks.robotics.DriveBase.turn>`, or
-    :meth:`curve <pybricks.robotics.DriveBase.curve>` command.
-
 Examples
 -------------------
 
@@ -151,8 +152,5 @@ Driving straight and turning in place
 
 The following program shows the basics of driving and turning.
 
-To use the built-in gyro, just replace the two occurrences of
-:class:`DriveBase` with :class:`GyroDriveBase`.
-
 .. literalinclude::
     ../../examples/pup/robotics/drivebase_basics.py

doc/main/tools/index.rst

@@ -22,6 +22,18 @@ Timing tools
 
     .. automethod:: pybricks.tools.StopWatch.reset
 
+Input tools
+-----------
+
+.. autofunction:: pybricks.tools.read_input_byte
+
+.. pybricks-requirements:: light-matrix
+
+.. autofunction:: pybricks.tools.hub_menu
+
+.. literalinclude::
+    ../../../examples/pup/tools/hub_menu.py
+
 Linear algebra tools
 --------------------
 
@@ -43,3 +55,35 @@ Linear algebra tools
 .. autofunction:: pybricks.tools.vector
 
 .. autofunction:: pybricks.tools.cross
+
+Multitasking
+--------------------
+
+.. versionadded:: 3.3
+
+Pybricks supports cooperative multitasking using the ``async`` and ``await``
+keywords. This allows operations that normally take some time to complete to
+run in parallel with other operations.
+
+.. autofunction:: pybricks.tools.multitask
+
+.. autofunction:: pybricks.tools.run_task
+
+The following example shows how to use multitasking to make a robot drive
+forward, then turn and move a gripper at the same time, and then drive
+backward.
+
+.. literalinclude::
+    ../../../examples/pup/robotics/drivebase_async.py
+
+.. class:: coroutine
+
+.. class:: await
+
+Whenever you see a function or method prefixed by ``await``, this means that
+it supports multitasking. When running a coroutine with ``run_task``, all
+methods and functions prefixed by ``await`` will act as coroutines.
+
+If you don't use multitasking, you can ignore the ``await`` keyword and write
+programs as usual. Specifically, when ``run_task`` is not used, functions
+prefixed by ``await`` will act as normal functions.

examples/pup/hub_common/ble_broadcast.py

@@ -17,7 +17,8 @@
     right_angle = right_motor.angle()
 
     # Set the broadcast data and start broadcasting if not already doing so.
-    hub.ble.broadcast(left_angle, right_angle)
+    data = (left_angle, right_angle)
+    hub.ble.broadcast(data)
 
     # Broadcasts are only sent every 100 milliseconds, so there is no reason
     # to call the broadcast() method more often than that.

examples/pup/hub_common/ble_observe.py

@@ -26,8 +26,7 @@
         # *data* contains the same values in the same order
         # that were passed to hub.ble.broadcast() on the
         # other hub.
-        left_angle = data[0]
-        right_angle = data[1]
+        left_angle, right_angle = data
 
         # Make the motors on this hub mirror the position of the
         # motors on the other hub.

examples/pup/robotics/drivebase_async.py

@@ -0,0 +1,27 @@
+from pybricks.pupdevices import Motor
+from pybricks.parameters import Direction, Port
+from pybricks.robotics import DriveBase
+from pybricks.tools import multitask, run_task
+
+# Set up all devices.
+left = Motor(Port.A, Direction.COUNTERCLOCKWISE)
+right = Motor(Port.B)
+gripper = Motor(Port.C)
+drive_base = DriveBase(left, right, 56, 114)
+
+
+# Move the gripper up and down.
+async def move_gripper():
+    await gripper.run_angle(500, -90)
+    await gripper.run_angle(500, 90)
+
+
+# Drive forward, turn move gripper at the same time, and drive backward.
+async def main():
+    await drive_base.straight(250)
+    await multitask(drive_base.turn(90), move_gripper())
+    await drive_base.straight(-250)
+
+
+# Runs the main program from start to finish.
+run_task(main())

examples/pup/robotics/drivebase_basics.py

@@ -11,6 +11,9 @@
 # The distance between the two wheel-ground contact points is 112mm.
 drive_base = DriveBase(left_motor, right_motor, wheel_diameter=56, axle_track=112)
 
+# Optionally, uncomment the line below to use the gyro for improved accuracy.
+# drive_base.use_gyro(True)
+
 # Drive forward by 500mm (half a meter).
 drive_base.straight(500)
 

examples/pup/tools/hub_menu.py

@@ -0,0 +1,16 @@
+from pybricks.tools import hub_menu
+
+# This example assumes that you have three other programs in Pybricks Code,
+# called "fly_mission", "drive_mission", and "zigzag". This example creates a
+# menu that lets you pick which one to run.
+
+# Choose a letter.
+selected = hub_menu("F", "D", "Z")
+
+# Based on the selection, run a program.
+if selected == "F":
+    import fly_mission
+elif selected == "D":
+    import drive_mission
+elif selected == "Z":
+    import zigzag

jedi/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## Unreleased
 
+## 1.10.0 - 2023-10-26
+
+### Changed
+- Updated `pybricks` package to v3.3.0b9.
+
 ## 1.9.0 - 2023-05-16
 
 ### Changed