@pybricks/ide-docs/v2.20.0

This cuts the total build from 527 to 156 files,
which is considerably fewer requests when loading
this inside Pybricks Code.

See https://github.com/pybricks/support/issues/1559

CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## Unreleased
 
+## 3.6.b5 - 2024-04-11
+
+### Changed
+
+- Update API for firmware 3.6.0b5. See upstream changelog for details.
+
+## 3.5.0 - 2024-04-11
+
+### Changed
+- Bump version to 3.5.0 without additional changes.
+
 ## 3.5.0b2 - 2024-04-05
 
 ### Added

doc/common/_static/css/blocks.css

@@ -1,3 +1,11 @@
-.block-image {
-    margin-top: 10px;
+.svg-container {
+    display: inline-block;
+    width: 100%;
+    height: auto;
+}
+
+.svg-container svg {
+    position: relative;
+    height: auto;
+    max-width: 100%;
 }

doc/common/conf.py

@@ -151,6 +151,9 @@ import sphinx_rtd_theme
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
+html_show_sourcelink = False
+html_copy_source = False
+
 html_context = {
     "disclaimer": _DISCLAIMER,
 }
@@ -261,6 +264,7 @@ exclude_patterns = [
     "messaging.rst",
     "nxtdevices.rst",
     "tools/datalog.rst",
+    "*.rst.txt",
 ]
 
 

doc/common/extensions/blockimg.py

@@ -1,56 +1,38 @@
 import xml.etree.ElementTree as ET
-
-from docutils.parsers.rst import directives
-from docutils.parsers.rst.directives.images import Image
-from docutils.nodes import image, paragraph
+from docutils.parsers.rst import Directive, directives
+from docutils import nodes
 from pathlib import Path
 
 SPHINX_IMAGE_PATH = "blockimg"
 
-SVG_SCALE = 0.9
 
-
-def get_svg_size(file_path):
-    tree = ET.parse(file_path)
-    root = tree.getroot()
-
-    width = root.attrib.get("width")
-    height = root.attrib.get("height")
-
-    return float(width), float(height)
+def get_svg_content(file_path):
+    with open(file_path, "r", encoding="utf-8") as file:
+        return file.read()
 
 
 # Global variable to store the app object
 app = None
 
 
-class BlockImageDirective(Image):
-    option_spec = Image.option_spec.copy()
-    option_spec["stack"] = directives.flag
+class BlockImageDirective(Directive):
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
 
     def run(self):
         # Adjust the image path
         file_name = self.arguments[0] + ".svg"
-        self.arguments[0] = "/" + SPHINX_IMAGE_PATH + "/" + file_name
-        path = Path(app.srcdir) / SPHINX_IMAGE_PATH / file_name
+        file_path = Path(app.srcdir) / SPHINX_IMAGE_PATH / file_name
 
-        # Set it to the scaled SVG size unless width explicitly set.
-        if self.options.get("width") is None:
-            width, height = get_svg_size(path)
-            self.options["width"] = str(round(width * SVG_SCALE)) + "px"
-            self.options["height"] = str(round(height * SVG_SCALE)) + "px"
+        # Read the SVG content
+        svg_content = get_svg_content(file_path)
 
-        # Call the parent class's run method
-        nodes = super().run()
+        # Create a raw HTML node with the SVG content
+        raw_html = f'<div class="svg-container">{svg_content}</div>'
+        raw_node = nodes.raw("", raw_html, format="html")
 
-        # Wrap each image node in a paragraph node
-        for i, node in enumerate(nodes):
-            if isinstance(node, image):
-                if "stack" not in self.options:
-                    node["classes"].append("block-image")
-                nodes[i] = paragraph("", "", node)
-
-        return nodes
+        return [raw_node]
 
 
 def setup(apparg):

doc/main/hubs/cityhub.rst

@@ -8,7 +8,6 @@ City Hub
 .. blockimg:: pybricks_variables_set_city_hub_option0
 
 .. blockimg:: pybricks_variables_set_city_hub_option3
-    :stack:
 
 .. autoclass:: pybricks.hubs.CityHub
     :no-members:
@@ -60,23 +59,21 @@ City Hub
     .. blockimg:: pybricks_blockHubStopButton_CityHub
 
     .. blockimg:: pybricks_blockHubStopButton_CityHub_none
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::CityHub.system.set_stop_button
 
-    .. automethod:: pybricks.hubs::CityHub.system.name
-
     .. automethod:: pybricks.hubs::CityHub.system.storage
 
         You can store up to 128 bytes of data on this hub. The data is cleared
         when you update the Pybricks firmware or if you restore the original
         firmware.
 
+    .. automethod:: pybricks.hubs::CityHub.system.reset_storage
+
     .. blockimg:: pybricks_blockHubShutdown_CityHub
 
     .. automethod:: pybricks.hubs::CityHub.system.shutdown
 
-    .. automethod:: pybricks.hubs::CityHub.system.reset_reason
 
 Status light examples
 ---------------------

doc/main/hubs/essentialhub.rst

@@ -9,7 +9,6 @@ Essential Hub
 .. blockimg:: pybricks_variables_set_essential_hub_option0
 
 .. blockimg:: pybricks_variables_set_essential_hub_option4
-    :stack:
 
 .. autoclass:: pybricks.hubs.EssentialHub
     :no-members:
@@ -37,12 +36,18 @@ Essential Hub
     .. blockimg:: pybricks_blockHubStopButton_EssentialHub
 
     .. blockimg:: pybricks_blockHubStopButton_EssentialHub_none
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::EssentialHub.system.set_stop_button
 
     .. rubric:: Using the IMU
 
+    .. versionchanged:: 3.6
+
+        The methods below now return calibrated data by default. Depending on
+        the method used, this combines data from the accelerometer, gyroscope,
+        with your calibration values. Use ``calibrated=False`` where applicable
+        to get the raw data you got before.
+
     .. blockimg:: pybricks_blockImuStatus_EssentialHub_ready
 
     .. automethod:: pybricks.hubs::EssentialHub.imu.ready
@@ -58,8 +63,7 @@ Essential Hub
     .. blockimg:: pybricks_blockTilt_EssentialHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_EssentialHub_imu.tilt.roll
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::EssentialHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_EssentialHub
@@ -84,6 +88,12 @@ Essential Hub
 
     .. automethod:: pybricks.hubs::EssentialHub.imu.orientation
 
+    .. blockimg:: pybricks_blockImuConfigure_EssentialHub_imu.settings_heading_correction
+    
+    .. blockimg:: pybricks_blockImuConfigure_EssentialHub_imu.settings_angular_velocity_threshold
+    
+    .. blockimg:: pybricks_blockImuConfigure_EssentialHub_imu.settings_acceleration_threshold
+    
     .. automethod:: pybricks.hubs::EssentialHub.imu.settings
 
     .. rubric:: Using connectionless Bluetooth messaging
@@ -120,18 +130,19 @@ Essential Hub
 
     .. rubric:: System control
 
-    .. automethod:: pybricks.hubs::EssentialHub.system.name
+    .. automethod:: pybricks.hubs::EssentialHub.system.info
 
     .. automethod:: pybricks.hubs::EssentialHub.system.storage
 
-        You can store up to 512 bytes of data on this hub.
+        You can store up to 512 bytes of data on this hub. The data is cleared
+        when you update the Pybricks firmware.
+
+    .. automethod:: pybricks.hubs::EssentialHub.system.reset_storage
 
     .. blockimg:: pybricks_blockHubShutdown_EssentialHub
 
     .. automethod:: pybricks.hubs::EssentialHub.system.shutdown
 
-    .. automethod:: pybricks.hubs::EssentialHub.system.reset_reason
-
 Status light examples
 ---------------------
 

doc/main/hubs/movehub.rst

@@ -11,7 +11,6 @@ Move Hub
 .. blockimg:: pybricks_variables_set_move_hub_option0
 
 .. blockimg:: pybricks_variables_set_move_hub_option4
-    :stack:
 
 .. autoclass:: pybricks.hubs.MoveHub
     :no-members:
@@ -39,8 +38,7 @@ Move Hub
     .. blockimg:: pybricks_blockTilt_MoveHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_MoveHub_imu.tilt.roll
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::MoveHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_MoveHub
@@ -84,24 +82,21 @@ Move Hub
     .. blockimg:: pybricks_blockHubStopButton_MoveHub
 
     .. blockimg:: pybricks_blockHubStopButton_MoveHub_none
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::MoveHub.system.set_stop_button
 
-    .. automethod:: pybricks.hubs::MoveHub.system.name
-
     .. automethod:: pybricks.hubs::MoveHub.system.storage
 
         You can store up to 128 bytes of data on this hub. The data is cleared
         when you update the Pybricks firmware or if you restore the original
         firmware.
 
+    .. automethod:: pybricks.hubs::MoveHub.system.reset_storage
+
     .. blockimg:: pybricks_blockHubShutdown_MoveHub
 
     .. automethod:: pybricks.hubs::MoveHub.system.shutdown
 
-    .. automethod:: pybricks.hubs::MoveHub.system.reset_reason
-
 Status light examples
 ---------------------
 

doc/main/hubs/primehub.rst

@@ -9,7 +9,6 @@ Prime Hub / Inventor Hub
 .. blockimg:: pybricks_variables_set_inventor_hub_option0
 
 .. blockimg:: pybricks_variables_set_inventor_hub_option4
-    :stack:
 
 .. class:: InventorHub
 
@@ -21,7 +20,6 @@ Prime Hub / Inventor Hub
 .. blockimg:: pybricks_variables_set_prime_hub_option0
 
 .. blockimg:: pybricks_variables_set_prime_hub_option4
-    :stack:
 
 .. autoclass:: pybricks.hubs.PrimeHub
     :no-members:
@@ -84,12 +82,18 @@ Prime Hub / Inventor Hub
     .. blockimg:: pybricks_blockHubStopButton_PrimeHub
 
     .. blockimg:: pybricks_blockHubStopButton_PrimeHub_none
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::PrimeHub.system.set_stop_button
 
     .. rubric:: Using the IMU
 
+    .. versionchanged:: 3.6
+
+        The methods below now return calibrated data by default. Depending on
+        the method used, this combines data from the accelerometer, gyroscope,
+        with your calibration values. Use ``calibrated=False`` where applicable
+        to get the raw data you got before.
+
     .. blockimg:: pybricks_blockImuStatus_PrimeHub_ready
 
     .. automethod:: pybricks.hubs::PrimeHub.imu.ready
@@ -105,8 +109,7 @@ Prime Hub / Inventor Hub
     .. blockimg:: pybricks_blockTilt_PrimeHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_PrimeHub_imu.tilt.roll
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::PrimeHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_PrimeHub
@@ -131,6 +134,12 @@ Prime Hub / Inventor Hub
 
     .. automethod:: pybricks.hubs::PrimeHub.imu.orientation
 
+    .. blockimg:: pybricks_blockImuConfigure_PrimeHub_imu.settings_heading_correction
+    
+    .. blockimg:: pybricks_blockImuConfigure_PrimeHub_imu.settings_angular_velocity_threshold
+    
+    .. blockimg:: pybricks_blockImuConfigure_PrimeHub_imu.settings_acceleration_threshold
+    
     .. automethod:: pybricks.hubs::PrimeHub.imu.settings
 
     .. rubric:: Using the speaker
@@ -175,19 +184,22 @@ Prime Hub / Inventor Hub
 
     .. rubric:: System control
 
-    .. automethod:: pybricks.hubs::PrimeHub.system.name
+    .. automethod:: pybricks.hubs::PrimeHub.system.info
 
     .. automethod:: pybricks.hubs::PrimeHub.system.storage
 
-        You can store up to 512 bytes of data on this hub.
+        You can store up to 512 bytes of data on this hub. The data is cleared
+        when you update the Pybricks firmware.
+
+    .. automethod:: pybricks.hubs::PrimeHub.system.reset_storage
 
     .. blockimg:: pybricks_blockHubShutdown_PrimeHub
 
     .. automethod:: pybricks.hubs::PrimeHub.system.shutdown
 
-    .. automethod:: pybricks.hubs::PrimeHub.system.reset_reason
+.. note::
 
-.. note:: The examples below use the ``PrimeHub`` class. The examples work fine
+        The examples below use the ``PrimeHub`` class. The examples work fine
         on both hubs because they are the identical. If you prefer, you can
         change this to ``InventorHub``.
 

doc/main/hubs/technichub.rst

@@ -9,7 +9,6 @@ Technic Hub
 .. blockimg:: pybricks_variables_set_technic_hub_option0
 
 .. blockimg:: pybricks_variables_set_technic_hub_option4
-    :stack:
 
 .. autoclass:: pybricks.hubs.TechnicHub
     :no-members:
@@ -30,6 +29,13 @@ Technic Hub
 
     .. rubric:: Using the IMU
 
+    .. versionchanged:: 3.6
+
+        The methods below now return calibrated data by default. Depending on
+        the method used, this combines data from the accelerometer, gyroscope,
+        with your calibration values. Use ``calibrated=False`` where applicable
+        to get the raw data you got before.
+
     .. blockimg:: pybricks_blockImuStatus_TechnicHub_ready
 
     .. automethod:: pybricks.hubs::TechnicHub.imu.ready
@@ -45,8 +51,7 @@ Technic Hub
     .. blockimg:: pybricks_blockTilt_TechnicHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_TechnicHub_imu.tilt.roll
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::TechnicHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_TechnicHub
@@ -71,6 +76,12 @@ Technic Hub
 
     .. automethod:: pybricks.hubs::TechnicHub.imu.orientation
 
+    .. blockimg:: pybricks_blockImuConfigure_TechnicHub_imu.settings_heading_correction
+    
+    .. blockimg:: pybricks_blockImuConfigure_TechnicHub_imu.settings_angular_velocity_threshold
+    
+    .. blockimg:: pybricks_blockImuConfigure_TechnicHub_imu.settings_acceleration_threshold
+    
     .. automethod:: pybricks.hubs::TechnicHub.imu.settings
 
     .. rubric:: Using connectionless Bluetooth messaging
@@ -106,24 +117,21 @@ Technic Hub
     .. blockimg:: pybricks_blockHubStopButton_TechnicHub
 
     .. blockimg:: pybricks_blockHubStopButton_TechnicHub_none
-        :stack:
-
+    
     .. automethod:: pybricks.hubs::TechnicHub.system.set_stop_button
 
-    .. automethod:: pybricks.hubs::TechnicHub.system.name
-
     .. automethod:: pybricks.hubs::TechnicHub.system.storage
 
         You can store up to 128 bytes of data on this hub. The data is cleared
         when you update the Pybricks firmware or if you restore the original
         firmware.
 
+    .. automethod:: pybricks.hubs::TechnicHub.system.reset_storage
+
     .. blockimg:: pybricks_blockHubShutdown_TechnicHub
 
     .. automethod:: pybricks.hubs::TechnicHub.system.shutdown
 
-    .. automethod:: pybricks.hubs::TechnicHub.system.reset_reason
-
 Status light examples
 ---------------------
 

doc/main/iodevices/lwp3device.rst

@@ -1,3 +1,5 @@
+.. pybricks-requirements:: pybricks-iodevices
+
 LEGO Wireless Protocol v3 device
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/main/iodevices/xboxcontroller.rst

@@ -30,22 +30,19 @@ Xbox Controller
   .. blockimg:: pybricks_blockJoystickValue_lj_x
 
   .. blockimg:: pybricks_blockJoystickValue_lj_y
-      :stack:
-
+  
   .. automethod:: pybricks.iodevices::XboxController.joystick_left
 
   .. blockimg:: pybricks_blockJoystickValue_rj_x
 
   .. blockimg:: pybricks_blockJoystickValue_rj_y
-      :stack:
-
+  
   .. automethod:: pybricks.iodevices::XboxController.joystick_right
 
   .. blockimg:: pybricks_blockJoystickValue_lt
 
   .. blockimg:: pybricks_blockJoystickValue_rt
-      :stack:
-
+  
   .. automethod:: pybricks.iodevices::XboxController.triggers
 
   .. blockimg:: pybricks_blockJoystickValue_dpad
@@ -59,11 +56,9 @@ Xbox Controller
   .. blockimg:: pybricks_blockGamepadRumble_default
 
   .. blockimg:: pybricks_blockGamepadRumble_default_with_list
-      :stack:
-
+  
   .. blockimg:: pybricks_blockGamepadRumble_with_options
-      :stack:
-
+  
   .. automethod:: pybricks.iodevices::XboxController.rumble
 
 .. _xbox-controller-pairing:

doc/main/micropython/builtins.rst

@@ -79,52 +79,36 @@ Sequences
 .. pybricks-requirements::
 
 .. blockimg:: pybricks_blockListCreate_list_empty
-    :stack:
 
 .. blockimg:: pybricks_blockListCreate_list_3
-    :stack:
 
 .. blockimg:: pybricks_blockListUnpack
-    :stack:
 
 .. blockimg:: pybricks_blockListGet_list_get_first
-    :stack:
 
 .. blockimg:: pybricks_blockListGet_list_get_index
-    :stack:
 
 .. blockimg:: pybricks_blockListGet_list_get_last
-    :stack:
 
 .. blockimg:: pybricks_blockListGet_list_get_random
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_insert_first
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_insert_index
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_insert_last
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_remove_first
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_remove_index
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_remove_last
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_set_first
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_set_index
-    :stack:
 
 .. blockimg:: pybricks_blockListSet_list_set_last
-    :stack:
 
 .. autoclass:: ubuiltins.list
 
@@ -262,11 +246,11 @@ See also :mod:`umath` for floating point math operations.
 Runtime functions
 -------------------------
 
-.. pybricks-requirements::
+.. pybricks-requirements:: stm32-extra
 
 .. autofunction:: ubuiltins.eval
 
-.. pybricks-requirements::
+.. pybricks-requirements:: stm32-extra
 
 .. autofunction:: ubuiltins.exec
 

doc/main/pupdevices/colorsensor.rst

@@ -42,8 +42,7 @@ Color Sensor
     .. blockimg:: pybricks_blockLightOn_colorsensor_on
 
     .. blockimg:: pybricks_blockLightOn_colorsensor_on_list
-        :stack:
-
+    
     .. automethod:: pybricks.pupdevices::ColorSensor.lights.on
 
     .. blockimg:: pybricks_blockLightOn_colorsensor_off

doc/main/pupdevices/motor.rst

@@ -105,11 +105,9 @@ Motors with rotation sensors
     .. blockimg:: pybricks_blockMotorConfigure_motor_max_speed
 
     .. blockimg:: pybricks_blockMotorConfigure_motor_acceleration
-        :stack:
-
+    
     .. blockimg:: pybricks_blockMotorConfigure_motor_max_torque
-        :stack:
-
+    
     .. automethod:: pybricks.pupdevices.Motor.control.limits
 
     .. pybricks-requirements:: pybricks-common-control

doc/main/pupdevices/remote.rst

@@ -9,7 +9,6 @@ Remote Control
 .. blockimg:: pybricks_variables_set_remote_connect_any
 
 .. blockimg:: pybricks_variables_set_remote_connect_name
-    :stack:
 
 .. autoclass:: pybricks.pupdevices.Remote
   :no-members:

doc/main/pupdevices/tiltsensor.rst

@@ -14,8 +14,7 @@ Tilt Sensor
     .. blockimg:: pybricks_blockTilt_TiltSensor_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_TiltSensor_imu.tilt.roll
-        :stack:
-
+    
     .. automethod:: tilt
 
 Examples

doc/main/pupdevices/ultrasonicsensor.rst

@@ -25,8 +25,7 @@ Ultrasonic Sensor
     .. blockimg:: pybricks_blockLightOn_ultrasonicsensor_on
 
     .. blockimg:: pybricks_blockLightOn_ultrasonicsensor_on_list
-        :stack:
-
+    
     .. automethod:: pybricks.pupdevices::UltrasonicSensor.lights.on
 
     .. blockimg:: pybricks_blockLightOn_ultrasonicsensor_off

doc/main/robotics.rst

@@ -27,9 +27,24 @@
 
     .. automethod:: pybricks.robotics.DriveBase.turn
 
-    .. blockimg:: pybricks_blockDriveBaseDrive_drivebase_drive_curve
+    .. versionchanged:: 3.6
 
-    .. automethod:: pybricks.robotics.DriveBase.curve
+        The ``curve()`` Python method will be replaced by the :meth:`.arc`
+        method. It can still make curves, but it uses different definitions
+        for drive and turn direction. Existing code with ``curve()`` continues
+        to work the same, but you should use :meth:`.arc` for new code.
+        If you use block code, you can pick a new block from the palette to
+        update your code. The old block will still work, but it displays a
+        warning icon to remind you to upgrade. The updated `curve` option uses
+        the direction definitions given below. The new `veer` option lets
+        you drive along a circle by a given distance, which is useful for
+        veering slightly in one direction.
+
+    .. blockimg:: pybricks_blockDriveBaseDrive2_drivebase_drive_arc_angle
+
+    .. blockimg:: pybricks_blockDriveBaseDrive2_drivebase_drive_arc_distance
+
+    .. automethod:: pybricks.robotics.DriveBase.arc
 
     .. blockimg:: pybricks_blockDriveBaseConfigure_drivebase_straight_speed
 
@@ -81,6 +96,12 @@
 
     .. automethod:: pybricks.robotics.DriveBase.state
 
+    .. versionchanged:: 3.6
+
+        Now stops the drive base. You can now use nonzero values.
+
+    .. blockimg:: pybricks_blockDriveBaseResetWithValues
+
     .. automethod:: pybricks.robotics.DriveBase.reset
 
     .. automethod:: pybricks.robotics.DriveBase.stalled
@@ -114,7 +135,7 @@
     ``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.
+    :meth:`curve <pybricks.robotics.DriveBase.arc>` command.
 
     .. _measuring:
 

doc/main/tools/index.rst

@@ -40,13 +40,10 @@ Input tools
 .. blockimg:: pybricks_blockReadInput_read_input_first_byte
 
 .. blockimg:: pybricks_blockReadInput_read_input_first_char
-    :stack:
 
 .. blockimg:: pybricks_blockReadInput_read_input_last_byte
-    :stack:
 
 .. blockimg:: pybricks_blockReadInput_read_input_last_char
-    :stack:
 
 .. autofunction:: pybricks.tools.read_input_byte
 

examples/pup/motor/motor_action_basic.py

@@ -12,7 +12,7 @@ wait(1500)
 example_motor.stop()
 wait(1500)
 
-# Run at 70% duty cycle ("power") and then stop by coasting.
+# Run at 50% duty cycle ("power") and then stop by coasting.
 print("Demo of dc")
 example_motor.dc(50)
 wait(1500)

jedi/tests/test_complete_city_hub.py

@@ -76,8 +76,8 @@ def test_hub_dot_system_dot():
     code = _create_snippet(line)
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
-        "name",
-        "reset_reason",
+        "info",
+        "reset_storage",
         "set_stop_button",
         "shutdown",
         "storage",

jedi/tests/test_complete_essential_hub.py

@@ -108,8 +108,8 @@ def test_hub_dot_system_dot():
     code = _create_snippet(line)
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
-        "name",
-        "reset_reason",
+        "info",
+        "reset_storage",
         "set_stop_button",
         "shutdown",
         "storage",

jedi/tests/test_complete_move_hub.py

@@ -88,8 +88,8 @@ def test_hub_dot_system_dot():
     code = _create_snippet(line)
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
-        "name",
-        "reset_reason",
+        "info",
+        "reset_storage",
         "set_stop_button",
         "shutdown",
         "storage",

jedi/tests/test_complete_prime_hub.py

@@ -137,8 +137,8 @@ def test_hub_dot_system_dot():
     code = _create_snippet(line)
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
-        "name",
-        "reset_reason",
+        "info",
+        "reset_storage",
         "set_stop_button",
         "shutdown",
         "storage",

jedi/tests/test_complete_technic_hub.py

@@ -96,8 +96,8 @@ def test_hub_dot_system_dot():
     code = _create_snippet(line)
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
-        "name",
-        "reset_reason",
+        "info",
+        "reset_storage",
         "set_stop_button",
         "shutdown",
         "storage",

jedi/tests/test_get_signature.py

@@ -86,12 +86,12 @@ CONSTRUCTOR_PARAMS = [
     pytest.param(
         "pybricks.hubs",
         "MoveHub",
-        [["broadcast_channel: int=0", "observe_channels: Sequence[int]=[]"]],
+        [["broadcast_channel: int=None", "observe_channels: Sequence[int]=[]"]],
     ),
     pytest.param(
         "pybricks.hubs",
         "CityHub",
-        [["broadcast_channel: int=0", "observe_channels: Sequence[int]=[]"]],
+        [["broadcast_channel: int=None", "observe_channels: Sequence[int]=[]"]],
     ),
     pytest.param(
         "pybricks.hubs",
@@ -100,7 +100,7 @@ CONSTRUCTOR_PARAMS = [
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=0",
+                "broadcast_channel: int=None",
                 "observe_channels: Sequence[int]=[]",
             ]
         ],
@@ -112,7 +112,7 @@ CONSTRUCTOR_PARAMS = [
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=0",
+                "broadcast_channel: int=None",
                 "observe_channels: Sequence[int]=[]",
             ]
         ],
@@ -124,7 +124,7 @@ CONSTRUCTOR_PARAMS = [
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=0",
+                "broadcast_channel: int=None",
                 "observe_channels: Sequence[int]=[]",
             ]
         ],
@@ -264,7 +264,6 @@ METHOD_PARAMS = [
         "system.set_stop_button",
         [(["button: Optional[Union[Button, Iterable[Button]]]"], "None")],
     ),
-    pytest.param("pybricks.hubs", "MoveHub", "system.name", [([], "str")]),
     pytest.param("pybricks.hubs", "MoveHub", "system.shutdown", [([], "None")]),
     pytest.param(
         "pybricks.hubs",
@@ -275,7 +274,6 @@ METHOD_PARAMS = [
             (["offset: int", "*", "write: bytes"], "None"),
         ],
     ),
-    pytest.param("pybricks.hubs", "MoveHub", "system.reset_reason", [([], "int")]),
     pytest.param("pybricks.hubs", "CityHub", "light.on", [(["color: Color"], "None")]),
     pytest.param("pybricks.hubs", "CityHub", "light.off", [([], "None")]),
     pytest.param(
@@ -299,7 +297,6 @@ METHOD_PARAMS = [
         "system.set_stop_button",
         [(["button: Optional[Union[Button, Iterable[Button]]]"], "None")],
     ),
-    pytest.param("pybricks.hubs", "CityHub", "system.name", [([], "str")]),
     pytest.param("pybricks.hubs", "CityHub", "system.shutdown", [([], "None")]),
     pytest.param(
         "pybricks.hubs",
@@ -310,7 +307,6 @@ METHOD_PARAMS = [
             (["offset: int", "*", "write: bytes"], "None"),
         ],
     ),
-    pytest.param("pybricks.hubs", "CityHub", "system.reset_reason", [([], "int")]),
     pytest.param(
         "pybricks.hubs", "TechnicHub", "light.on", [(["color: Color"], "None")]
     ),
@@ -327,19 +323,35 @@ METHOD_PARAMS = [
         "light.animate",
         [(["colors: Collection[Color]", "interval: Number"], "None")],
     ),
-    pytest.param("pybricks.hubs", "TechnicHub", "imu.up", [([], "Side")]),
-    pytest.param("pybricks.hubs", "TechnicHub", "imu.tilt", [([], "Tuple[int, int]")]),
+    pytest.param(
+        "pybricks.hubs",
+        "TechnicHub",
+        "imu.up",
+        [(["calibrated: bool=True"], "Side")],
+    ),
+    pytest.param(
+        "pybricks.hubs",
+        "TechnicHub",
+        "imu.tilt",
+        [(["calibrated: bool=True"], "Tuple[int, int]")],
+    ),
     pytest.param(
         "pybricks.hubs",
         "TechnicHub",
         "imu.acceleration",
-        [(["axis: Axis"], "float"), ([], "Matrix")],
+        [
+            (["axis: Axis=None", "calibrated: bool=True"], "float"),
+            (["calibrated: bool=True"], "Matrix"),
+        ],
     ),
     pytest.param(
         "pybricks.hubs",
         "TechnicHub",
         "imu.angular_velocity",
-        [(["axis: Axis"], "float"), ([], "Matrix")],
+        [
+            (["axis: Axis=None", "calibrated: bool=True"], "float"),
+            (["calibrated: bool=True"], "Matrix"),
+        ],
     ),
     pytest.param("pybricks.hubs", "TechnicHub", "imu.heading", [([], "float")]),
     pytest.param("pybricks.hubs", "TechnicHub", "imu.orientation", [([], "Matrix")]),
@@ -353,7 +365,7 @@ METHOD_PARAMS = [
         "pybricks.hubs",
         "TechnicHub",
         "imu.rotation",
-        [(["axis: Axis"], "float")],
+        [(["axis: Axis", "calibrated: bool=True"], "float")],
     ),
     pytest.param("pybricks.hubs", "TechnicHub", "battery.voltage", [([], "int")]),
     pytest.param("pybricks.hubs", "TechnicHub", "battery.current", [([], "int")]),
@@ -366,7 +378,6 @@ METHOD_PARAMS = [
         "system.set_stop_button",
         [(["button: Optional[Union[Button, Iterable[Button]]]"], "None")],
     ),
-    pytest.param("pybricks.hubs", "TechnicHub", "system.name", [([], "str")]),
     pytest.param("pybricks.hubs", "TechnicHub", "system.shutdown", [([], "None")]),
     pytest.param(
         "pybricks.hubs",
@@ -377,7 +388,6 @@ METHOD_PARAMS = [
             (["offset: int", "*", "write: bytes"], "None"),
         ],
     ),
-    pytest.param("pybricks.hubs", "TechnicHub", "system.reset_reason", [([], "int")]),
     pytest.param("pybricks.hubs", "PrimeHub", "light.on", [(["color: Color"], "None")]),
     pytest.param("pybricks.hubs", "PrimeHub", "light.off", [([], "None")]),
     pytest.param(
@@ -424,19 +434,32 @@ METHOD_PARAMS = [
         [(["text: str", "on: Number=500", "off: Number=50"], "None")],
     ),
     pytest.param("pybricks.hubs", "PrimeHub", "buttons.pressed", [([], "Set[Button]")]),
-    pytest.param("pybricks.hubs", "PrimeHub", "imu.up", [([], "Side")]),
-    pytest.param("pybricks.hubs", "PrimeHub", "imu.tilt", [([], "Tuple[int, int]")]),
+    pytest.param(
+        "pybricks.hubs", "PrimeHub", "imu.up", [(["calibrated: bool=True"], "Side")]
+    ),
+    pytest.param(
+        "pybricks.hubs",
+        "PrimeHub",
+        "imu.tilt",
+        [(["calibrated: bool=True"], "Tuple[int, int]")],
+    ),
     pytest.param(
         "pybricks.hubs",
         "PrimeHub",
         "imu.acceleration",
-        [(["axis: Axis"], "float"), ([], "Matrix")],
+        [
+            (["axis: Axis=None", "calibrated: bool=True"], "float"),
+            (["calibrated: bool=True"], "Matrix"),
+        ],
     ),
     pytest.param(
         "pybricks.hubs",
         "PrimeHub",
         "imu.angular_velocity",
-        [(["axis: Axis"], "float"), ([], "Matrix")],
+        [
+            (["axis: Axis=None", "calibrated: bool=True"], "float"),
+            (["calibrated: bool=True"], "Matrix"),
+        ],
     ),
     pytest.param("pybricks.hubs", "PrimeHub", "imu.heading", [([], "float")]),
     pytest.param("pybricks.hubs", "PrimeHub", "imu.orientation", [([], "Matrix")]),
@@ -450,7 +473,7 @@ METHOD_PARAMS = [
         "pybricks.hubs",
         "PrimeHub",
         "imu.rotation",
-        [(["axis: Axis"], "float")],
+        [(["axis: Axis", "calibrated: bool=True"], "float")],
     ),
     pytest.param(
         "pybricks.hubs",
@@ -481,7 +504,6 @@ METHOD_PARAMS = [
         "system.set_stop_button",
         [(["button: Optional[Union[Button, Iterable[Button]]]"], "None")],
     ),
-    pytest.param("pybricks.hubs", "PrimeHub", "system.name", [([], "str")]),
     pytest.param("pybricks.hubs", "PrimeHub", "system.shutdown", [([], "None")]),
     pytest.param(
         "pybricks.hubs",
@@ -492,7 +514,6 @@ METHOD_PARAMS = [
             (["offset: int", "*", "write: bytes"], "None"),
         ],
     ),
-    pytest.param("pybricks.hubs", "PrimeHub", "system.reset_reason", [([], "int")]),
     pytest.param(
         "pybricks.hubs", "EssentialHub", "light.on", [(["color: Color"], "None")]
     ),
@@ -512,21 +533,32 @@ METHOD_PARAMS = [
     pytest.param(
         "pybricks.hubs", "EssentialHub", "buttons.pressed", [([], "Set[Button]")]
     ),
-    pytest.param("pybricks.hubs", "EssentialHub", "imu.up", [([], "Side")]),
     pytest.param(
-        "pybricks.hubs", "EssentialHub", "imu.tilt", [([], "Tuple[int, int]")]
+        "pybricks.hubs", "EssentialHub", "imu.up", [(["calibrated: bool=True"], "Side")]
+    ),
+    pytest.param(
+        "pybricks.hubs",
+        "EssentialHub",
+        "imu.tilt",
+        [(["calibrated: bool=True"], "Tuple[int, int]")],
     ),
     pytest.param(
         "pybricks.hubs",
         "EssentialHub",
         "imu.acceleration",
-        [(["axis: Axis"], "float"), ([], "Matrix")],
+        [
+            (["axis: Axis=None", "calibrated: bool=True"], "float"),
+            (["calibrated: bool=True"], "Matrix"),
+        ],
     ),
     pytest.param(
         "pybricks.hubs",
         "EssentialHub",
         "imu.angular_velocity",
-        [(["axis: Axis"], "float"), ([], "Matrix")],
+        [
+            (["axis: Axis=None", "calibrated: bool=True"], "float"),
+            (["calibrated: bool=True"], "Matrix"),
+        ],
     ),
     pytest.param("pybricks.hubs", "EssentialHub", "imu.heading", [([], "float")]),
     pytest.param("pybricks.hubs", "EssentialHub", "imu.orientation", [([], "Matrix")]),
@@ -540,7 +572,7 @@ METHOD_PARAMS = [
         "pybricks.hubs",
         "EssentialHub",
         "imu.rotation",
-        [(["axis: Axis"], "float")],
+        [(["axis: Axis", "calibrated: bool=True"], "float")],
     ),
     pytest.param("pybricks.hubs", "EssentialHub", "battery.voltage", [([], "int")]),
     pytest.param("pybricks.hubs", "EssentialHub", "battery.current", [([], "int")]),
@@ -553,7 +585,6 @@ METHOD_PARAMS = [
         "system.set_stop_button",
         [(["button: Optional[Union[Button, Iterable[Button]]]"], "None")],
     ),
-    pytest.param("pybricks.hubs", "EssentialHub", "system.name", [([], "str")]),
     pytest.param("pybricks.hubs", "EssentialHub", "system.shutdown", [([], "None")]),
     pytest.param(
         "pybricks.hubs",
@@ -564,7 +595,6 @@ METHOD_PARAMS = [
             (["offset: int", "*", "write: bytes"], "None"),
         ],
     ),
-    pytest.param("pybricks.hubs", "EssentialHub", "system.reset_reason", [([], "int")]),
     # TODO: iodevices module here
     pytest.param("pybricks.pupdevices", "DCMotor", "dc", [(["duty: Number"], "None")]),
     pytest.param("pybricks.pupdevices", "DCMotor", "stop", [([], "None")]),
@@ -994,7 +1024,12 @@ METHOD_PARAMS = [
     pytest.param(
         "pybricks.robotics", "DriveBase", "state", [([], "Tuple[int, int, int, int]")]
     ),
-    pytest.param("pybricks.robotics", "DriveBase", "reset", [([], "None")]),
+    pytest.param(
+        "pybricks.robotics",
+        "DriveBase",
+        "reset",
+        [(["distance: Number=0", "angle: Number=0"], "None")],
+    ),
     pytest.param("pybricks.robotics", "DriveBase", "done", [([], "bool")]),
     pytest.param("pybricks.robotics", "DriveBase", "stalled", [([], "bool")]),
 ]

npm/ide-docs/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 <!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
 
+## 2.20.0 - 2024-02-26
+
+### Changed
+- Updated docs to v3.6.0b5.
+
+## 2.19.0 - 2024-04-11
+
+### Changed
+- Updated docs to v3.5.0.
+
 ## 2.18.0 - 2024-04-05
 
 ### Changed

npm/ide-docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pybricks/ide-docs",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "description": "Special build of Pybricks API docs for embedding in an IDE.",
   "repository": {
     "type": "git",

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.5.0b2"
+version = "3.6.0b5"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]

src/pybricks/_common.py

@@ -69,32 +69,6 @@ class System:
 
         Stops your program and shuts the hub down."""
 
-    def reset_reason(self) -> int:
-        """reset_reason() -> int
-
-        Finds out how and why the hub (re)booted. This can be useful to
-        diagnose some problems.
-
-        Returns:
-            * ``0`` if the hub was previously powered off
-              normally.
-            * ``1`` if the hub rebooted automatically, like
-              after a firmware update.
-            * ``2`` if the hub previously
-              crashed due to a watchdog timeout, which indicates a firmware
-              issue.
-        """
-
-    def name(self) -> str:
-        """name() -> str
-
-        Gets the hub name. This is the name you see when connecting
-        via Bluetooth.
-
-        Returns:
-            The hub name.
-        """
-
     @overload
     def storage(self, offset: int, *, read: int) -> bytes: ...
 
@@ -131,6 +105,40 @@ class System:
                 If you try to read or write data outside of the allowed range.
         """
 
+    def reset_storage(self) -> None:
+        """reset_storage()
+
+        Resets all user settings to default values and erases user programs.
+        """
+
+    def info(self) -> dict:
+        """info() -> dict
+
+        Gets information about the hub as a dictionary with the following keys:
+
+         - ``"name"``: The hub name. This is the name you see when connecting
+           via Bluetooth.
+         - ``"reset_reason"``: Why the hub (re)booted. It is ``0`` if the hub
+           was previously powered off normally. It is ``1`` if the hub rebooted
+           automatically, like after a firmware update. It is ``2`` if the hub
+           previously crashed due to a watchdog timeout, which indicates a
+           firmware issue.
+         - ``"host_connected_ble"``: Whether the hub is connected to a computer,
+           tablet, or phone via Bluetooth.
+         - ``"program_start_type"``: It is ``1`` if the program started
+           automatically when the hub was powered on. It is ``2`` if the program
+           was started with the hub buttons. It is ``3`` if the program was
+           started from your connected computer.
+
+        Returns:
+            A dictionary with system info.
+
+        .. versionchanged:: 3.6
+            The name and reset reason where previously available as separate
+            methods. Now they are included in the info dictionary. The methods
+            are still available for compatibility.
+        """
+
 
 class DCMotor:
     """Generic class to control simple motors without rotation sensors, such
@@ -471,6 +479,11 @@ class Motor(DCMotor):
 
         Sets the accumulated rotation angle of the motor to a desired value.
 
+        If this motor is also being used by a drive base, its distance and
+        angle values will also be affected. You might want to
+        use its :meth:`reset <pybricks.robotics.DriveBase.reset>`
+        method instead.
+
         Arguments:
             angle (Number, deg): Value to which the angle should be reset.
         """
@@ -1013,34 +1026,67 @@ class SimpleAccelerometer:
         """
 
 
-class Accelerometer(SimpleAccelerometer):
-    """Get measurements from an accelerometer."""
+class IMU:
+
+    def up(self, calibrated: bool = True) -> Side:
+        """up(calibrated=True) -> Side
+
+        Checks which side of the hub currently faces upward.
+
+        Arguments:
+            calibrated (bool): Choose ``True`` to use calibrated gyroscope and
+                accelerometer data to determine which way is up. Choose
+                ``False`` to use raw acceleration values.
+
+        Returns:
+            ``Side.TOP``, ``Side.BOTTOM``, ``Side.LEFT``, ``Side.RIGHT``,
+            ``Side.FRONT`` or ``Side.BACK``.
+        """
+
+    def tilt(self, calibrated: bool = True) -> Tuple[int, int]:
+        """tilt(calibrated=True) -> Tuple[int, int]
+
+        Gets the pitch and roll angles. This is relative to the
+        :ref:`user-specified neutral orientation <robotframe>`.
+
+        The order of rotation is pitch-then-roll. This is equivalent to a
+        positive rotation along the robot y-axis and then a positive rotation
+        along the x-axis.
+
+        Arguments:
+            calibrated (bool): Choose ``True`` to use calibrated gyroscope and
+                accelerometer data to determine the tilt. Choose ``False``
+                to use raw acceleration values.
+
+        Returns:
+            Tuple of pitch and roll angles in degrees.
+        """
 
     @overload
-    def acceleration(self, axis: Axis) -> float: ...
+    def acceleration(self, axis: Axis = None, calibrated: bool = True) -> float: ...
 
     @overload
-    def acceleration(self) -> Matrix: ...
+    def acceleration(self, calibrated: bool = True) -> Matrix: ...
 
     def acceleration(self, *args):
         """
-        acceleration(axis) -> float: mm/s²
-        acceleration() -> vector: mm/s²
-
+        acceleration(axis, calibrated=True) -> float: mm/s²
+        acceleration(calibrated=True) -> vector: mm/s²
 
         Gets the acceleration of the device along a given axis in the
         :ref:`robot reference frame <robotframe>`.
 
         Arguments:
             axis (Axis): Axis along which the acceleration should be
-                         measured.
+                measured, or ``None`` to get a vector along all axes.
+            calibrated (bool): Choose ``True`` to use calibrated acceleration
+                values. Choose ``False`` to use raw acceleration values.
+
         Returns:
             Acceleration along the specified axis. If you specify no axis,
             this returns a vector of accelerations along all axes.
         """
 
-
-class IMU(Accelerometer):
     def ready(self) -> bool:
         """ready() -> bool
 
@@ -1068,38 +1114,89 @@ class IMU(Accelerometer):
     @overload
     def settings(
         self,
+        *,
         angular_velocity_threshold: float = None,
         acceleration_threshold: float = None,
+        heading_correction: float = None,
+        angular_velocity_bias: Tuple[float, float, float] = None,
+        angular_velocity_scale: Tuple[float, float, float] = None,
+        acceleration_correction: Tuple[float, float, float, float, float, float] = None,
     ) -> None: ...
 
     @overload
-    def settings(self) -> Tuple[float, float]: ...
+    def settings(
+        self,
+    ) -> Tuple[
+        float,
+        float,
+        float,
+        Tuple[float, float, float],
+        Tuple[float, float, float],
+        Tuple[float, float, float, float, float, float],
+    ]: ...
 
     def settings(self, *args):
         """
-        settings(angular_velocity_threshold, acceleration_threshold)
-        settings() -> Tuple[float, float]
+        settings(*, angular_velocity_threshold, acceleration_threshold, heading_correction, angular_velocity_bias, angular_velocity_scale, acceleration_correction)
+        settings() -> Tuple
 
         Configures the IMU settings. If no arguments are given,
-        this returns the current values.
+        this returns the current values. Use keyword arguments for each value
+        to ensure correct behavior because settings may be added or changed in
+        future releases.
+
+        These IMU settings are saved on the hub. They will keep their values
+        until you change them again. The values will be reset to default values
+        if you update the hub to a different firmware version or call the
+        ``hub.system.reset_storage`` method.
 
         The ``angular_velocity_threshold`` and ``acceleration_threshold``
         define when the hub is considered stationary. If all
         measurements stay below these thresholds for one second, the IMU
-        will recalibrate itself.
-
-        In a noisy room with high ambient vibrations (such as a
-        competition hall), it is recommended to increase the thresholds
+        will recalibrate itself. In a noisy room with high ambient vibrations (such as a
+        competition hall), you can increase the thresholds
         slightly to give your robot the chance to calibrate.
         To verify that your settings are working as expected, test that
         the ``stationary()`` method gives ``False`` if your robot is moving,
-        and ``True`` if it is sitting still for at least a second.
+        and ``True`` if it is sitting still.
+
+        The gyroscope measures how fast the hub rotates to estimate the total
+        angle. Due to variations in the production process, each
+        hub consistently reports a different value for a full rotation. For
+        example, your hub might consistently report `357` degrees for every
+        `360` degree turn. You can measure this value
+        with ``hub.imu.rotation(-Axis.Z)`` and enter it as
+        the ``heading_correction`` setting. Then, the ``hub.imu.heading()``
+        method will take it into account going forward, correctly scaling it
+        to 360 degrees for a full rotation.
 
         Arguments:
             angular_velocity_threshold (Number, deg/s): The threshold for
-                angular velocity. The default value is 1.5 deg/s.
-            acceleration_threshold (Number, mm/s²): The threshold for angular
-                velocity. The default value is 250 mm/s².
+                variations in the angular velocity below which the hub is
+                considered stationary enough to calibrate.
+                After a reset the value is 2 deg/s.
+            acceleration_threshold (Number, mm/s²): The threshold for
+                variations in acceleration below which the hub is considered
+                stationary enough to calibrate. After a reset the value
+                is 2500 mm/s².
+            heading_correction (Number, deg): Number of degrees reported by
+                ``imu.rotation(-Axis.Z)`` for one full rotation of your robot.
+                After a reset the value is 360 degrees.
+            angular_velocity_bias (tuple, deg/s): Initial bias for angular
+                velocity measurements along x, y, and z immediately after boot.
+                After a reset the value is (0, 0, 0) deg/s.
+            angular_velocity_scale (tuple, deg): Scale adjustment for x, y, and
+                z rotation to account for manufacturing differences. After a reset the
+                value is (360, 360, 360) deg/s. The correct values can be
+                obtained using `hub.imu.rotation(Axis.X, calibrated=False)` and
+                repeating it for each axis.
+            acceleration_correction (tuple, mm/s²): Scale adjustment for x, y,
+                and z gravity magnitude in both directions to account for
+                manufacturing differences. After a reset the
+                value is (9806.65, -9806.65, 9806.65, -9806.65, 9806.65, -9806.65) mm/s².
+                The correct values can be
+                obtained using `hub.imu.acceleration(Axis.X, calibrated=False)`
+                and repeating it for all axes in both directions.
         """
 
     def heading(self) -> float:
@@ -1117,11 +1214,11 @@ class IMU(Accelerometer):
                   the robot is on a flat surface.*
 
                   This means that the value is
-                  no longer correct if you lift it from the table. To solve
-                  this, you can call ``reset_heading`` to reset the heading to
-                  a known value *after* you put it back down. For example, you
-                  could align your robot with the side of the competition table
-                  and reset the heading 90 degrees as the new starting point.
+                  no longer correct if you lift it from the table or turn on
+                  a ramp. Try ``hub.imu.heading('3D')`` for a heading value
+                  that compensates for this. This will become the default in a
+                  future release. If you try it, please let us know on our
+                  forums!
 
         Returns:
             Heading angle relative to starting orientation.
@@ -1133,35 +1230,50 @@ class IMU(Accelerometer):
 
         Resets the accumulated heading angle of the robot.
 
+        This cannot be called while a drive base is using the gyro to drive or
+        hold position.
+        Use :meth:`DriveBase.reset() <pybricks.robotics.DriveBase.reset>`
+        instead, which will stop the robot and then set the new heading value.
+
+        .. versionchanged:: 3.6 Resetting the angle while driving is not allowed. Stop first.
+
         Arguments:
             angle (Number, deg): Value to which the heading should be reset.
+
+        Raises:
+            OSError:
+                There is a drive base that is currently using the gyro.
         """
 
     @overload
-    def angular_velocity(self, axis: Axis) -> float: ...
+    def angular_velocity(self, axis: Axis = None, calibrated: bool = True) -> float: ...
 
     @overload
-    def angular_velocity(self) -> Matrix: ...
+    def angular_velocity(self, calibrated: bool = True) -> Matrix: ...
 
     def angular_velocity(self, *args):
         """
-        angular_velocity(axis) -> float: deg/s
-        angular_velocity() -> vector: deg/s
+        angular_velocity(axis, calibrated=True) -> float: deg/s
+        angular_velocity(calibrated=True) -> vector: deg/s
 
         Gets the angular velocity of the device along a given axis in
         the :ref:`robot reference frame <robotframe>`.
 
         Arguments:
             axis (Axis): Axis along which the angular velocity should be
-                         measured.
+                measured, or ``None`` to get a vector along all axes.
+            calibrated (bool): Choose ``True`` to compensate for the estimated
+                bias and configured scale of the gyroscope. Choose ``False``
+                to get raw angular velocity values.
+
         Returns:
             Angular velocity along the specified axis. If you specify no axis,
             this returns a vector of accelerations along all axes.
         """
 
-    def rotation(self, axis: Axis) -> float:
+    def rotation(self, axis: Axis, calibrated: bool = True) -> float:
         """
-        rotation(axis) -> float: deg
+        rotation(axis, calibrated=True) -> float: deg
 
         Gets the rotation of the device along a given axis in
         the :ref:`robot reference frame <robotframe>`.
@@ -1170,10 +1282,11 @@ class IMU(Accelerometer):
         axis. For general three-dimensional motion, use the
         ``orientation()`` method instead.
 
-        The value starts counting from ``0`` when you initialize this class.
-
         Arguments:
             axis (Axis): Axis along which the rotation should be measured.
+            calibrated (bool): Choose ``True`` to compensate for configured
+                scale of the gyroscope. Choose ``False`` to get unscaled values.
+
         Returns:
             The rotation angle.
         """
@@ -1188,10 +1301,8 @@ class IMU(Accelerometer):
         It returns a rotation matrix whose columns represent the ``X``, ``Y``,
         and ``Z`` axis of the robot.
 
-        .. note:: This method is not yet implemented.
-
         Returns:
-            The rotation matrix.
+            The 3x3 rotation matrix.
         """
 
 
@@ -1335,14 +1446,14 @@ class BLE:
     .. versionadded:: 3.3
     """
 
-    def broadcast(self, data: Union[bool, int, float, str, bytes]) -> None:
+    def broadcast(self, data: Union[bool, int, float, str, bytes]) -> MaybeAwaitable:
         """broadcast(data)
 
         Starts broadcasting the given data on
         the ``broadcast_channel`` you selected when initializing the hub.
 
         Data may be of type ``int``, ``float``, ``str``, ``bytes``,
-        ``True``, or ``False``, or a list thereof.
+        ``True``, or ``False``. It can also be a list or tuple of these.
 
         Choose ``None`` to stop broadcasting. This helps improve performance
         when you don't need the broadcast feature, especially when observing

src/pybricks/hubs.py

@@ -44,9 +44,9 @@ class MoveHub:
     ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
     ):
-        """MoveHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """MoveHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Arguments:
             top_side (Axis): The axis that passes through the *top side* of
@@ -54,8 +54,8 @@ class MoveHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -78,14 +78,14 @@ class CityHub:
     ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
     ):
-        """CityHub(broadcast_channel=0, observe_channels=[])
+        """CityHub(broadcast_channel=None, observe_channels=[])
 
         Arguments:
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -112,10 +112,10 @@ class TechnicHub:
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = 0,
+        broadcast_channel: int = None,
         observe_channels: Sequence[int] = [],
     ):
-        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -128,8 +128,8 @@ class TechnicHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -157,10 +157,10 @@ class EssentialHub:
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = 0,
+        broadcast_channel: int = None,
         observe_channels: Sequence[int] = [],
     ):
-        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -173,8 +173,8 @@ class EssentialHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -212,10 +212,10 @@ class PrimeHub:
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = 0,
+        broadcast_channel: int = None,
         observe_channels: Sequence[int] = [],
     ):
-        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -228,8 +228,8 @@ class PrimeHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.

src/pybricks/parameters.py

@@ -112,6 +112,10 @@ class Color:
         The brightness value.
         """
 
+    def __iter__(self):
+        """Allows unpacking of the Color instance into h, s, and v."""
+        return iter((self.h, self.s, self.v))
+
     def __repr__(self):
         return "Color(h={}, s={}, v={})".format(self.h, self.s, self.v)
 

src/pybricks/pupdevices.py

@@ -86,11 +86,15 @@ class Motor(_common.Motor):
 
         Sets the accumulated rotation angle of the motor to a desired value.
 
-        If you don't specify an angle, the absolute angle
-        will be used if your motor supports it.
+        If this motor is also being used by a drive base, its distance and
+        angle values will also be affected. You might want to
+        use its :meth:`reset <pybricks.robotics.DriveBase.reset>`
+        method instead.
 
         Arguments:
             angle (Number, deg): Value to which the angle should be reset.
+                                 Choose ``None`` to reset it to the absolute
+                                 value of the motor.
         """
 
 

src/pybricks/robotics.py

@@ -119,10 +119,19 @@ class DriveBase:
             Tuple of distance, drive speed, angle, and turn rate of the robot.
         """
 
-    def reset(self) -> None:
-        """reset()
+    def reset(self, distance: Number = 0, angle: Number = 0) -> None:
+        """reset(distance=0, angle=0)
 
-        Resets the estimated driven distance and angle to 0."""
+        Resets the estimated driven distance and heading angle.
+
+        This also calls :meth:`.stop` to stop ongoing movements.
+        If your robot is controlled with :meth:`.use_gyro` set to ``True``,
+        calling this method will `also` set the gyro to the given angle.
+
+        Arguments:
+            distance (Number, mm): Speed of the robot.
+            angle (Number, deg): Heading angle of the robot.
+        """
 
     @overload
     def settings(
@@ -191,6 +200,40 @@ class DriveBase:
                          with the rest of the program.
         """
 
+    def arc(
+        self,
+        radius: Number,
+        angle: Number = None,
+        distance: Number = None,
+        then: Stop = Stop.HOLD,
+        wait: bool = True,
+    ) -> MaybeAwaitable:
+        """arc(radius, angle=None, distance=None, then=Stop.HOLD, wait=True)
+
+        Drives an arc (a partial circle) with a given radius. You can specify
+        how far to drive using either an angle or a distance.
+
+        With a positive radius, the robot drives along a circle to its right.
+        With a negative radius, the robot drives along a circle to its left.
+
+        You can specify how far to travel along that circle as an angle
+        (degrees) or distance (mm). A positive value means driving forward
+        along the circle. Negative means driving in reverse.
+
+        Arguments:
+            radius (Number, mm): Radius of the circle.
+            angle (Number, deg): Angle to drive along the circle.
+            distance (Number, mm): Distance to drive along the circle,
+                                   measured at the center of the robot.
+            then (Stop): What to do after coming to a standstill.
+            wait (bool): Wait for the maneuver to complete before continuing
+                         with the rest of the program.
+        Raises:
+            ValueError:
+                You must specify ``angle`` or ``distance``, but not both. The
+                radius cannot be zero. Use :meth:`.turn` for in-place turns.
+        """
+
     def curve(
         self, radius: Number, angle: Number, then: Stop = Stop.HOLD, wait: bool = True
     ) -> MaybeAwaitable:
@@ -224,7 +267,7 @@ class DriveBase:
         with the maximum actuation signal.
 
         Returns:
-            ``True`` if the drivebase is stalled, ``False`` if not.
+            ``True`` if the drive base is stalled, ``False`` if not.
         """
 
     def use_gyro(self, use_gyro: bool) -> None:
@@ -234,6 +277,9 @@ class DriveBase:
         straight. Choose ``False`` to rely only on the motor's built-in
         rotation sensors.
 
+        This method will automatically call :meth:`.stop` to stop ongoing
+        movements.
+
         Arguments:
             use_gyro (bool): ``True`` to enable, ``False`` to disable.
         """