v4.0.0b11

Ship it with the docs so we can parse it in Pybricks for namespace based lookup.

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
 
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
       with:
         submodules: recursive
     - name: Install dependencies

.github/workflows/jedi.yml

@@ -7,24 +7,9 @@ jobs:
     if: github.ref_type != 'tag'
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - run: pipx install poetry
     - run: poetry install
       working-directory: ./jedi
     - run: poetry run pytest -vv
       working-directory: ./jedi
-
-  publish:
-    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'pybricks_jedi/')
-    runs-on: ubuntu-22.04
-    steps:
-    - uses: actions/checkout@v3
-    - run: pipx install poetry
-    - run: poetry install
-      working-directory: ./jedi
-    - run: poetry build
-      working-directory: ./jedi
-    - run: poetry publish
-      working-directory: ./jedi
-      env:
-        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_PYBRICKS_JEDI_TOKEN }}

.github/workflows/publish-ide-docs.yml

@@ -2,22 +2,33 @@ name: Release @pybricks/ide-docs
 
 on:
   push:
-    tags: 
-    - '@pybricks/ide-docs/**'
+    tags:
+    - 'v4.*'
+
+permissions:
+  id-token: write
+  contents: read
 
 jobs:
   publish_ide_docs:
     runs-on: ubuntu-22.04
     steps:
+    - name: Get version from tag
+      run: |
+        VERSION="${GITHUB_REF_NAME#v}"
+        NPM_VERSION=$(echo "$VERSION" | sed 's/\([0-9]\)a\([0-9]\)/\1-alpha.\2/;s/\([0-9]\)b\([0-9]\)/\1-beta.\2/;s/\([0-9]\)rc\([0-9]\)/\1-rc.\2/')
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        echo "NPM_VERSION=$NPM_VERSION" >> $GITHUB_ENV
+        echo "NPM_TAG=$(echo "$NPM_VERSION" | grep -q '-' && echo 'next' || echo 'latest')" >> $GITHUB_ENV
     - name: Ubuntu packages
       run: |
         sudo apt-get update
         sudo apt-get install -y dvisvgm preview-latex-style texlive texlive-fonts-extra texlive-latex-extra
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
       with:
         submodules: recursive
     - name: Set up Python 3.8
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.8
     - name: Install dependencies
@@ -26,13 +37,13 @@ jobs:
         poetry run python -m pip install --upgrade pip
         poetry run python -m pip install --upgrade setuptools
         poetry install --only=doc
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
-        node-version: '14.x'
+        node-version: '24'
         registry-url: 'https://registry.npmjs.org'
+    - run: npm version --no-git-tag-version "$NPM_VERSION"
+      working-directory: npm/ide-docs
     - run: yarn build
       working-directory: npm/ide-docs
-    - run: yarn publish
+    - run: npm publish --tag "$NPM_TAG"
       working-directory: npm/ide-docs
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.github/workflows/publish-images.yml

@@ -9,11 +9,11 @@ jobs:
   publish_ide_docs:
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     # Setup .npmrc file to publish to npm
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
-        node-version: '16.x'
+        node-version: '22.x'
         registry-url: 'https://registry.npmjs.org'
     - run: ./build.py
       working-directory: npm/images

.github/workflows/publish-jedi.yml

@@ -2,22 +2,42 @@ name: Release @pybricks/jedi
 
 on:
   push:
-    tags: 
-    - '@pybricks/jedi/**'
+    tags:
+    - 'v4.*'
+
+permissions:
+  id-token: write
+  contents: read
 
 jobs:
   publish_jedi:
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
-    # Setup .npmrc file to publish to npm
-    - uses: actions/setup-node@v3
+    - uses: actions/checkout@v6
+    - name: Get version from tag
+      run: |
+        VERSION="${GITHUB_REF_NAME#v}"
+        NPM_VERSION=$(echo "$VERSION" | sed 's/\([0-9]\)a\([0-9]\)/\1-alpha.\2/;s/\([0-9]\)b\([0-9]\)/\1-beta.\2/;s/\([0-9]\)rc\([0-9]\)/\1-rc.\2/')
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        echo "NPM_VERSION=$NPM_VERSION" >> $GITHUB_ENV
+        echo "NPM_TAG=$(echo "$NPM_VERSION" | grep -q '-' && echo 'next' || echo 'latest')" >> $GITHUB_ENV
+    - name: Set up Python
+      uses: actions/setup-python@v5
       with:
-        node-version: '16.x'
+        python-version: '3.11'
+    - name: Install poetry
+      run: pipx install poetry
+    - name: Set pybricks-jedi version
+      run: poetry version "$VERSION"
+      working-directory: jedi
+    - name: Set pybricks version and update jedi dependency pin
+      run: |
+        poetry version "$VERSION"
+        sed -i "s/^pybricks = \".*\"/pybricks = \"$VERSION\"/" jedi/pyproject.toml
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '24'
         registry-url: 'https://registry.npmjs.org'
-    - run: ./build.py
-      working-directory: npm/jedi
-    - run: yarn publish
-      working-directory: npm/jedi/build
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+    - run: python jedi/build.py "$NPM_VERSION"
+    - run: npm publish --tag "$NPM_TAG"
+      working-directory: jedi/npm-build

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 on:
   push:
     tags:
-    - 'v3.*'
+    - 'v4.*'
 
 name: Create release on GitHub and PyPI
 
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
         with:
           submodules: true
           fetch-depth: 0
@@ -38,7 +38,7 @@ jobs:
   build_and_publish:
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - run: pipx run poetry build
     - run: pipx run poetry publish
       env:

.gitignore

@@ -25,6 +25,7 @@
 build/
 build-*/
 _build/
+npm-build/
 
 # Tests
 ######################

.vscode/spellright.dict

@@ -24,7 +24,6 @@ EV3
 ev3brick
 ev3dev
 ev3devices
-Ev3devSensor
 fb
 Franca
 func

CHANGELOG.md

@@ -1,291 +1,13 @@
 # Changelog
 
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
+See [pybricks-micropython/CHANGELOG.md][changelog] for the changes in each release.
 
-## Unreleased
+This repository is frequently updated to stay in sync with the implementation.
 
-## 3.6.b5 - 2024-04-11
+Major and minor versions are synchronized with `pybricks-micropython`, which
+leads. Patch versions and prerelease version numbers may differ, as they may
+be bumped for every small change or typo in the docs.
 
-### Changed
+The version for this repository is also used for the `@pybricks/jedi` and `@pybricks/ide-docs` npm packages.
 
-- 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
-
-- Added `pybricks.pupdevices.Remote.disconnect` method.
-- Added blocks for `up`, `ready` and `stationary` for IMUs.
-- Added `last` and `chr` parameters to `read_input_byte` and add blocks.
-- Added block for the `in` operation.
-- Add double ternary block.
-
-## 3.5.0b1 - 2024-03-11
-
-### Added
-
-- Added `XboxController.rumble` method.
-- Added block icons for `hub.system.set_stop_button` and `hub.system.shutdown`.
-- Added program stop block (`raise SystemExit`).
-
-## 3.4.1 - 2024-03-11
-
-### Fixed
-
-- Fixed Read The Docs virtual environment workflow.
-
-## 3.4.0 - 2024-03-11
-
-### Changed
-
-- Update list block screenshots to match implementation.
-
-## 3.4.0b5 - 2024-03-05
-
-### Changed
-
-- Updates for v3.4.0b3 firmware (out of sync with docs).
-- Changed `hub.button` to `hub.buttons` on single button hubs. Access via
- `hub.button` will keep working in the firmware for backwards compatibility.
-
-## 3.4.0b4 - 2024-02-14
-
-### Added
-
-- Added `pybricks.iodevices.XboxController` class.
-
-### Changed
-
-- Changed `buttons.pressed` return type to set.
-
-## 3.4.0b3 - 2024-01-30
-
-### Added
-
-- Added `pybricks.robotics.Car` class.
-
-### Changed
-
-- Changed `pybricks.robotics.DriveBase` icon to two wheels instead of steering
-  wheel, which will be used for the new car class.
-
-## 3.4.0b2 - 2023-11-28
-
-### Changed
-- Include first batch of block coding images.
-
-## 3.3.0 - 2023-11-24
-
-### Changed
-- Bump beta version to release version with no further changes.
-
-## 3.3.0c1 - 2023-11-20
-
-### Added
-- Enabled tilt and orientation config for `MoveHub()`.
-- Documented `Motor.close()`
-
-## Fixed
-- Fixed missing awaitable for `Remote.light` and LWP3 writes.
-
-## 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
-- Documented new `hub.ble` methods.
-
-## 3.3.0b4 - 2023-04-21
-
-### Added
-- Documented `integral_deadzone` in `Control.pid()`.
-- Documented `Motor.model`. This can be used to view the estimated motor
-  state and change its settings.
-- Added `rotation`, `orientation`, `ready`, `stationary` and `settings` methods
-  to `IMU` class.
-- Added `GyroDriveBase` class to `pybricks.robotics`.
-
-### Changed
-- Change implementation status of `IMU.heading` and `IMU.reset_heading`. They
-  are now implemented, with some limitations as noted in a note box.
-- Moved `Matrix` and `vector` from `pybricks.geometry` to `pybricks.tools`.
-- Moved `Axis` from `pybricks.geometry` to `pybricks.parameters`.
-
-### Removed
-- Removed `pybricks.geometry` module.
-
-## 3.2.0 - 2022-12-20
-
-### Changed
-- Changed module TOC headings to make it easier to find things.
-
-## 3.2.0c1 - 2022-12-09
-
-### Changed
-- Updated "front" side of the Technic Hub to be consistent with
-  the Prime Hub.
-
-## 3.2.0b6 - 2022-12-02
-
-### Added
-- Documented ``Stop.NONE`` and ``Stop.COAST_SMART``.
-- Documented ``ujson`` module.
-- Added `done` and `stalled` methods for `DriveBase`.
-
-### Changed
-- Changed `PrimeHub.display.image()` to `PrimeHub.display.icon()` and renamed
-  its kwarg from `image` to `icon`.
-- Improved presentation and docstrings of the ``ubuiltins`` and other
-  MicroPython modules
-- Moved the random numbers example for Move Hub to the Move Hub page.
-- Moved `done()`, `stalled()`, `load()` from `Control` to `Motor` object.
-
-## 3.2.0b5 - 2022-11-11
-
-### Fixed
-- Fixed Jedi code completion for `Color` and `Icon` classes in `pybricks.parameters`.
-
-## 3.2.0b4 - 2022-10-21
-
-### Added
-- Code auto-completion for `EssentialHub`.
-- Added `System.storage` method.
-
-### Fixed
-- Fixed some type hints in `parameters` submodule.
-
-## 3.2.0b1-r3 - 2022-06-26
-
-### Fixed
-- Fixed more type hints and improved compatibility with jedi.
-
-## 3.2.0b1-r2 - 2022-06-24
-
-### Changed
-- Moved remaining type hints from `.pyi` files to the python stub modules, and
-  fixed numerous errors in the type hints throughout.
-
-## 3.2.0b1-r1 - 2022-06-09
-
-### Added
-- Added `__init__.py` to `pybricks` package.
-
-## 3.2.0b1 - 2022-06-02
-
-### Added
-- Code auto-completion for `hub.charger`, `hub.imu` and `hub.system`.
-- Moved typing from several `.pyi` files to the actual python modules.
-
-### Fixed
-- Fixed code completion for `DCMotor` and `Motor` classes in MS Python VS Code extension.
-- Fixed missing `DCMotor` type in `ev3devices`.
-- Fixed type hint for `Motor.reset_angle()` in `pupdevices`.
-
-### Changed
-- Setter for acceleration can now also be used to set acceleration and
-  deceleration to different values, using a two-valued tuple.
-
-## 3.1.0 - 2021-12-16
-
-### Added
-- Added maximum voltage setter for `DCMotor` and `Motor`.
-- Documented `DriveBase.curve()` method.
-
-### Changed
-- Removed `duty` setting from `Control.limits` method.
-- Removed `integral_range` setting from `Control.pid` method.
-
-### Fixed
-- Fixed link to Color Light Matrix page.
-- Fixed link to Inventor Hub page.
-
-## 3.1.0rc1 - 2021-11-19
-
-### Added
-- Added `ColorLightMatrix` class.
-- Added `LWP3Device` class.
-
-**NOTE: version number after this point were from JavaScript package and do
-not correspond to Pybricks firmware version numbers.**
-
-## 1.6.0 - 2021-08-30
-
-### Added
-- MicroPython module documentation.
-- Examples for hub system functions including stop button and shutdown.
-
-### Changed
-- Build IDE docs as main docs with minor changes, instead of a completely
-  separate build.
-- Moved motor control documentation to the motor page.
-
-## 1.5.0 - 2021-07-01
-
-### Added
-- Documentation for Powered Up Remote Control.
-
-## 1.4.0 - 2021-06-23
-
-### Added
-- Enabled beta content that was hidden for the 3.0 release.
-- Added notice about using the latest beta version.
-
-## 1.3.3 - 2021-05-21
-
-### Changed
-- Match example snippet styling to IDE.
-- Add more examples.
-
-## 1.3.2 - 2021-04-26
-
-### Changed
-- Theme style fixes.
-- Example code fixes
-- Match doc version to firmware version.
-
-## 1.3.1 - 2021-04-12
-
-### Changed
-- Upgrade sphinx and rtd-theme to fix style issues.
-
-## 1.3.0 - 2021-04-12
-
-### Removed
-- Removed features which not be in the official 3.0 release. These features
-  are still in beta. They'll come back in future releases once tested.
-
-## 1.2.0 - 2021-04-09
-
-### Changed
-- Moved installation guide to external site.
-
-## 1.1.1 - 2021-02-14
-
-### Added
-- Added installation guide.
-- Various documentation fixes.
-
-## 1.1.0 - 2021-01-28
-
-### Added
-- Scrollbar styling.
-
-## 1.0.0 - 2021-01-25
-
-### Added
-- Sphinx build output.
+[changelog]: https://github.com/pybricks/pybricks-micropython/blob/master/CHANGELOG.md

CONTRIBUTING.md

@@ -163,6 +163,11 @@ Linting:
     poetry run flake8  # check Python
     poetry run doc8  # check Restructured Text
 
+Building all release artifacts (docs, jedi, npm packages):
+
+    # Linux/macOS only
+    ./build-all.sh
+
 [vscode]: https://code.visualstudio.com/
 [git]: https://git-scm.com/
 [python]: https://www.python.org/

build-all.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Build all release artifacts locally (equivalent to CI workflows, minus publish).
+set -euo pipefail
+
+REPO_ROOT="$(realpath "$(dirname "${BASH_SOURCE[0]}")")"
+
+# Activate the project venv so python/make/etc. all use it without poetry run
+source "$REPO_ROOT/.venv/bin/activate"
+
+# Read version from pyproject.toml
+VERSION=$(grep '^version = ' "$REPO_ROOT/pyproject.toml" | head -1 | sed 's/version = "\(.*\)"/\1/')
+# Convert Python pre-release format (e.g. 4.0.0a1, 4.0.0b1, 4.0.0rc1) to npm semver (e.g. 4.0.0-alpha.1, 4.0.0-beta.1, 4.0.0-rc.1)
+NPM_VERSION=$(echo "$VERSION" | sed 's/\([0-9]\)a\([0-9]\)/\1-alpha.\2/;s/\([0-9]\)b\([0-9]\)/\1-beta.\2/;s/\([0-9]\)rc\([0-9]\)/\1-rc.\2/')
+echo "==> Building version $VERSION (npm: $NPM_VERSION)"
+
+# lint
+echo "==> Linting"
+cd "$REPO_ROOT"
+flake8
+doc8
+
+# pybricks-jedi tests
+echo "==> Testing pybricks-jedi"
+cd "$REPO_ROOT/jedi"
+poetry run pytest -vv
+
+# @pybricks/jedi npm package
+echo "==> Building @pybricks/jedi"
+cd "$REPO_ROOT/jedi"
+python3 build.py "$NPM_VERSION"
+
+# @pybricks/ide-docs npm package
+echo "==> Building @pybricks/ide-docs"
+cd "$REPO_ROOT"
+make -C doc clean
+cd "$REPO_ROOT/npm/ide-docs"
+yarn build
+
+echo ""
+echo "Build complete."
+echo "  jedi npm package : jedi/npm-build/"
+echo "  ide-docs         : npm/ide-docs/html/"

doc/common/conf.py

@@ -254,12 +254,6 @@ latex_documents = [
 exclude_patterns = [
     "ev3devices.rst",
     "hubs/ev3brick.rst",
-    "iodevices/analogsensor.rst",
-    "iodevices/dcmotor.rst",
-    "iodevices/ev3devsensor.rst",
-    "iodevices/i2cdevice.rst",
-    "iodevices/lumpdevice.rst",
-    "iodevices/uartdevice.rst",
     "media.rst",
     "messaging.rst",
     "nxtdevices.rst",
@@ -370,9 +364,35 @@ def on_missing_reference(
             return nodes.Text(f"{ret_type}: {ret_unit}")
 
 
+def on_build_finished(app: Sphinx, exception):
+    if exception or app.builder.name != "html":
+        return
+    import json
+    from sphinx.ext.intersphinx import InventoryFile
+
+    inv_path = os.path.join(app.outdir, "objects.inv")
+    if not os.path.exists(inv_path):
+        return
+
+    with open(inv_path, "rb") as f:
+        inv = InventoryFile.load(f, "", lambda base, uri: base + uri)
+
+    index = {}
+    for type_key, entries in inv.items():
+        if not type_key.startswith("py:"):
+            continue
+        for name, (project, version, url, display) in entries.items():
+            index[name] = url
+
+    out_path = os.path.join(app.outdir, "index.json")
+    with open(out_path, "w") as f:
+        json.dump(index, f, indent=2, sort_keys=True)
+
+
 def setup(app: Sphinx):
     app.add_directive("availability", AvailabilityDirective)
     app.connect("missing-reference", on_missing_reference)
+    app.connect("build-finished", on_build_finished)
 
 
 # -- Python domain hacks ---------------------------------------------------

doc/common/extensions/blockimg.py

@@ -1,5 +1,4 @@
-import xml.etree.ElementTree as ET
-from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst import Directive
 from docutils import nodes
 from pathlib import Path
 

doc/common/extensions/requirements-static.py

@@ -18,14 +18,23 @@ FEATURES_MEDIUM = FEATURES_SMALL | {
 }
 
 # Large feature set.
-FEATURES_LARGE = FEATURES_MEDIUM | set()
+FEATURES_LARGE = FEATURES_MEDIUM | {
+    "ble-extra",  # Extra features such as pairing or multiple connections.
+}
 
 # Features per hub.
 HUB_FEATURES = {
-    "movehub": {"movehub"} | FEATURES_SMALL,
-    "cityhub": {"cityhub"} | FEATURES_MEDIUM,
-    "technichub": {"technichub", "gyro", "xbox-controller"} | FEATURES_MEDIUM,
-    "primehub": {"primehub", "inventorhub", "light-matrix", "gyro", "xbox-controller"}
+    "movehub": {"movehub", "pup"} | FEATURES_SMALL,
+    "cityhub": {"cityhub", "pup"} | FEATURES_MEDIUM,
+    "technichub": {"technichub", "gyro", "xbox-controller", "pup"} | FEATURES_MEDIUM,
+    "primehub": {
+        "primehub",
+        "inventorhub",
+        "light-matrix",
+        "gyro",
+        "xbox-controller",
+        "pup",
+    }
     | FEATURES_LARGE,
     "inventorhub": {
         "primehub",
@@ -33,9 +42,10 @@ HUB_FEATURES = {
         "light-matrix",
         "gyro",
         "xbox-controller",
+        "pup",
     }
     | FEATURES_LARGE,
-    "essentialhub": {"essentialhub", "gyro", "xbox-controller"} | FEATURES_LARGE,
+    "essentialhub": {"essentialhub", "gyro", "xbox-controller", "pup"} | FEATURES_LARGE,
 }
 
 
@@ -94,9 +104,7 @@ class PybricksRequirementsStaticDirective(Directive):
                 </tbody>
             </table>
         </div>
-        """.format(
-            compat_row
-        )
+        """.format(compat_row)
 
         # Return the node.
         node = nodes.raw("", html, format="html")

doc/main/diagrams_source/icon_ev3hub.svg

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   version="1.1"
+   id="svg2"
+   width="525"
+   height="525"
+   viewBox="0 0 525 525"
+   sodipodi:docname="icon_ev3hub.svg"
+   inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
+   inkscape:export-filename="../diagrams/icon_ev3hub.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath860">
+      <rect
+         style="fill:#6ab0de;fill-opacity:1;stroke:#6ab0de;stroke-width:4;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         id="rect862"
+         width="589.10107"
+         height="96.333336"
+         x="235.33333"
+         y="-236.00002" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1040">
+      <rect
+         style="fill:#1e1e1e;fill-opacity:1;stroke:none;stroke-width:4;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         id="rect1042"
+         width="128.5101"
+         height="19.934668"
+         x="827.15656"
+         y="74.666672" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1920"
+     inkscape:window-height="1163"
+     id="namedview4"
+     showgrid="false"
+     inkscape:zoom="0.9950413"
+     inkscape:cx="301.49502"
+     inkscape:cy="344.70931"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg2"
+     inkscape:snap-global="false"
+     inkscape:pagecheckerboard="0" />
+  <image
+     width="525"
+     height="468.02328"
+     preserveAspectRatio="none"
+     xlink:href="../cad/output/ev3device-ev3.png"
+     id="image834"
+     x="0"
+     y="26.384924" />
+</svg>

doc/main/diagrams_source/icon_nxthub.svg

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   version="1.1"
+   id="svg2"
+   width="525"
+   height="525"
+   viewBox="0 0 525 525"
+   sodipodi:docname="icon_nxthub.svg"
+   inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
+   inkscape:export-filename="../diagrams/icon_nxthub.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath860">
+      <rect
+         style="fill:#6ab0de;fill-opacity:1;stroke:#6ab0de;stroke-width:4;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         id="rect862"
+         width="589.10107"
+         height="96.333336"
+         x="235.33333"
+         y="-236.00002" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1040">
+      <rect
+         style="fill:#1e1e1e;fill-opacity:1;stroke:none;stroke-width:4;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         id="rect1042"
+         width="128.5101"
+         height="19.934668"
+         x="827.15656"
+         y="74.666672" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1920"
+     inkscape:window-height="1163"
+     id="namedview4"
+     showgrid="false"
+     inkscape:zoom="0.9950413"
+     inkscape:cx="301.49502"
+     inkscape:cy="344.70931"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg2"
+     inkscape:snap-global="false"
+     inkscape:pagecheckerboard="false" />
+  <image
+     width="525"
+     height="447.39801"
+     preserveAspectRatio="none"
+     xlink:href="../cad/output/nxtdevice-nxt.png"
+     id="image960"
+     x="0"
+     y="34.809708" />
+</svg>

doc/main/ev3devices.rst

@@ -64,13 +64,13 @@ Motors
 
     .. rubric:: Control settings
 
-    .. automethod:: pybricks.ev3devices.Motor.control.limits
+    .. automethod:: pybricks.ev3devices::Motor.control.limits
 
-    .. automethod:: pybricks.ev3devices.Motor.control.pid
+    .. automethod:: pybricks.ev3devices::Motor.control.pid
 
-    .. automethod:: pybricks.ev3devices.Motor.control.target_tolerances
+    .. automethod:: pybricks.ev3devices::Motor.control.target_tolerances
 
-    .. automethod:: pybricks.ev3devices.Motor.control.stall_tolerances
+    .. automethod:: pybricks.ev3devices::Motor.control.stall_tolerances
 
     .. attribute:: control.scale
 

doc/main/hubs/cityhub.rst

@@ -26,20 +26,6 @@ City Hub
 
     .. automethod:: pybricks.hubs::CityHub.light.animate
 
-    .. rubric:: Using connectionless Bluetooth messaging
-
-    .. blockimg:: pybricks_blockBleBroadcast_CityHub
-
-    .. automethod:: pybricks.hubs::CityHub.ble.broadcast
-
-    .. blockimg:: pybricks_blockBleObserve_CityHub
-
-    .. automethod:: pybricks.hubs::CityHub.ble.observe
-
-    .. automethod:: pybricks.hubs::CityHub.ble.signal_strength
-
-    .. automethod:: pybricks.hubs::CityHub.ble.version
-
     .. rubric:: Using the battery
 
     .. blockimg:: pybricks_blockBatteryMeasure_CityHub_battery.voltage
@@ -56,10 +42,12 @@ City Hub
 
     .. automethod:: pybricks.hubs::CityHub.buttons.pressed
 
+    .. automethod:: pybricks.hubs::CityHub.system.info
+
     .. blockimg:: pybricks_blockHubStopButton_CityHub
 
     .. blockimg:: pybricks_blockHubStopButton_CityHub_none
-    
+
     .. automethod:: pybricks.hubs::CityHub.system.set_stop_button
 
     .. automethod:: pybricks.hubs::CityHub.system.storage
@@ -102,23 +90,6 @@ Creating light animations
 .. literalinclude::
     ../../../examples/pup/hub_common/build/light_animate_cityhub.py
 
-
-Bluetooth examples
-------------------
-
-Broadcasting data to other hubs
-*******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_broadcast_cityhub.py
-
-Observing data from other hubs
-******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_observe_cityhub.py
-
-
 Button and system examples
 ----------------------------------
 

doc/main/hubs/essentialhub.rst

@@ -36,7 +36,7 @@ Essential Hub
     .. blockimg:: pybricks_blockHubStopButton_EssentialHub
 
     .. blockimg:: pybricks_blockHubStopButton_EssentialHub_none
-    
+
     .. automethod:: pybricks.hubs::EssentialHub.system.set_stop_button
 
     .. rubric:: Using the IMU
@@ -63,7 +63,7 @@ Essential Hub
     .. blockimg:: pybricks_blockTilt_EssentialHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_EssentialHub_imu.tilt.roll
-    
+
     .. automethod:: pybricks.hubs::EssentialHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_EssentialHub
@@ -89,27 +89,13 @@ 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
-
-    .. blockimg:: pybricks_blockBleBroadcast_EssentialHub
-
-    .. automethod:: pybricks.hubs::EssentialHub.ble.broadcast
-
-    .. blockimg:: pybricks_blockBleObserve_EssentialHub
-
-    .. automethod:: pybricks.hubs::EssentialHub.ble.observe
-
-    .. automethod:: pybricks.hubs::EssentialHub.ble.signal_strength
-
-    .. automethod:: pybricks.hubs::EssentialHub.ble.version
-
     .. rubric:: Using the battery
 
     .. blockimg:: pybricks_blockBatteryMeasure_EssentialHub_battery.voltage
@@ -204,23 +190,6 @@ Reading acceleration and angular velocity on one axis
 .. literalinclude::
     ../../../examples/pup/hub_common/build/imu_read_scalar_essentialhub.py
 
-
-Bluetooth examples
-------------------
-
-Broadcasting data to other hubs
-*******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_broadcast_essentialhub.py
-
-Observing data from other hubs
-******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_observe_essentialhub.py
-
-
 System examples
 ----------------------------------
 

doc/main/hubs/movehub.rst

@@ -38,7 +38,7 @@ Move Hub
     .. blockimg:: pybricks_blockTilt_MoveHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_MoveHub_imu.tilt.roll
-    
+
     .. automethod:: pybricks.hubs::MoveHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_MoveHub
@@ -49,20 +49,6 @@ Move Hub
 
             Changed acceleration units from m/s² to mm/s².
 
-    .. rubric:: Using connectionless Bluetooth messaging
-
-    .. blockimg:: pybricks_blockBleBroadcast_PrimeHub
-
-    .. automethod:: pybricks.hubs::PrimeHub.ble.broadcast
-
-    .. blockimg:: pybricks_blockBleObserve_PrimeHub
-
-    .. automethod:: pybricks.hubs::PrimeHub.ble.observe
-
-    .. automethod:: pybricks.hubs::MoveHub.ble.signal_strength
-
-    .. automethod:: pybricks.hubs::MoveHub.ble.version
-
     .. rubric:: Using the battery
 
     .. blockimg:: pybricks_blockBatteryMeasure_MoveHub_battery.voltage
@@ -79,10 +65,12 @@ Move Hub
 
     .. automethod:: pybricks.hubs::MoveHub.buttons.pressed
 
+    .. automethod:: pybricks.hubs::MoveHub.system.info
+
     .. blockimg:: pybricks_blockHubStopButton_MoveHub
 
     .. blockimg:: pybricks_blockHubStopButton_MoveHub_none
-    
+
     .. automethod:: pybricks.hubs::MoveHub.system.set_stop_button
 
     .. automethod:: pybricks.hubs::MoveHub.system.storage
@@ -127,23 +115,6 @@ Reading acceleration
 .. literalinclude::
     ../../../examples/pup/hub_movehub/imu_read_acceleration.py
 
-
-Bluetooth examples
-------------------
-
-Broadcasting data to other hubs
-*******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_broadcast_movehub.py
-
-Observing data from other hubs
-******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_observe_movehub.py
-
-
 Button and system examples
 ----------------------------------
 

doc/main/hubs/primehub.rst

@@ -10,6 +10,8 @@ Prime Hub / Inventor Hub
 
 .. blockimg:: pybricks_variables_set_inventor_hub_option4
 
+.. currentmodule:: pybricks.hubs
+
 .. class:: InventorHub
 
     This class is the same as the ``PrimeHub`` class, shown below. Both classes
@@ -82,7 +84,7 @@ Prime Hub / Inventor Hub
     .. blockimg:: pybricks_blockHubStopButton_PrimeHub
 
     .. blockimg:: pybricks_blockHubStopButton_PrimeHub_none
-    
+
     .. automethod:: pybricks.hubs::PrimeHub.system.set_stop_button
 
     .. rubric:: Using the IMU
@@ -109,7 +111,7 @@ Prime Hub / Inventor Hub
     .. blockimg:: pybricks_blockTilt_PrimeHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_PrimeHub_imu.tilt.roll
-    
+
     .. automethod:: pybricks.hubs::PrimeHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_PrimeHub
@@ -135,11 +137,11 @@ 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
@@ -150,20 +152,6 @@ Prime Hub / Inventor Hub
 
     .. automethod:: pybricks.hubs::PrimeHub.speaker.play_notes
 
-    .. rubric:: Using connectionless Bluetooth messaging
-
-    .. blockimg:: pybricks_blockBleBroadcast_PrimeHub
-
-    .. automethod:: pybricks.hubs::PrimeHub.ble.broadcast
-
-    .. blockimg:: pybricks_blockBleObserve_PrimeHub
-
-    .. automethod:: pybricks.hubs::PrimeHub.ble.observe
-
-    .. automethod:: pybricks.hubs::PrimeHub.ble.signal_strength
-
-    .. automethod:: pybricks.hubs::PrimeHub.ble.version
-
     .. rubric:: Using the battery
 
     .. blockimg:: pybricks_blockBatteryMeasure_PrimeHub_battery.voltage
@@ -329,23 +317,6 @@ Reading acceleration and angular velocity on one axis
 .. literalinclude::
     ../../../examples/pup/hub_common/build/imu_read_scalar_primehub.py
 
-
-Bluetooth examples
-------------------
-
-Broadcasting data to other hubs
-*******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_broadcast_primehub.py
-
-Observing data from other hubs
-******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_observe_primehub.py
-
-
 System examples
 ----------------------------------
 

doc/main/hubs/technichub.rst

@@ -51,7 +51,7 @@ Technic Hub
     .. blockimg:: pybricks_blockTilt_TechnicHub_imu.tilt.pitch
 
     .. blockimg:: pybricks_blockTilt_TechnicHub_imu.tilt.roll
-    
+
     .. automethod:: pybricks.hubs::TechnicHub.imu.tilt
 
     .. blockimg:: pybricks_blockImuAcceleration_TechnicHub
@@ -77,27 +77,13 @@ 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
-
-    .. blockimg:: pybricks_blockBleBroadcast_TechnicHub
-
-    .. automethod:: pybricks.hubs::TechnicHub.ble.broadcast
-
-    .. blockimg:: pybricks_blockBleObserve_TechnicHub
-
-    .. automethod:: pybricks.hubs::TechnicHub.ble.observe
-
-    .. automethod:: pybricks.hubs::TechnicHub.ble.signal_strength
-
-    .. automethod:: pybricks.hubs::TechnicHub.ble.version
-
     .. rubric:: Using the battery
 
     .. blockimg:: pybricks_blockBatteryMeasure_TechnicHub_battery.voltage
@@ -114,10 +100,12 @@ Technic Hub
 
     .. automethod:: pybricks.hubs::TechnicHub.buttons.pressed
 
+    .. automethod:: pybricks.hubs::TechnicHub.system.info
+
     .. blockimg:: pybricks_blockHubStopButton_TechnicHub
 
     .. blockimg:: pybricks_blockHubStopButton_TechnicHub_none
-    
+
     .. automethod:: pybricks.hubs::TechnicHub.system.set_stop_button
 
     .. automethod:: pybricks.hubs::TechnicHub.system.storage
@@ -193,23 +181,6 @@ Reading acceleration and angular velocity on one axis
 .. literalinclude::
     ../../../examples/pup/hub_common/build/imu_read_scalar_technichub.py
 
-
-Bluetooth examples
-------------------
-
-Broadcasting data to other hubs
-*******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_broadcast_technichub.py
-
-Observing data from other hubs
-******************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_common/build/ble_observe_technichub.py
-
-
 Button and system examples
 ----------------------------------
 

doc/main/index.rst

@@ -60,6 +60,7 @@ above to reveal this menu.
    parameters/index
    tools/index
    robotics
+   messaging/index
    signaltypes
 
 .. toctree::

doc/main/iodevices/analogsensor.rst

@@ -1,10 +1,8 @@
-EV3 Analog Sensor
+.. pybricks-requirements:: pybricks-iodevices ev3
+
+Analog Sensor
 ^^^^^^^^^^^^^^^^^
 
-.. note::
-
-   This class is only available on EV3.
-
 .. figure:: ../../main/cad/output/iodevice-rj12brown.png
    :width: 25 %
 

doc/main/iodevices/dcmotor.rst

@@ -1,20 +1,25 @@
-EV3 DC Motor
+DC Motor
 ^^^^^^^^^^^^^^^^^^
 
-.. note::
+This class is specifically for EV3 and NXT. This lets you drive motors that
+are not automatically detected as motors. This includes RCX motors and Power
+Function motors that are connected via the official converter cables. Note:
+Applying motor power to custom electronics may damage the hub or the device.
 
-   This class is specifically for on EV3. For Powered Up DC Motors, just use
-   the :class:`DCMotor <pybricks.pupdevices.DCMotor>` class.
+For Powered Up DC Motors, just use
+the :class:`DCMotor <pybricks.pupdevices.DCMotor>` class instead, which will
+automatically detect the motor and use the correct and safe settings.
 
 .. figure:: ../../main/cad/output/iodevice-dcmotor.png
    :width: 40 %
 
 .. autoclass:: pybricks.iodevices.DCMotor
-    :noindex:
     :no-members:
 
     .. automethod:: pybricks.iodevices.DCMotor.dc
-        :noindex:
+
+    .. automethod:: pybricks.iodevices.DCMotor.brake
 
     .. automethod:: pybricks.iodevices.DCMotor.stop
-        :noindex:
+
+    .. automethod:: pybricks.iodevices.DCMotor.settings

doc/main/iodevices/ev3devsensor.rst

@@ -1,60 +0,0 @@
-Ev3dev sensors
-^^^^^^^^^^^^^^^^^^
-
-.. note::
-
-   This class is only available on EV3.
-
-.. figure:: ../../main/cad/output/iodevice-rj12pcbbox.png
-   :width: 30 %
-
-EV3 MicroPython is built on top of ev3dev, which means that a sensor
-may be supported even if it is not listed in this documentation. If so, you can
-use it with the ``Ev3devSensor`` class. This is easier and faster than using
-the custom device classes given above.
-
-To check whether you can use the ``Ev3devSensor`` class:
-
-    * Plug the sensor into your EV3 Brick.
-    * Go to the main menu of the EV3 Brick.
-    * Select `Device Browser` and then `Sensors`.
-    * If your sensor shows up, you can use it.
-
-Now select your sensor from the menu and choose `set mode`. This shows all
-available modes for this sensor. You can use these mode names as the ``mode``
-setting below.
-
-To learn more about compatible devices and what each mode does,
-visit the `ev3dev sensors`_ page.
-
-.. autoclass:: pybricks.iodevices.Ev3devSensor
-    :no-members:
-
-    .. autoattribute:: pybricks.iodevices.Ev3devSensor.sensor_index
-        :annotation:
-
-    .. autoattribute:: pybricks.iodevices.Ev3devSensor.port_index
-        :annotation:
-
-    .. automethod:: pybricks.iodevices.Ev3devSensor.read
-
-**Example: Reading values with the Ev3devSensor class**
-
-In this example we use the LEGO MINDSTORMS EV3 Color Sensor with the raw
-RGB mode. This gives uncalibrated red, green, and blue reflection values.
-
-.. literalinclude::
-   ../../../examples/ev3/ev3devsensor/main.py
-
-**Example: Extending the Ev3devSensor class**
-
-This example shows how to extend the ``Ev3devSensor`` class by accessing
-additional features found in the Linux system folder for this device.
-
-.. literalinclude::
-   ../../../examples/ev3/ev3devsensor/class_example.py
-
-.. _ev3dev sensors: http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-stretch/sensors.html
-.. _Mode name: http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-stretch/sensor_data.html
-.. _lego-sensor: http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-stretch/sensors.html#the-lego-sensor-subsytem
-.. _lego-port: http://docs.ev3dev.org/projects/lego-linux-drivers/en/ev3dev-stretch/ports.html#the-lego-port-subsystem

doc/main/iodevices/i2cdevice.rst

@@ -1,14 +1,8 @@
 Generic I2C Device
 ^^^^^^^^^^^^^^^^^^
 
-.. note::
-
-   This class is **only supported on the EV3** at this time. It could be added
-   to Powered Up hubs in a future release. If you'd like to see this happen, be
-   sure to ask us on our `support page`_.
-
-.. _support page: https://github.com/pybricks/support/issues/
-
+EV3 and NXT support connecting generic I2C devices to the hub.
+See :doc:`pinout here <uartdevice>`.
 
 .. figure:: ../../main/cad/output/iodevice-rj12cyan.png
    :width: 25 %

doc/main/iodevices/index.rst

@@ -1,25 +1,39 @@
-.. pybricks-requirements:: pybricks-iodevices
-
 :mod:`iodevices <pybricks.iodevices>` -- Custom devices
 ============================================================
 
 .. module:: pybricks.iodevices
 
+This module has classes for generic and custom input/output devices.
+
+Wireless devices
+----------------
+
 .. toctree::
    :maxdepth: 1
    :hidden:
 
-   pupdevice
-   lwp3device
    xboxcontroller
 
-This module has classes for generic and custom input/output devices.
+.. pybricks-requirements:: pybricks-iodevices
 
-.. pybricks-classlink:: PUPDevice
+.. pybricks-classlink:: XboxController
 
-.. figure:: ../../main/cad/output/iodevice-pupdevice.png
-   :width: 50 %
-   :target: pupdevice.html
+.. figure:: ../../main/diagrams_source/xboxcontroller.png
+   :width: 40 %
+   :target: xboxcontroller.html
+
+LEGO protocol devices
+---------------------
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   lwp3device
+   lumpdevice
+   pupdevice
+
+.. pybricks-requirements:: pybricks-iodevices
 
 .. pybricks-classlink:: LWP3Device
 
@@ -27,8 +41,68 @@ This module has classes for generic and custom input/output devices.
    :width: 80 %
    :target: lwp3device.html
 
-.. pybricks-classlink:: XboxController
+.. pybricks-requirements:: ev3 pybricks-iodevices
 
-.. figure:: ../../main/diagrams_source/xboxcontroller.png
+.. pybricks-classlink:: LUMPDevice
+
+.. figure:: ../../main/cad/output/iodevice-rj12green.png
+   :width: 20 %
+   :target: lumpdevice.html
+
+.. pybricks-requirements:: pybricks-iodevices
+
+.. pybricks-classlink:: PUPDevice
+
+.. figure:: ../../main/cad/output/iodevice-pupdevice.png
+   :width: 50 %
+   :target: pupdevice.html
+
+Generic protocols
+-----------------
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   uartdevice
+   i2cdevice
+   analogsensor
+   dcmotor
+
+.. pybricks-requirements:: pybricks-iodevices
+
+.. pybricks-classlink:: UARTDevice
+
+.. |uart-wired| image:: ../../main/cad/output/iodevice-rj12grey.png
+   :width: 20 %
+   :target: uartdevice.html
+
+.. |uart-wireless| image:: ../../main/cad/output/iodevice-pupdevice.png
+   :width: 50 %
+   :target: uartdevice.html
+
+|uart-wired| |uart-wireless|
+
+.. pybricks-requirements:: ev3 pybricks-iodevices
+
+.. pybricks-classlink:: I2CDevice
+
+.. figure:: ../../main/cad/output/iodevice-rj12cyan.png
+   :width: 20 %
+   :target: i2cdevice.html
+
+.. pybricks-requirements:: ev3 pybricks-iodevices
+
+.. pybricks-classlink:: AnalogSensor
+
+.. figure:: ../../main/cad/output/iodevice-rj12brown.png
+   :width: 20 %
+   :target: analogsensor.html
+
+.. pybricks-requirements:: ev3 pybricks-iodevices
+
+.. pybricks-classlink:: DCMotor
+
+.. figure:: ../../main/cad/output/iodevice-dcmotor.png
    :width: 40 %
-   :target: xboxcontroller.html
+   :target: dcmotor.html

doc/main/iodevices/lumpdevice.rst

@@ -1,11 +1,10 @@
+.. pybricks-requirements:: pybricks-iodevices ev3
+
 EV3 UART Device
 ^^^^^^^^^^^^^^^^^
 
-.. note::
-
-   This class is only available on EV3.
-
 .. figure:: ../../main/cad/output/iodevice-rj12green.png
    :width: 25 %
 
 .. autoclass:: pybricks.iodevices.LUMPDevice
+   :no-members:

doc/main/iodevices/lwp3device.rst

@@ -3,11 +3,6 @@
 LEGO Wireless Protocol v3 device
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. warning::
-
-   This is an experimental class. It has not been well tested and may be
-   changed in future.
-
 .. figure:: ../../main/cad/output/hub-lwp3.png
    :width: 80 %
 

doc/main/iodevices/pupdevice.rst

@@ -15,6 +15,8 @@ Powered Up Device
 
     .. automethod:: pybricks.iodevices.PUPDevice.write
 
+    .. automethod:: pybricks.iodevices.PUPDevice.reset
+
 Examples
 -------------------
 

doc/main/iodevices/uartdevice.rst

@@ -1,16 +1,47 @@
+.. pybricks-requirements:: pybricks-iodevices
+
 Generic UART Device
 ^^^^^^^^^^^^^^^^^^^
 
-.. note::
+Powered Up and EV3 support connecting generic UART devices to the hub. The pinout
+is shown below. Note the orientation of the connector. For EV3, the internal
+wire colors match those on the diagram below.
 
-   This class is **only supported on the EV3** at this time. It could be added
-   to Powered Up hubs in a future release. If you'd like to see this happen,
-   be sure to ask us on our `support page`_.
+.. image:: pinout_numbered.jpg
+   :width: 50 %
 
-.. _support page: https://github.com/pybricks/support/issues/
+.. list-table::
+   :header-rows: 1
+
+   * - Pin
+     - Powered Up (UART)
+     - EV3 (UART sensor)
+     - EV3 (I2C sensor)
+   * - 1 (white)
+     - Motor Terminal 1
+     - Optional battery power
+     - Optional battery power
+   * - 2 (black)
+     - Motor Terminal 2
+     - N/A
+     - N/A
+   * - 3 (red)
+     - Ground
+     - Ground
+     - Ground
+   * - 4 (green)
+     - VCC (3.3 V)
+     - VCC (5 V)
+     - VCC (5 V)
+   * - 5 (yellow)
+     - Hub TX (Sensor RX) (3.3 V)
+     - Hub TX (Sensor RX) (3.3 V)
+     - SCL (master) (3.3 V)
+   * - 6 (blue)
+     - Hub RX (Sensor TX) (3.3 V)
+     - Hub RX (Sensor TX) (3.3 V)
+     - SDA (master) (3.3 V)
 
-.. figure:: ../../main/cad/output/iodevice-rj12grey.png
-   :width: 25 %
 
 .. autoclass:: pybricks.iodevices.UARTDevice
 

doc/main/iodevices/xboxcontroller.rst

@@ -11,6 +11,12 @@ Xbox Controller
 .. autoclass:: pybricks.iodevices.XboxController
   :no-members:
 
+  .. automethod:: pybricks.iodevices::XboxController.connect
+
+  .. automethod:: pybricks.iodevices::XboxController.disconnect
+
+  .. automethod:: pybricks.iodevices::XboxController.name
+
   .. blockimg:: pybricks_blockButtonIsPressed_XboxController
 
   .. automethod:: pybricks.iodevices::XboxController.buttons.pressed
@@ -30,19 +36,19 @@ Xbox Controller
   .. blockimg:: pybricks_blockJoystickValue_lj_x
 
   .. blockimg:: pybricks_blockJoystickValue_lj_y
-  
+
   .. automethod:: pybricks.iodevices::XboxController.joystick_left
 
   .. blockimg:: pybricks_blockJoystickValue_rj_x
 
   .. blockimg:: pybricks_blockJoystickValue_rj_y
-  
+
   .. automethod:: pybricks.iodevices::XboxController.joystick_right
 
   .. blockimg:: pybricks_blockJoystickValue_lt
 
   .. blockimg:: pybricks_blockJoystickValue_rt
-  
+
   .. automethod:: pybricks.iodevices::XboxController.triggers
 
   .. blockimg:: pybricks_blockJoystickValue_dpad
@@ -56,15 +62,15 @@ Xbox Controller
   .. blockimg:: pybricks_blockGamepadRumble_default
 
   .. blockimg:: pybricks_blockGamepadRumble_default_with_list
-  
+
   .. blockimg:: pybricks_blockGamepadRumble_with_options
-  
+
   .. automethod:: pybricks.iodevices::XboxController.rumble
 
 .. _xbox-controller-pairing:
 
 Xbox Controller Pairing Instructions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+====================================
 The first time you use a controller with a hub, you will need to pair
 them: Turn the controller on and then press and hold the pairing
 button on the back of the controller for a few seconds. When you release
@@ -74,7 +80,7 @@ When pairing and the connection is succesful, the Xbox button will stop
 flashing and stay on for as long as the program is running.
 
 Repeat Connections
-==================
+------------------
 
 If you keep using the same controller with the same hub, you can simply
 turn the controller on the next time and the hub will connect to it
@@ -86,7 +92,7 @@ connect to another hub, you will need to pair them again as described
 above.
 
 Compatible Controllers
-============================
+----------------------
 
 All Xbox controllers released since 2016 are compatible. This includes the
 controller from the One S (``1708`` from 2016), the Elite Series 2 (``1797``

doc/main/messaging/index.rst

@@ -0,0 +1,44 @@
+:mod:`messaging <pybricks.messaging>` -- Send and receive messages
+==================================================================
+
+.. automodule:: pybricks.messaging
+    :no-members:
+
+.. pybricks-requirements:: pup
+
+.. autoclass:: pybricks.messaging.BLERadio
+    :no-members:
+
+    .. automethod:: pybricks.messaging.BLERadio.broadcast
+
+    .. automethod:: pybricks.messaging.BLERadio.observe
+
+    .. automethod:: pybricks.messaging.BLERadio.signal_strength
+
+    .. automethod:: pybricks.messaging.BLERadio.version
+
+.. autoclass:: pybricks.messaging.AppData
+    :no-members:
+
+    .. automethod:: pybricks.messaging.AppData.get_bytes
+
+    .. automethod:: pybricks.messaging.AppData.write_bytes
+
+    .. automethod:: pybricks.messaging.AppData.configure
+
+    .. automethod:: pybricks.messaging.AppData.close
+
+BLERadio examples
+------------------
+
+Broadcasting data to other hubs
+*******************************
+
+.. literalinclude::
+    ../../../examples/pup/ble_radio/ble_broadcast.py
+
+Observing data from other hubs
+******************************
+
+.. literalinclude::
+    ../../../examples/pup/ble_radio/ble_observe.py

doc/main/micropython/exceptions.rst

@@ -54,7 +54,6 @@ This section lists all available exceptions in alphabetical order.
 .. _OSError:
 
 .. autoclass:: ubuiltins.OSError
-    :noindex:
 
 .. autoclass:: ubuiltins.OverflowError
     :no-members:

doc/main/parameters/axis.rst

@@ -6,5 +6,14 @@ Axis
 .. autoclass:: pybricks.parameters.Axis
     :no-members:
 
+    .. autoattribute:: pybricks.parameters.Axis.X
+        :annotation: = vector(1, 0, 0)
+
+    .. autoattribute:: pybricks.parameters.Axis.Y
+        :annotation: = vector(0, 1, 0)
+
+    .. autoattribute:: pybricks.parameters.Axis.Z
+        :annotation: = vector(0, 0, 1)
+
 On Move Hub, doing math with these vectors is not supported. The axes can still
 be used to set up the hub orientation.

doc/main/parameters/button.rst

@@ -3,6 +3,8 @@
 Button
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. currentmodule:: pybricks.parameters
+
 .. class:: Button
 
     .. rubric:: Remote and hub buttons

doc/main/parameters/direction.rst

@@ -3,6 +3,8 @@
 Direction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. currentmodule:: pybricks.parameters
+
 .. class:: Direction
 
     Rotational direction for positive speed or angle values.

doc/main/parameters/port.rst

@@ -3,6 +3,8 @@
 Port
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. currentmodule:: pybricks.parameters
+
 .. class:: Port
 
     Input and output ports:

doc/main/parameters/side.rst

@@ -3,6 +3,8 @@
 Side
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. currentmodule:: pybricks.parameters
+
 .. class:: Side
 
     Side of a hub or a sensor. These devices are

doc/main/parameters/stop.rst

@@ -3,6 +3,8 @@
 Stop
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. currentmodule:: pybricks.parameters
+
 .. class:: Stop
 
     Action after the motor stops.

doc/main/pupdevices/colorsensor.rst

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

doc/main/pupdevices/dcmotor.rst

@@ -21,20 +21,16 @@ Motors without rotation sensors
     .. blockimg:: pybricks_blockMotorDuty_DCMotor
 
     .. automethod:: pybricks.pupdevices.DCMotor.dc
-        :noindex:
 
     .. blockimg:: pybricks_blockMotorStop_DCMotor_coast
 
     .. automethod:: pybricks.pupdevices.DCMotor.stop
-        :noindex:
 
     .. blockimg:: pybricks_blockMotorStop_DCMotor_brake
 
     .. automethod:: pybricks.pupdevices.DCMotor.brake
-        :noindex:
 
     .. automethod:: pybricks.pupdevices.DCMotor.settings
-        :noindex:
 
 Examples
 -------------------

doc/main/pupdevices/duplotrain.rst

@@ -0,0 +1,23 @@
+.. pybricks-requirements:: pybricks-iodevices ble-extra
+
+Duplo Train
+^^^^^^^^^^^
+
+.. autoclass:: pybricks.pupdevices.DuploTrain
+  :no-members:
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.connect
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.disconnect
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.name
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.drive
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.headlights
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.sound
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.speed
+
+  .. automethod:: pybricks.pupdevices::DuploTrain.color

doc/main/pupdevices/index.rst

@@ -22,6 +22,9 @@
    colorlightmatrix
    light
    remote
+   technicmovehub
+   mariohub
+   duplotrain
 
 .. pybricks-classlink:: DCMotor
 
@@ -94,3 +97,15 @@
 .. figure:: ../../main/cad/output/pupdevice-remote.png
    :width: 50 %
    :target: remote.html
+
+.. pybricks-requirements:: pybricks-iodevices ble-extra
+
+.. pybricks-classlink:: TechnicMoveHub
+
+.. pybricks-requirements:: pybricks-iodevices ble-extra
+
+.. pybricks-classlink:: MarioHub
+
+.. pybricks-requirements:: pybricks-iodevices ble-extra
+
+.. pybricks-classlink:: DuploTrain

doc/main/pupdevices/mariohub.rst

@@ -0,0 +1,17 @@
+.. pybricks-requirements:: pybricks-iodevices ble-extra
+
+Mario Hub
+^^^^^^^^^
+
+.. autoclass:: pybricks.pupdevices.MarioHub
+  :no-members:
+
+  .. automethod:: pybricks.pupdevices::MarioHub.connect
+
+  .. automethod:: pybricks.pupdevices::MarioHub.disconnect
+
+  .. automethod:: pybricks.pupdevices::MarioHub.color
+
+  .. automethod:: pybricks.pupdevices::MarioHub.hsv
+
+  .. automethod:: pybricks.pupdevices::MarioHub.detectable_colors

doc/main/pupdevices/motor.rst

@@ -105,24 +105,24 @@ Motors with rotation sensors
     .. blockimg:: pybricks_blockMotorConfigure_motor_max_speed
 
     .. blockimg:: pybricks_blockMotorConfigure_motor_acceleration
-    
+
     .. blockimg:: pybricks_blockMotorConfigure_motor_max_torque
-    
-    .. automethod:: pybricks.pupdevices.Motor.control.limits
+
+    .. automethod:: pybricks.pupdevices::Motor.control.limits
 
     .. pybricks-requirements:: pybricks-common-control
 
-    .. automethod:: pybricks.pupdevices.Motor.control.pid
+    .. automethod:: pybricks.pupdevices::Motor.control.pid
 
     .. pybricks-requirements:: pybricks-common-control
 
     .. blockimg:: pybricks_blockMotorConfigure_motor_target_tolerances
 
-    .. automethod:: pybricks.pupdevices.Motor.control.target_tolerances
+    .. automethod:: pybricks.pupdevices::Motor.control.target_tolerances
 
     .. pybricks-requirements:: pybricks-common-control
 
-    .. automethod:: pybricks.pupdevices.Motor.control.stall_tolerances
+    .. automethod:: pybricks.pupdevices::Motor.control.stall_tolerances
 
     .. pybricks-requirements:: pybricks-common-control
 
@@ -139,11 +139,11 @@ Motors with rotation sensors
 
     .. pybricks-requirements:: pybricks-common-control
 
-    .. automethod:: pybricks.pupdevices.Motor.model.state
+    .. automethod:: pybricks.pupdevices::Motor.model.state
 
     .. pybricks-requirements:: pybricks-common-control
 
-    .. automethod:: pybricks.pupdevices.Motor.model.settings
+    .. automethod:: pybricks.pupdevices::Motor.model.settings
 
 Initialization examples
 -----------------------

doc/main/pupdevices/pfmotor.rst

@@ -21,23 +21,19 @@ and ambient conditions.
 .. blockimg:: pybricks_variables_set_pf_motor
 
 .. autoclass:: pybricks.pupdevices.PFMotor
-    :noindex:
     :no-members:
 
     .. blockimg:: pybricks_blockMotorDuty_PFMotor
 
     .. automethod:: pybricks.pupdevices.PFMotor.dc
-        :noindex:
 
     .. blockimg:: pybricks_blockMotorStop_PFMotor_coast
 
     .. automethod:: pybricks.pupdevices.PFMotor.stop
-        :noindex:
 
     .. blockimg:: pybricks_blockMotorStop_PFMotor_brake
 
     .. automethod:: pybricks.pupdevices.PFMotor.brake
-        :noindex:
 
 Examples
 -------------------

doc/main/pupdevices/remote.rst

@@ -13,6 +13,8 @@ Remote Control
 .. autoclass:: pybricks.pupdevices.Remote
   :no-members:
 
+  .. automethod:: pybricks.pupdevices::Remote.connect
+
   .. automethod:: pybricks.pupdevices::Remote.name
 
   .. blockimg:: pybricks_blockLightOnColor_remote_on

doc/main/pupdevices/technicmovehub.rst

@@ -0,0 +1,13 @@
+.. pybricks-requirements:: pybricks-iodevices ble-extra
+
+Technic Move Hub
+^^^^^^^^^^^^^^^^
+
+.. autoclass:: pybricks.pupdevices.TechnicMoveHub
+  :no-members:
+
+  .. automethod:: pybricks.pupdevices::TechnicMoveHub.connect
+
+  .. automethod:: pybricks.pupdevices::TechnicMoveHub.disconnect
+
+  .. automethod:: pybricks.pupdevices::TechnicMoveHub.drive

doc/main/pupdevices/tiltsensor.rst

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

doc/main/pupdevices/ultrasonicsensor.rst

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

doc/main/robotics.rst

@@ -27,25 +27,16 @@
 
     .. automethod:: pybricks.robotics.DriveBase.turn
 
-    .. versionchanged:: 3.6
-
-        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
 
+    .. pybricks-requirements:: stm32-float
+
+    .. automethod:: pybricks.robotics.DriveBase.move_by
+
     .. blockimg:: pybricks_blockDriveBaseConfigure_drivebase_straight_speed
 
     .. blockimg:: pybricks_blockDriveBaseConfigure_drivebase_straight_acceleration
@@ -80,6 +71,8 @@
 
     .. blockimg:: pybricks_blockDriveBaseStop_hold
 
+    .. automethod:: pybricks.robotics.DriveBase.hold
+
     .. rubric:: Measuring
 
     .. blockimg:: pybricks_blockDriveBaseMeasure_drivebase_get_distance

doc/main/signaltypes.rst

@@ -291,5 +291,5 @@ though the *hub* accelerates backward.
    How to configure the ``top_side`` and ``front_side`` settings for three
    different robot designs. The same technique can be applied to other hubs
    and other creations, by noting which way the top and
-   front :class:`Side <Side>` of the hub are pointing. The example
+   front :class:`Side <pybricks.parameters.Side>` of the hub are pointing. The example
    on the left is the default configuration.

examples/ev3/i2c_extra/main.py

@@ -10,7 +10,7 @@ ev3 = EV3Brick()
 device = I2CDevice(Port.S2, 0xD2 >> 1)
 
 # Recommended for reading
-(result,) = device.read(reg=0x0F, length=1)
+result = device.read(reg=0x0F, length=1)
 
 # Read 1 byte from no particular register:
 device.read(reg=None, length=1)

examples/pup/ble_radio/ble_broadcast.py

@@ -1,11 +1,10 @@
-# ThisHub = MoveHub CityHub TechnicHub PrimeHub EssentialHub
-from pybricks.hubs import ThisHub
 from pybricks.pupdevices import Motor
 from pybricks.parameters import Port
 from pybricks.tools import wait
+from pybricks.messaging import BLERadio
 
 # Initialize the hub.
-hub = ThisHub(broadcast_channel=1)
+radio = BLERadio(broadcast_channel=1)
 
 # Initialize the motors.
 left_motor = Motor(Port.A)
@@ -18,7 +17,7 @@ while True:
 
     # Set the broadcast data and start broadcasting if not already doing so.
     data = (left_angle, right_angle)
-    hub.ble.broadcast(data)
+    radio.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/ble_radio/ble_observe.py

@@ -1,11 +1,10 @@
-# ThisHub = MoveHub CityHub TechnicHub PrimeHub EssentialHub
-from pybricks.hubs import ThisHub
 from pybricks.pupdevices import Motor
-from pybricks.parameters import Color, Port
+from pybricks.parameters import Port
 from pybricks.tools import wait
+from pybricks.messaging import BLERadio
 
 # Initialize the hub.
-hub = ThisHub(observe_channels=[1])
+radio = BLERadio(observe_channels=[1])
 
 # Initialize the motors.
 left_motor = Motor(Port.A)
@@ -14,17 +13,12 @@ right_motor = Motor(Port.B)
 while True:
     # Receive broadcast from the other hub.
 
-    data = hub.ble.observe(1)
+    data = radio.observe(1)
 
-    if data is None:
-        # No data has been received in the last 1 second.
-        hub.light.on(Color.RED)
-    else:
+    if data is not None:
         # Data was received and is less that one second old.
-        hub.light.on(Color.GREEN)
-
-        # *data* contains the same values in the same order
-        # that were passed to hub.ble.broadcast() on the
+        # It contains the same values in the same order
+        # that were passed to radio.broadcast() on the
         # other hub.
         left_angle, right_angle = data
 

jedi/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## Unreleased
 
+## 1.17.0 - 2025-02-26
+
+### Changed
+- Updated `pybricks` package to v3.5.0b5.
+
 ## 1.16.0 - 2024-04-05
 
 ### Changed

jedi/build.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Builds the @pybricks/jedi npm package into npm-build/.
 
 import email.parser
 import json
@@ -6,18 +7,27 @@ import pathlib
 import shutil
 import subprocess
 import sys
+import tomllib
 import zipfile
 
-BUILD_DIR = (pathlib.Path(__file__).parent / "build").resolve()
+if len(sys.argv) != 2:
+    print(f"Usage: {sys.argv[0]} <version>", file=sys.stderr)
+    sys.exit(1)
+
+VERSION = sys.argv[1]
+
+ROOT_DIR = pathlib.Path(__file__).parent.resolve()
+REPO_ROOT_DIR = (ROOT_DIR / "..").resolve()
+BUILD_DIR = ROOT_DIR / "npm-build"
 
 package_json = {
     "name": "@pybricks/jedi",
-    "version": "1.16.0",
+    "version": VERSION,
     "description": "Binary distribution of pybricks-jedi Python package and dependencies for use with Pyodide.",
     "repository": {
         "type": "git",
-        "url": "https://github.com/pybricks/pybricks-api",
-        "directory": "npm/jedi",
+        "url": "git+https://github.com/pybricks/pybricks-api.git",
+        "directory": "jedi",
     },
     "publishConfig": {"registry": "https://registry.npmjs.org", "access": "public"},
 }
@@ -30,16 +40,28 @@ whl_map: dict[str, str] = {}
 shutil.rmtree(BUILD_DIR, True)
 BUILD_DIR.mkdir()
 
-# download package and dependencies (*.whl files)
+# build pybricks api wheel from local source so pip uses it instead of fetching from PyPI
+subprocess.check_call(["poetry", "build", "--format=wheel"], cwd=REPO_ROOT_DIR)
+
+# copy locally built pybricks wheel to build dir
+for whl in (REPO_ROOT_DIR / "dist").glob("pybricks-*.whl"):
+    shutil.copy(whl, BUILD_DIR)
+
+# build pybricks-jedi wheel from local source
+subprocess.check_call(["poetry", "build", "--format=wheel"], cwd=ROOT_DIR)
+
+# copy locally built wheel to build dir
+for whl in (ROOT_DIR / "dist").glob("pybricks_jedi-*.whl"):
+    shutil.copy(whl, BUILD_DIR)
+
+# download transitive dependencies using versions pinned in poetry.lock
+transitive_packages = ["jedi", "parso", "docstring-parser", "typing-extensions"]
+with open(ROOT_DIR / "poetry.lock", "rb") as f:
+    lock = tomllib.load(f)
+lock_versions = {pkg["name"]: pkg["version"] for pkg in lock["package"]}
+transitive = [f"{pkg}=={lock_versions[pkg]}" for pkg in transitive_packages]
 subprocess.check_call(
-    [
-        sys.executable,
-        "-m",
-        "pip",
-        "download",
-        "--only-binary=any",
-        "pybricks-jedi==1.16.0",
-    ],
+    [sys.executable, "-m", "pip", "download", "--only-binary=any"] + transitive,
     cwd=BUILD_DIR,
 )
 
@@ -79,13 +101,8 @@ for whl in BUILD_DIR.glob("*.whl"):
 
             license_identifiers.add(license)
 
-        # TODO: The LICENSE workaround for the pybricks-jedi package can be
-        # dropped after the next release of that package
         if whl.name.startswith("pybricks_jedi-"):
-            LICENSE = (
-                pathlib.Path(__file__).parent.parent.parent / "jedi" / "LICENSE"
-            ).resolve()
-            with open(LICENSE) as lf:
+            with open(ROOT_DIR / "LICENSE") as lf:
                 license_text[whl.name] = lf.read()
         else:
             try:
@@ -126,7 +143,4 @@ with open(BUILD_DIR / "LICENSE", "w") as f:
 
 # copy additional files
 
-ROOT_DIR = (pathlib.Path(__file__).parent).resolve()
-
-for file in "README.md", "CHANGELOG.md":
-    shutil.copy(ROOT_DIR / file, BUILD_DIR / file)
+shutil.copy(ROOT_DIR / "README.md", BUILD_DIR / "README.md")

jedi/poetry.lock

@@ -1,12 +1,12 @@
-# This file is automatically @generated by Poetry and should not be changed by hand.
+# This file is automatically @generated by Poetry 2.2.1 and should not be changed by hand.
 
 [[package]]
 name = "black"
 version = "22.12.0"
 description = "The uncompromising code formatter."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["dev"]
 files = [
     {file = "black-22.12.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9eedd20838bd5d75b80c9f5487dbcb06836a43833a37846cf1d8c1cc01cef59d"},
     {file = "black-22.12.0-cp310-cp310-win_amd64.whl", hash = "sha256:159a46a4947f73387b4d83e87ea006dbb2337eab6c879620a3ba52699b1f4351"},
@@ -37,14 +37,14 @@ uvloop = ["uvloop (>=0.15.2)"]
 
 [[package]]
 name = "click"
-version = "8.1.7"
+version = "8.1.8"
 description = "Composable command line interface toolkit"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["dev"]
 files = [
-    {file = "click-8.1.7-py3-none-any.whl", hash = "sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28"},
-    {file = "click-8.1.7.tar.gz", hash = "sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de"},
+    {file = "click-8.1.8-py3-none-any.whl", hash = "sha256:63c132bbbed01578a06712a2d1f497bb62d9c1c0d329b7903a866228027263b2"},
+    {file = "click-8.1.8.tar.gz", hash = "sha256:ed53c9d8990d83c2a27deae68e4ee337473f6330c040a31d4225c9574d16096a"},
 ]
 
 [package.dependencies]
@@ -54,9 +54,10 @@ colorama = {version = "*", markers = "platform_system == \"Windows\""}
 name = "colorama"
 version = "0.4.6"
 description = "Cross-platform colored terminal text."
-category = "dev"
 optional = false
 python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
+groups = ["dev"]
+markers = "sys_platform == \"win32\" or platform_system == \"Windows\""
 files = [
     {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
     {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
@@ -66,9 +67,9 @@ files = [
 name = "docstring-parser"
 version = "0.14.1"
 description = "Parse Python docstrings in reST, Google and Numpydoc format"
-category = "main"
 optional = false
 python-versions = ">=3.6,<4.0"
+groups = ["main"]
 files = [
     {file = "docstring_parser-0.14.1-py3-none-any.whl", hash = "sha256:14ac6ec1f1ba6905c4d8cb90fd0bc55394f5678183752c90e44812bf28d7a515"},
     {file = "docstring_parser-0.14.1.tar.gz", hash = "sha256:2c77522e31b7c88b1ab457a1f3c9ae38947ad719732260ba77ee8a3deb58622a"},
@@ -76,14 +77,15 @@ files = [
 
 [[package]]
 name = "exceptiongroup"
-version = "1.2.0"
+version = "1.2.2"
 description = "Backport of PEP 654 (exception groups)"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["dev"]
+markers = "python_version == \"3.10\""
 files = [
-    {file = "exceptiongroup-1.2.0-py3-none-any.whl", hash = "sha256:4bfd3996ac73b41e9b9628b04e079f193850720ea5945fc96a08633c66912f14"},
-    {file = "exceptiongroup-1.2.0.tar.gz", hash = "sha256:91f5c769735f051a4290d52edd0858999b57e5876e9f85937691bd4c9fa3ed68"},
+    {file = "exceptiongroup-1.2.2-py3-none-any.whl", hash = "sha256:3111b9d131c238bec2f8f516e123e14ba243563fb135d3fe885990585aa7795b"},
+    {file = "exceptiongroup-1.2.2.tar.gz", hash = "sha256:47c2edf7c6738fafb49fd34290706d1a1a2f4d1c6df275526b62cbb4aa5393cc"},
 ]
 
 [package.extras]
@@ -93,9 +95,9 @@ test = ["pytest (>=6)"]
 name = "flake8"
 version = "4.0.1"
 description = "the modular source code checker: pep8 pyflakes and co"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
+groups = ["dev"]
 files = [
     {file = "flake8-4.0.1-py2.py3-none-any.whl", hash = "sha256:479b1304f72536a55948cb40a32dce8bb0ffe3501e26eaf292c7e60eb5e0428d"},
     {file = "flake8-4.0.1.tar.gz", hash = "sha256:806e034dda44114815e23c16ef92f95c91e4c71100ff52813adf7132a6ad870d"},
@@ -110,9 +112,9 @@ pyflakes = ">=2.4.0,<2.5.0"
 name = "iniconfig"
 version = "2.0.0"
 description = "brain-dead simple config-ini parsing"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["dev"]
 files = [
     {file = "iniconfig-2.0.0-py3-none-any.whl", hash = "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374"},
     {file = "iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3"},
@@ -122,9 +124,9 @@ files = [
 name = "jedi"
 version = "0.18.1"
 description = "An autocompletion tool for Python that can be used for text editors."
-category = "main"
 optional = false
 python-versions = ">=3.6"
+groups = ["main"]
 files = [
     {file = "jedi-0.18.1-py2.py3-none-any.whl", hash = "sha256:637c9635fcf47945ceb91cd7f320234a7be540ded6f3e99a50cb6febdfd1ba8d"},
     {file = "jedi-0.18.1.tar.gz", hash = "sha256:74137626a64a99c8eb6ae5832d99b3bdd7d29a3850fe2aa80a4126b2a7d949ab"},
@@ -141,9 +143,9 @@ testing = ["Django (<3.1)", "colorama", "docopt", "pytest (<7.0.0)"]
 name = "mccabe"
 version = "0.6.1"
 description = "McCabe checker, plugin for flake8"
-category = "dev"
 optional = false
 python-versions = "*"
+groups = ["dev"]
 files = [
     {file = "mccabe-0.6.1-py2.py3-none-any.whl", hash = "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42"},
     {file = "mccabe-0.6.1.tar.gz", hash = "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"},
@@ -153,9 +155,9 @@ files = [
 name = "mypy-extensions"
 version = "1.0.0"
 description = "Type system extensions for programs checked with the mypy type checker."
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["dev"]
 files = [
     {file = "mypy_extensions-1.0.0-py3-none-any.whl", hash = "sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d"},
     {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"},
@@ -163,23 +165,23 @@ files = [
 
 [[package]]
 name = "packaging"
-version = "24.0"
+version = "24.2"
 description = "Core utilities for Python packages"
-category = "dev"
 optional = false
-python-versions = ">=3.7"
+python-versions = ">=3.8"
+groups = ["dev"]
 files = [
-    {file = "packaging-24.0-py3-none-any.whl", hash = "sha256:2ddfb553fdf02fb784c234c7ba6ccc288296ceabec964ad2eae3777778130bc5"},
-    {file = "packaging-24.0.tar.gz", hash = "sha256:eb82c5e3e56209074766e6885bb04b8c38a0c015d0a30036ebe7ece34c9989e9"},
+    {file = "packaging-24.2-py3-none-any.whl", hash = "sha256:09abb1bccd265c01f4a3aa3f7a7db064b36514d2cba19a2f694fe6150451a759"},
+    {file = "packaging-24.2.tar.gz", hash = "sha256:c228a6dc5e932d346bc5739379109d49e8853dd8223571c7c5b55260edc0b97f"},
 ]
 
 [[package]]
 name = "parso"
 version = "0.8.4"
 description = "A Python Parser"
-category = "main"
 optional = false
 python-versions = ">=3.6"
+groups = ["main"]
 files = [
     {file = "parso-0.8.4-py2.py3-none-any.whl", hash = "sha256:a418670a20291dacd2dddc80c377c5c3791378ee1e8d12bffc35420643d43f18"},
     {file = "parso-0.8.4.tar.gz", hash = "sha256:eb3a7b58240fb99099a345571deecc0f9540ea5f4dd2fe14c2a99d6b281ab92d"},
@@ -193,9 +195,9 @@ testing = ["docopt", "pytest"]
 name = "pathspec"
 version = "0.12.1"
 description = "Utility library for gitignore style pattern matching of file paths."
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["dev"]
 files = [
     {file = "pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08"},
     {file = "pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712"},
@@ -203,30 +205,31 @@ files = [
 
 [[package]]
 name = "platformdirs"
-version = "4.2.0"
-description = "A small Python package for determining appropriate platform-specific dirs, e.g. a \"user data dir\"."
-category = "dev"
+version = "4.3.6"
+description = "A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`."
 optional = false
 python-versions = ">=3.8"
+groups = ["dev"]
 files = [
-    {file = "platformdirs-4.2.0-py3-none-any.whl", hash = "sha256:0614df2a2f37e1a662acbd8e2b25b92ccf8632929bc6d43467e17fe89c75e068"},
-    {file = "platformdirs-4.2.0.tar.gz", hash = "sha256:ef0cc731df711022c174543cb70a9b5bd22e5a9337c8624ef2c2ceb8ddad8768"},
+    {file = "platformdirs-4.3.6-py3-none-any.whl", hash = "sha256:73e575e1408ab8103900836b97580d5307456908a03e92031bab39e4554cc3fb"},
+    {file = "platformdirs-4.3.6.tar.gz", hash = "sha256:357fb2acbc885b0419afd3ce3ed34564c13c9b95c89360cd9563f73aa5e2b907"},
 ]
 
 [package.extras]
-docs = ["furo (>=2023.9.10)", "proselint (>=0.13)", "sphinx (>=7.2.6)", "sphinx-autodoc-typehints (>=1.25.2)"]
-test = ["appdirs (==1.4.4)", "covdefaults (>=2.3)", "pytest (>=7.4.3)", "pytest-cov (>=4.1)", "pytest-mock (>=3.12)"]
+docs = ["furo (>=2024.8.6)", "proselint (>=0.14)", "sphinx (>=8.0.2)", "sphinx-autodoc-typehints (>=2.4)"]
+test = ["appdirs (==1.4.4)", "covdefaults (>=2.3)", "pytest (>=8.3.2)", "pytest-cov (>=5)", "pytest-mock (>=3.14)"]
+type = ["mypy (>=1.11.2)"]
 
 [[package]]
 name = "pluggy"
-version = "1.4.0"
+version = "1.5.0"
 description = "plugin and hook calling mechanisms for python"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["dev"]
 files = [
-    {file = "pluggy-1.4.0-py3-none-any.whl", hash = "sha256:7db9f7b503d67d1c5b95f59773ebb58a8c1c288129a88665838012cfb07b8981"},
-    {file = "pluggy-1.4.0.tar.gz", hash = "sha256:8c85c2876142a764e5b7548e7d9a0e0ddb46f5185161049a79b7e974454223be"},
+    {file = "pluggy-1.5.0-py3-none-any.whl", hash = "sha256:44e1ad92c8ca002de6377e165f3e0f1be63266ab4d554740532335b9d75ea669"},
+    {file = "pluggy-1.5.0.tar.gz", hash = "sha256:2cffa88e94fdc978c4c574f15f9e59b7f4201d439195c3715ca9e2486f1d0cf1"},
 ]
 
 [package.extras]
@@ -235,11 +238,11 @@ testing = ["pytest", "pytest-benchmark"]
 
 [[package]]
 name = "pybricks"
-version = "3.5.0b2"
+version = "4.0.0b10"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
-category = "main"
 optional = false
 python-versions = "^3.8"
+groups = ["main", "dev"]
 files = []
 develop = true
 
@@ -251,9 +254,9 @@ url = ".."
 name = "pycodestyle"
 version = "2.8.0"
 description = "Python style guide checker"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+groups = ["dev"]
 files = [
     {file = "pycodestyle-2.8.0-py2.py3-none-any.whl", hash = "sha256:720f8b39dde8b293825e7ff02c475f3077124006db4f440dcbc9a20b76548a20"},
     {file = "pycodestyle-2.8.0.tar.gz", hash = "sha256:eddd5847ef438ea1c7870ca7eb78a9d47ce0cdb4851a5523949f2601d0cbbe7f"},
@@ -263,9 +266,9 @@ files = [
 name = "pyflakes"
 version = "2.4.0"
 description = "passive checker of Python programs"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+groups = ["dev"]
 files = [
     {file = "pyflakes-2.4.0-py2.py3-none-any.whl", hash = "sha256:3bb3a3f256f4b7968c9c788781e4ff07dce46bdf12339dcda61053375426ee2e"},
     {file = "pyflakes-2.4.0.tar.gz", hash = "sha256:05a85c2872edf37a4ed30b0cce2f6093e1d0581f8c19d7393122da7e25b2b24c"},
@@ -275,9 +278,9 @@ files = [
 name = "pytest"
 version = "7.4.4"
 description = "pytest: simple powerful testing with Python"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["dev"]
 files = [
     {file = "pytest-7.4.4-py3-none-any.whl", hash = "sha256:b090cdf5ed60bf4c45261be03239c2c1c22df034fbffe691abe93cd80cea01d8"},
     {file = "pytest-7.4.4.tar.gz", hash = "sha256:2cf0005922c6ace4a3e2ec8b4080eb0d9753fdc93107415332f50ce9e7994280"},
@@ -296,29 +299,60 @@ testing = ["argcomplete", "attrs (>=19.2.0)", "hypothesis (>=3.56)", "mock", "no
 
 [[package]]
 name = "tomli"
-version = "2.0.1"
+version = "2.2.1"
 description = "A lil' TOML parser"
-category = "dev"
 optional = false
-python-versions = ">=3.7"
+python-versions = ">=3.8"
+groups = ["dev"]
+markers = "python_full_version < \"3.11.0a7\""
 files = [
-    {file = "tomli-2.0.1-py3-none-any.whl", hash = "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc"},
-    {file = "tomli-2.0.1.tar.gz", hash = "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f"},
+    {file = "tomli-2.2.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:678e4fa69e4575eb77d103de3df8a895e1591b48e740211bd1067378c69e8249"},
+    {file = "tomli-2.2.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:023aa114dd824ade0100497eb2318602af309e5a55595f76b626d6d9f3b7b0a6"},
+    {file = "tomli-2.2.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ece47d672db52ac607a3d9599a9d48dcb2f2f735c6c2d1f34130085bb12b112a"},
+    {file = "tomli-2.2.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6972ca9c9cc9f0acaa56a8ca1ff51e7af152a9f87fb64623e31d5c83700080ee"},
+    {file = "tomli-2.2.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:c954d2250168d28797dd4e3ac5cf812a406cd5a92674ee4c8f123c889786aa8e"},
+    {file = "tomli-2.2.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:8dd28b3e155b80f4d54beb40a441d366adcfe740969820caf156c019fb5c7ec4"},
+    {file = "tomli-2.2.1-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:e59e304978767a54663af13c07b3d1af22ddee3bb2fb0618ca1593e4f593a106"},
+    {file = "tomli-2.2.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:33580bccab0338d00994d7f16f4c4ec25b776af3ffaac1ed74e0b3fc95e885a8"},
+    {file = "tomli-2.2.1-cp311-cp311-win32.whl", hash = "sha256:465af0e0875402f1d226519c9904f37254b3045fc5084697cefb9bdde1ff99ff"},
+    {file = "tomli-2.2.1-cp311-cp311-win_amd64.whl", hash = "sha256:2d0f2fdd22b02c6d81637a3c95f8cd77f995846af7414c5c4b8d0545afa1bc4b"},
+    {file = "tomli-2.2.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4a8f6e44de52d5e6c657c9fe83b562f5f4256d8ebbfe4ff922c495620a7f6cea"},
+    {file = "tomli-2.2.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8d57ca8095a641b8237d5b079147646153d22552f1c637fd3ba7f4b0b29167a8"},
+    {file = "tomli-2.2.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4e340144ad7ae1533cb897d406382b4b6fede8890a03738ff1683af800d54192"},
+    {file = "tomli-2.2.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:db2b95f9de79181805df90bedc5a5ab4c165e6ec3fe99f970d0e302f384ad222"},
+    {file = "tomli-2.2.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:40741994320b232529c802f8bc86da4e1aa9f413db394617b9a256ae0f9a7f77"},
+    {file = "tomli-2.2.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:400e720fe168c0f8521520190686ef8ef033fb19fc493da09779e592861b78c6"},
+    {file = "tomli-2.2.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:02abe224de6ae62c19f090f68da4e27b10af2b93213d36cf44e6e1c5abd19fdd"},
+    {file = "tomli-2.2.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b82ebccc8c8a36f2094e969560a1b836758481f3dc360ce9a3277c65f374285e"},
+    {file = "tomli-2.2.1-cp312-cp312-win32.whl", hash = "sha256:889f80ef92701b9dbb224e49ec87c645ce5df3fa2cc548664eb8a25e03127a98"},
+    {file = "tomli-2.2.1-cp312-cp312-win_amd64.whl", hash = "sha256:7fc04e92e1d624a4a63c76474610238576942d6b8950a2d7f908a340494e67e4"},
+    {file = "tomli-2.2.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:f4039b9cbc3048b2416cc57ab3bda989a6fcf9b36cf8937f01a6e731b64f80d7"},
+    {file = "tomli-2.2.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:286f0ca2ffeeb5b9bd4fcc8d6c330534323ec51b2f52da063b11c502da16f30c"},
+    {file = "tomli-2.2.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a92ef1a44547e894e2a17d24e7557a5e85a9e1d0048b0b5e7541f76c5032cb13"},
+    {file = "tomli-2.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9316dc65bed1684c9a98ee68759ceaed29d229e985297003e494aa825ebb0281"},
+    {file = "tomli-2.2.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e85e99945e688e32d5a35c1ff38ed0b3f41f43fad8df0bdf79f72b2ba7bc5272"},
+    {file = "tomli-2.2.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ac065718db92ca818f8d6141b5f66369833d4a80a9d74435a268c52bdfa73140"},
+    {file = "tomli-2.2.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:d920f33822747519673ee656a4b6ac33e382eca9d331c87770faa3eef562aeb2"},
+    {file = "tomli-2.2.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a198f10c4d1b1375d7687bc25294306e551bf1abfa4eace6650070a5c1ae2744"},
+    {file = "tomli-2.2.1-cp313-cp313-win32.whl", hash = "sha256:d3f5614314d758649ab2ab3a62d4f2004c825922f9e370b29416484086b264ec"},
+    {file = "tomli-2.2.1-cp313-cp313-win_amd64.whl", hash = "sha256:a38aa0308e754b0e3c67e344754dff64999ff9b513e691d0e786265c93583c69"},
+    {file = "tomli-2.2.1-py3-none-any.whl", hash = "sha256:cb55c73c5f4408779d0cf3eef9f762b9c9f147a77de7b258bef0a5628adc85cc"},
+    {file = "tomli-2.2.1.tar.gz", hash = "sha256:cd45e1dc79c835ce60f7404ec8119f2eb06d38b1deba146f07ced3bbc44505ff"},
 ]
 
 [[package]]
 name = "typing-extensions"
 version = "4.2.0"
 description = "Backported and Experimental Type Hints for Python 3.7+"
-category = "main"
 optional = false
 python-versions = ">=3.7"
+groups = ["main"]
 files = [
     {file = "typing_extensions-4.2.0-py3-none-any.whl", hash = "sha256:6657594ee297170d19f67d55c05852a874e7eb634f4f753dbd667855e07c1708"},
     {file = "typing_extensions-4.2.0.tar.gz", hash = "sha256:f1c24655a0da0d1b67f07e17a5e6b2a105894e6824b92096378bb3668ef02376"},
 ]
 
 [metadata]
-lock-version = "2.0"
+lock-version = "2.1"
 python-versions = ">= 3.10, < 3.12"
-content-hash = "a634c0231937213565b3dff33539075fd544a4261bf8f84e99b294f34ec7edd4"
+content-hash = "6efcdeb3ce02cdd64b69d4d58466e0c7241681aa7f71432bf1a1d53764f305c0"

jedi/pyproject.toml

@@ -1,18 +1,20 @@
 [tool.poetry]
 name = "pybricks_jedi"
-version = "1.16.0"
+# Version is set automatically at build time from the root pyproject.toml. Do not edit.
+version = "0.0.0"
 description = "Code completion for Pybricks."
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 license = "MIT"
 
 [tool.poetry.dependencies]
 python = ">= 3.10, < 3.12"
-pybricks = "3.5.0b2"
+# Version is set automatically at build time from the root pyproject.toml. Do not edit.
+pybricks = "*"
 jedi = "0.18.1"
 typing-extensions = "4.2.0"
 docstring-parser = "0.14.1"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 pytest = "^7.1.2"
 black = "^22.3.0"
 flake8 = "^4.0.1"

jedi/src/pybricks_jedi/__init__.py

@@ -15,6 +15,7 @@ PYBRICKS_CODE_PACKAGES = {
     "pybricks",
     "pybricks.hubs",
     "pybricks.iodevices",
+    "pybricks.messaging",
     "pybricks.parameters",
     "pybricks.pupdevices",
     "pybricks.robotics",
@@ -490,6 +491,7 @@ def initialize():
         "pybricks.ev3dev.speaker",
         "pybricks.hubs",
         "pybricks.iodevices",
+        "pybricks.messaging",
         "pybricks.parameters",
         "pybricks.pupdevices",
         "pybricks.robotics",

jedi/tests/test_complete_city_hub.py

@@ -5,7 +5,6 @@
 Tests for correct code completion of the CityHub class.
 """
 
-
 import json
 from pybricks_jedi import CompletionItem, complete
 
@@ -33,7 +32,6 @@ def test_hub_dot():
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
         "battery",
-        "ble",
         "buttons",
         "light",
         "system",

jedi/tests/test_complete_essential_hub.py

@@ -5,7 +5,6 @@
 Tests for correct code completion of the EssentialHub class.
 """
 
-
 import json
 from pybricks_jedi import CompletionItem, complete
 
@@ -33,7 +32,6 @@ def test_hub_dot():
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
         "battery",
-        "ble",
         "buttons",
         "charger",
         "imu",

jedi/tests/test_complete_import.py

@@ -61,6 +61,7 @@ def test_from_pybricks_import():
     assert [c["insertText"] for c in completions] == [
         "hubs",
         "iodevices",
+        "messaging",
         "parameters",
         "pupdevices",
         "robotics",
@@ -75,6 +76,7 @@ def test_from_pybricks_dot():
     assert [c["insertText"] for c in completions] == [
         "hubs",
         "iodevices",
+        "messaging",
         "parameters",
         "pupdevices",
         "robotics",
@@ -102,7 +104,6 @@ def test_from_pybricks_iodevices_import():
     assert [c["insertText"] for c in completions] == [
         "AnalogSensor",
         "DCMotor",
-        "Ev3devSensor",
         "I2CDevice",
         "LUMPDevice",
         "LWP3Device",
@@ -135,12 +136,15 @@ def test_from_pybricks_pupdevices_import():
         "ColorLightMatrix",
         "ColorSensor",
         "DCMotor",
+        "DuploTrain",
         "ForceSensor",
         "InfraredSensor",
         "Light",
+        "MarioHub",
         "Motor",
         "PFMotor",
         "Remote",
+        "TechnicMoveHub",
         "TiltSensor",
         "UltrasonicSensor",
     ]

jedi/tests/test_complete_inventor_hub.py

@@ -5,7 +5,6 @@
 Tests for correct code completion of the InventorHub class.
 """
 
-
 import json
 from pybricks_jedi import complete, CompletionItem
 

jedi/tests/test_complete_messaging.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""
+Tests for correct code completion of the messaging module.
+"""
+
+import json
+
+import pytest
+from pybricks_jedi import CompletionItem, complete
+
+
+def test_from_pybricks_messaging_import():
+    code = "from pybricks.messaging import "
+    completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
+    assert [c["insertText"] for c in completions] == [
+        "AppData",
+        "BLERadio",
+        "BluetoothMailboxClient",
+        "BluetoothMailboxServer",
+        "Connection",
+        "LogicMailbox",
+        "Mailbox",
+        "NumericMailbox",
+        "TextMailbox",
+    ]
+
+
+def test_ble_radio_dot():
+    code = "\n".join(
+        [
+            "from pybricks.messaging import BLERadio",
+            "ble = BLERadio()",
+            "ble.",
+        ]
+    )
+    completions: list[CompletionItem] = json.loads(complete(code, 3, 5))
+    assert [c["insertText"] for c in completions] == [
+        "broadcast",
+        "observe",
+        "signal_strength",
+        "version",
+    ]
+
+
+def test_app_data_dot():
+    code = "\n".join(
+        [
+            "from pybricks.messaging import AppData",
+            "app = AppData([(0, 4)])",
+            "app.",
+        ]
+    )
+    completions: list[CompletionItem] = json.loads(complete(code, 3, 5))
+    assert [c["insertText"] for c in completions] == [
+        "close",
+        "configure",
+        "get_bytes",
+        "write_bytes",
+    ]

jedi/tests/test_complete_move_hub.py

@@ -5,7 +5,6 @@
 Tests for correct code completion of the MoveHub class.
 """
 
-
 import json
 from pybricks_jedi import CompletionItem, complete
 
@@ -33,7 +32,6 @@ def test_hub_dot():
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
         "battery",
-        "ble",
         "buttons",
         "imu",
         "light",

jedi/tests/test_complete_prime_hub.py

@@ -5,7 +5,6 @@
 Tests for correct code completion of the PrimeHub class.
 """
 
-
 import json
 from pybricks_jedi import CompletionItem, complete
 
@@ -33,7 +32,6 @@ def test_hub_dot():
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
         "battery",
-        "ble",
         "buttons",
         "charger",
         "display",

jedi/tests/test_complete_technic_hub.py

@@ -5,7 +5,6 @@
 Tests for correct code completion of the TechnicHub class.
 """
 
-
 import json
 from pybricks_jedi import CompletionItem, complete
 
@@ -33,7 +32,6 @@ def test_hub_dot():
     completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
     assert [c["insertText"] for c in completions] == [
         "battery",
-        "ble",
         "buttons",
         "imu",
         "light",

jedi/tests/test_get_signature.py

@@ -5,7 +5,6 @@
 Tests for correct signatures of the pupdevices.Motor class.
 """
 
-
 from itertools import zip_longest
 import json
 
@@ -86,12 +85,17 @@ CONSTRUCTOR_PARAMS = [
     pytest.param(
         "pybricks.hubs",
         "MoveHub",
-        [["broadcast_channel: int=None", "observe_channels: Sequence[int]=[]"]],
+        [
+            [
+                "top_side: Axis=Axis.Z",
+                "front_side: Axis=Axis.X",
+            ]
+        ],
     ),
     pytest.param(
         "pybricks.hubs",
         "CityHub",
-        [["broadcast_channel: int=None", "observe_channels: Sequence[int]=[]"]],
+        [[]],
     ),
     pytest.param(
         "pybricks.hubs",
@@ -100,8 +104,6 @@ CONSTRUCTOR_PARAMS = [
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=None",
-                "observe_channels: Sequence[int]=[]",
             ]
         ],
     ),
@@ -112,8 +114,6 @@ CONSTRUCTOR_PARAMS = [
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=None",
-                "observe_channels: Sequence[int]=[]",
             ]
         ],
     ),
@@ -124,8 +124,6 @@ CONSTRUCTOR_PARAMS = [
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=None",
-                "observe_channels: Sequence[int]=[]",
             ]
         ],
     ),
@@ -170,7 +168,7 @@ CONSTRUCTOR_PARAMS = [
     pytest.param(
         "pybricks.pupdevices",
         "Remote",
-        [["name: Optional[str]=None", "timeout: int=10000"]],
+        [["name: Optional[str]=None", "timeout: int=10000", "connect: bool=True"]],
     ),
     # TODO: iodevices go here
     pytest.param(
@@ -935,7 +933,7 @@ METHOD_PARAMS = [
         "pybricks.pupdevices",
         "Remote",
         "name",
-        [(["name: str"], "None"), ([], "str")],
+        [(["name: str"], "MaybeAwaitable"), ([], "str")],
     ),
     pytest.param(
         "pybricks.pupdevices",
@@ -973,7 +971,12 @@ METHOD_PARAMS = [
         "turn",
         [
             (
-                ["angle: Number", "then: Stop=Stop.HOLD", "wait: bool=True"],
+                [
+                    "angle: Number",
+                    "then: Stop=Stop.HOLD",
+                    "wait: bool=True",
+                    "absolute: bool=False",
+                ],
                 "MaybeAwaitable",
             )
         ],
@@ -981,12 +984,13 @@ METHOD_PARAMS = [
     pytest.param(
         "pybricks.robotics",
         "DriveBase",
-        "curve",
+        "arc",
         [
             (
                 [
                     "radius: Number",
-                    "angle: Number",
+                    "angle: Number=None",
+                    "distance: Number=None",
                     "then: Stop=Stop.HOLD",
                     "wait: bool=True",
                 ],
@@ -1002,13 +1006,16 @@ METHOD_PARAMS = [
             (
                 [
                     "straight_speed: Optional[Number]=None",
-                    "straight_acceleration: Optional[Number]=None",
+                    "straight_acceleration: Optional[Union[Number, Tuple[Number, Number]]]=None",
                     "turn_rate: Optional[Number]=None",
-                    "turn_acceleration: Optional[Number]=None",
+                    "turn_acceleration: Optional[Union[Number, Tuple[Number, Number]]]=None",
                 ],
                 "None",
             ),
-            ([], "Tuple[int, int, int, int]"),
+            (
+                [],
+                "Tuple[int, Union[int, Tuple[int, int]], int, Union[int, Tuple[int, int]]]",
+            ),
         ],
     ),
     pytest.param(
@@ -1020,7 +1027,7 @@ METHOD_PARAMS = [
     pytest.param("pybricks.robotics", "DriveBase", "stop", [([], "None")]),
     pytest.param("pybricks.robotics", "DriveBase", "brake", [([], "None")]),
     pytest.param("pybricks.robotics", "DriveBase", "distance", [([], "int")]),
-    pytest.param("pybricks.robotics", "DriveBase", "angle", [([], "int")]),
+    pytest.param("pybricks.robotics", "DriveBase", "angle", [([], "float")]),
     pytest.param(
         "pybricks.robotics", "DriveBase", "state", [([], "Tuple[int, int, int, int]")]
     ),

npm/ide-docs/.yarnrc

@@ -1,2 +0,0 @@
-version-tag-prefix "@pybricks/ide-docs/v"
-version-git-message "@pybricks/ide-docs v%s"

npm/ide-docs/CHANGELOG.md

@@ -1,114 +0,0 @@
-# Changelog
-
-<!-- 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
-- Updated docs to v3.5.0b2.
-
-## 2.17.0 - 2024-03-21
-
-### Changed
-- Updated docs to v3.5.0b1.
-
-## 2.16.0 - 2024-03-11
-
-### Changed
-- Updated docs to v3.4.0.
-
-## 2.15.0 - 2024-03-05
-
-### Changed
-- Updated docs to v3.4.0b5.
-
-## 2.14.0 - 2024-01-30
-
-### Changed
-- Updated docs to v3.4.0b3.
-
-## 2.13.0 - 2023-11-24
-
-### Changed
-- Updated docs to v3.4.0b1.
-
-## 2.12.0 - 2023-11-24
-
-### Changed
-- Updated docs to v3.3.0.
-
-## 2.11.0 - 2023-11-20
-
-### Changed
-- Updated docs to v3.3.0c1.
-
-## 2.10.0 - 2023-10-26
-
-### Changed
-- Updated docs to v3.3.0b9.
-
-## 2.9.0 - 2023-05-16
-
-### Changed
-- Updated docs to v3.3.0b5.
-
-## 2.8.0 - 2023-04-21
-
-### Changed
-- Updated docs to v3.3.0b4.
-
-## 2.7.0 - 2022-12-20
-
-### Changed
-- Updated docs to v3.2.0c2.
-
-## 2.6.0 - 2022-12-09
-
-### Changed
-- Updated docs to v3.2.0c1.
-
-## 2.5.0 - 2022-12-02
-
-### Changed
-- Updated docs to v3.2.0b6.
-
-## 2.4.0 - 2022-11-11
-
-### Changed
-- Updated docs to v3.2.0b5.
-
-## 2.3.0 - 2022-10-21
-
-### Changed
-- Updated docs to v3.2.0b4.
-
-## 2.2.0 - 2022-06-02
-
-### Changed
-- Updated docs to v3.2.0b1.
-
-## 2.1.0 - 2021-12-16
-
-### Changed
-- Updated docs to v3.1.0.
-
-## 2.0.1 - 2021-11-19
-
-### Fixed
-- Fixed link to Color Light Matrix page.
-
-## 2.0.0 - 2021-11-19
-
-### Changed
-- Changed package directory structure.
-- Updated docs to v3.1.0rc1.

npm/ide-docs/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@pybricks/ide-docs",
-  "version": "2.20.0",
+  "version": "0.0.0",
   "description": "Special build of Pybricks API docs for embedding in an IDE.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pybricks/pybricks-api",
+    "url": "git+https://github.com/pybricks/pybricks-api.git",
     "directory": "npm/ide-docs"
   },
   "publishConfig": {

npm/images/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 <!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
 
+## 1.4.0 - 2022-12-19
+
+### Added
+- Added existing NXT and EV3 hub images to published package.
+
 ## 1.3.0 - 2022-12-19
 
 ### Added

npm/images/build.py

@@ -9,16 +9,16 @@ BUILD_DIR = (pathlib.Path(__file__).parent / "build").resolve()
 IMAGE_DIR = (
     pathlib.Path(__file__).parent.parent.parent / "doc" / "main" / "diagrams"
 ).resolve()
-HUBS = ["move", "city", "technic", "prime", "essential", "inventor"]
+HUBS = ["move", "city", "technic", "prime", "essential", "inventor", "ev3", "nxt"]
 
 package_json = {
     "name": "@pybricks/images",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Distribution of Pybricks images.",
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/pybricks/pybricks-api",
+        "url": "git+https://github.com/pybricks/pybricks-api.git",
         "directory": "npm/images",
     },
     "publishConfig": {"registry": "https://registry.npmjs.org", "access": "public"},

npm/jedi/.yarnrc

@@ -1,2 +0,0 @@
-version-tag-prefix "@pybricks/jedi/v"
-version-git-message "@pybricks/jedi v%s"

npm/jedi/CHANGELOG.md

@@ -1,94 +0,0 @@
-# Changelog
-
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
-
-## Unreleased
-
-## 1.16.0 - 2024-04-05
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.16.0.
-
-## 1.15.0 - 2024-03-21
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.15.0.
-
-## 1.14.0 - 2024-03-05
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.14.0.
-
-## 1.13.0 - 2024-01-30
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.13.0.
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.12.0.
-
-## 1.12.0 - 2023-11-24
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.12.0.
-
-## 1.11.0 - 2023-11-20
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.11.0.
-
-## 1.10.0 - 2023-10-26
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.10.0.
-
-## 1.9.0 - 2023-05-16
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.9.0.
-
-## 1.8.0 - 2023-04-21
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.8.0.
-
-## 1.7.0 - 2022-12-28
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.7.0.
-
-## 1.6.0 - 2022-12-09
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.6.0.
-
-## 1.5.0 - 2022-12-02
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.5.0.
-
-## 1.4.0 - 2022-12-02
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.4.0.
-
-## 1.3.0 - 2022-11-11
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.3.0.
-
-## 1.2.0 - 2022-10-21
-
-### Changed
-- Updated `pybricks_jedi` Python package to v1.2.0.
-
-## 1.0.1 - 2022-09-07
-
-### Fixed
-- Fixed exports.
-- Fixed missing README and CHANGELOG.
-
-## 1.0.0 - 2022-09-07
-
-### Added
-- Added new @pybricks/jedi package.

poetry.lock

@@ -1,12 +1,12 @@
-# This file is automatically @generated by Poetry and should not be changed by hand.
+# This file is automatically @generated by Poetry 2.2.1 and should not be changed by hand.
 
 [[package]]
 name = "alabaster"
 version = "0.7.13"
 description = "A configurable sidebar-enabled Sphinx theme"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
+groups = ["doc"]
 files = [
     {file = "alabaster-0.7.13-py3-none-any.whl", hash = "sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3"},
     {file = "alabaster-0.7.13.tar.gz", hash = "sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2"},
@@ -16,9 +16,9 @@ files = [
 name = "babel"
 version = "2.13.0"
 description = "Internationalization utilities"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc"]
 files = [
     {file = "Babel-2.13.0-py3-none-any.whl", hash = "sha256:fbfcae1575ff78e26c7449136f1abbefc3c13ce542eeb13d43d50d8b047216ec"},
     {file = "Babel-2.13.0.tar.gz", hash = "sha256:04c3e2d28d2b7681644508f836be388ae49e0cfe91465095340395b60d00f210"},
@@ -34,9 +34,9 @@ dev = ["freezegun (>=1.0,<2.0)", "pytest (>=6.0)", "pytest-cov"]
 name = "black"
 version = "22.12.0"
 description = "The uncompromising code formatter."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["lint"]
 files = [
     {file = "black-22.12.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9eedd20838bd5d75b80c9f5487dbcb06836a43833a37846cf1d8c1cc01cef59d"},
     {file = "black-22.12.0-cp310-cp310-win_amd64.whl", hash = "sha256:159a46a4947f73387b4d83e87ea006dbb2337eab6c879620a3ba52699b1f4351"},
@@ -70,9 +70,9 @@ uvloop = ["uvloop (>=0.15.2)"]
 name = "certifi"
 version = "2023.7.22"
 description = "Python package for providing Mozilla's CA Bundle."
-category = "dev"
 optional = false
 python-versions = ">=3.6"
+groups = ["doc"]
 files = [
     {file = "certifi-2023.7.22-py3-none-any.whl", hash = "sha256:92d6037539857d8206b8f6ae472e8b77db8058fec5937a1ef3f54304089edbb9"},
     {file = "certifi-2023.7.22.tar.gz", hash = "sha256:539cc1d13202e33ca466e88b2807e29f4c13049d6d87031a3c110744495cb082"},
@@ -82,9 +82,9 @@ files = [
 name = "chardet"
 version = "5.2.0"
 description = "Universal encoding detector for Python 3"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["lint"]
 files = [
     {file = "chardet-5.2.0-py3-none-any.whl", hash = "sha256:e1cf59446890a00105fe7b7912492ea04b6e6f06d4b742b2c788469e34c82970"},
     {file = "chardet-5.2.0.tar.gz", hash = "sha256:1b3b6ff479a8c414bc3fa2c0852995695c4a026dcd6d0633b2dd092ca39c1cf7"},
@@ -94,9 +94,9 @@ files = [
 name = "charset-normalizer"
 version = "3.3.1"
 description = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet."
-category = "dev"
 optional = false
 python-versions = ">=3.7.0"
+groups = ["doc"]
 files = [
     {file = "charset-normalizer-3.3.1.tar.gz", hash = "sha256:d9137a876020661972ca6eec0766d81aef8a5627df628b664b234b73396e727e"},
     {file = "charset_normalizer-3.3.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:8aee051c89e13565c6bd366813c386939f8e928af93c29fda4af86d25b73d8f8"},
@@ -194,9 +194,9 @@ files = [
 name = "click"
 version = "8.1.7"
 description = "Composable command line interface toolkit"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["lint"]
 files = [
     {file = "click-8.1.7-py3-none-any.whl", hash = "sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28"},
     {file = "click-8.1.7.tar.gz", hash = "sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de"},
@@ -209,21 +209,22 @@ colorama = {version = "*", markers = "platform_system == \"Windows\""}
 name = "colorama"
 version = "0.4.6"
 description = "Cross-platform colored terminal text."
-category = "dev"
 optional = false
 python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
+groups = ["doc", "lint"]
 files = [
     {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
     {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
 ]
+markers = {doc = "sys_platform == \"win32\"", lint = "platform_system == \"Windows\""}
 
 [[package]]
 name = "doc8"
 version = "0.8.1"
 description = "Style checker for Sphinx (or other) RST documentation"
-category = "dev"
 optional = false
 python-versions = "*"
+groups = ["lint"]
 files = [
     {file = "doc8-0.8.1-py2.py3-none-any.whl", hash = "sha256:4d58a5c8c56cedd2b2c9d6e3153be5d956cf72f6051128f0f2255c66227df721"},
     {file = "doc8-0.8.1.tar.gz", hash = "sha256:4d1df12598807cf08ffa9a1d5ef42d229ee0de42519da01b768ff27211082c12"},
@@ -241,9 +242,9 @@ stevedore = "*"
 name = "docutils"
 version = "0.18.1"
 description = "Docutils -- Python Documentation Utilities"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+groups = ["doc", "lint"]
 files = [
     {file = "docutils-0.18.1-py2.py3-none-any.whl", hash = "sha256:23010f129180089fbcd3bc08cfefccb3b890b0050e1ca00c867036e9d161b98c"},
     {file = "docutils-0.18.1.tar.gz", hash = "sha256:679987caf361a7539d76e584cbeddc311e3aee937877c87346f31debc63e9d06"},
@@ -253,9 +254,9 @@ files = [
 name = "flake8"
 version = "4.0.1"
 description = "the modular source code checker: pep8 pyflakes and co"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
+groups = ["lint"]
 files = [
     {file = "flake8-4.0.1-py2.py3-none-any.whl", hash = "sha256:479b1304f72536a55948cb40a32dce8bb0ffe3501e26eaf292c7e60eb5e0428d"},
     {file = "flake8-4.0.1.tar.gz", hash = "sha256:806e034dda44114815e23c16ef92f95c91e4c71100ff52813adf7132a6ad870d"},
@@ -270,9 +271,9 @@ pyflakes = ">=2.4.0,<2.5.0"
 name = "idna"
 version = "3.4"
 description = "Internationalized Domain Names in Applications (IDNA)"
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["doc"]
 files = [
     {file = "idna-3.4-py3-none-any.whl", hash = "sha256:90b77e79eaa3eba6de819a0c442c0b4ceefc341a7a2ab77d7562bf49f425c5c2"},
     {file = "idna-3.4.tar.gz", hash = "sha256:814f528e8dead7d329833b91c5faa87d60bf71824cd12a7530b5526063d02cb4"},
@@ -282,9 +283,9 @@ files = [
 name = "imagesize"
 version = "1.4.1"
 description = "Getting image size from png/jpeg/jpeg2000/gif file"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+groups = ["doc"]
 files = [
     {file = "imagesize-1.4.1-py2.py3-none-any.whl", hash = "sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b"},
     {file = "imagesize-1.4.1.tar.gz", hash = "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a"},
@@ -294,9 +295,10 @@ files = [
 name = "importlib-metadata"
 version = "6.8.0"
 description = "Read metadata from Python packages"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["doc"]
+markers = "python_version < \"3.10\""
 files = [
     {file = "importlib_metadata-6.8.0-py3-none-any.whl", hash = "sha256:3ebb78df84a805d7698245025b975d9d67053cd94c79245ba4b3eb694abe68bb"},
     {file = "importlib_metadata-6.8.0.tar.gz", hash = "sha256:dbace7892d8c0c4ac1ad096662232f831d4e64f4c4545bd53016a3e9d4654743"},
@@ -308,15 +310,15 @@ zipp = ">=0.5"
 [package.extras]
 docs = ["furo", "jaraco.packaging (>=9)", "jaraco.tidelift (>=1.4)", "rst.linker (>=1.9)", "sphinx (>=3.5)", "sphinx-lint"]
 perf = ["ipython"]
-testing = ["flufl.flake8", "importlib-resources (>=1.3)", "packaging", "pyfakefs", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-mypy (>=0.9.1)", "pytest-perf (>=0.9.2)", "pytest-ruff"]
+testing = ["flufl.flake8", "importlib-resources (>=1.3) ; python_version < \"3.9\"", "packaging", "pyfakefs", "pytest (>=6)", "pytest-black (>=0.3.7) ; platform_python_implementation != \"PyPy\"", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-mypy (>=0.9.1) ; platform_python_implementation != \"PyPy\"", "pytest-perf (>=0.9.2)", "pytest-ruff"]
 
 [[package]]
 name = "jinja2"
 version = "3.1.2"
 description = "A very fast and expressive template engine."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc"]
 files = [
     {file = "Jinja2-3.1.2-py3-none-any.whl", hash = "sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61"},
     {file = "Jinja2-3.1.2.tar.gz", hash = "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852"},
@@ -332,9 +334,9 @@ i18n = ["Babel (>=2.7)"]
 name = "markupsafe"
 version = "2.1.3"
 description = "Safely add untrusted strings to HTML/XML markup."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc"]
 files = [
     {file = "MarkupSafe-2.1.3-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:cd0f502fe016460680cd20aaa5a76d241d6f35a1c3350c474bac1273803893fa"},
     {file = "MarkupSafe-2.1.3-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e09031c87a1e51556fdcb46e5bd4f59dfb743061cf93c4d6831bf894f125eb57"},
@@ -356,6 +358,16 @@ files = [
     {file = "MarkupSafe-2.1.3-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:5bbe06f8eeafd38e5d0a4894ffec89378b6c6a625ff57e3028921f8ff59318ac"},
     {file = "MarkupSafe-2.1.3-cp311-cp311-win32.whl", hash = "sha256:dd15ff04ffd7e05ffcb7fe79f1b98041b8ea30ae9234aed2a9168b5797c3effb"},
     {file = "MarkupSafe-2.1.3-cp311-cp311-win_amd64.whl", hash = "sha256:134da1eca9ec0ae528110ccc9e48041e0828d79f24121a1a146161103c76e686"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:f698de3fd0c4e6972b92290a45bd9b1536bffe8c6759c62471efaa8acb4c37bc"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:aa57bd9cf8ae831a362185ee444e15a93ecb2e344c8e52e4d721ea3ab6ef1823"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ffcc3f7c66b5f5b7931a5aa68fc9cecc51e685ef90282f4a82f0f5e9b704ad11"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47d4f1c5f80fc62fdd7777d0d40a2e9dda0a05883ab11374334f6c4de38adffd"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1f67c7038d560d92149c060157d623c542173016c4babc0c1913cca0564b9939"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:9aad3c1755095ce347e26488214ef77e0485a3c34a50c5a5e2471dff60b9dd9c"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:14ff806850827afd6b07a5f32bd917fb7f45b046ba40c57abdb636674a8b559c"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8f9293864fe09b8149f0cc42ce56e3f0e54de883a9de90cd427f191c346eb2e1"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-win32.whl", hash = "sha256:715d3562f79d540f251b99ebd6d8baa547118974341db04f5ad06d5ea3eb8007"},
+    {file = "MarkupSafe-2.1.3-cp312-cp312-win_amd64.whl", hash = "sha256:1b8dd8c3fd14349433c79fa8abeb573a55fc0fdd769133baac1f5e07abf54aeb"},
     {file = "MarkupSafe-2.1.3-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:8e254ae696c88d98da6555f5ace2279cf7cd5b3f52be2b5cf97feafe883b58d2"},
     {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cb0932dc158471523c9637e807d9bfb93e06a95cbf010f1a38b98623b929ef2b"},
     {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9402b03f1a1b4dc4c19845e5c749e3ab82d5078d16a2a4c2cd2df62d57bb0707"},
@@ -392,9 +404,9 @@ files = [
 name = "mccabe"
 version = "0.6.1"
 description = "McCabe checker, plugin for flake8"
-category = "dev"
 optional = false
 python-versions = "*"
+groups = ["lint"]
 files = [
     {file = "mccabe-0.6.1-py2.py3-none-any.whl", hash = "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42"},
     {file = "mccabe-0.6.1.tar.gz", hash = "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"},
@@ -404,9 +416,9 @@ files = [
 name = "mypy-extensions"
 version = "1.0.0"
 description = "Type system extensions for programs checked with the mypy type checker."
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["lint"]
 files = [
     {file = "mypy_extensions-1.0.0-py3-none-any.whl", hash = "sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d"},
     {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"},
@@ -416,9 +428,9 @@ files = [
 name = "packaging"
 version = "23.2"
 description = "Core utilities for Python packages"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc"]
 files = [
     {file = "packaging-23.2-py3-none-any.whl", hash = "sha256:8c491190033a9af7e1d931d0b5dacc2ef47509b34dd0de67ed209b5203fc88c7"},
     {file = "packaging-23.2.tar.gz", hash = "sha256:048fb0e9405036518eaaf48a55953c750c11e1a1b68e0dd1a9d62ed0c092cfc5"},
@@ -428,9 +440,9 @@ files = [
 name = "pathspec"
 version = "0.11.2"
 description = "Utility library for gitignore style pattern matching of file paths."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["lint"]
 files = [
     {file = "pathspec-0.11.2-py3-none-any.whl", hash = "sha256:1d6ed233af05e679efb96b1851550ea95bbb64b7c490b0f5aa52996c11e92a20"},
     {file = "pathspec-0.11.2.tar.gz", hash = "sha256:e0d8d0ac2f12da61956eb2306b69f9469b42f4deb0f3cb6ed47b9cce9996ced3"},
@@ -440,9 +452,9 @@ files = [
 name = "pbr"
 version = "5.11.1"
 description = "Python Build Reasonableness"
-category = "dev"
 optional = false
 python-versions = ">=2.6"
+groups = ["lint"]
 files = [
     {file = "pbr-5.11.1-py2.py3-none-any.whl", hash = "sha256:567f09558bae2b3ab53cb3c1e2e33e726ff3338e7bae3db5dc954b3a44eef12b"},
     {file = "pbr-5.11.1.tar.gz", hash = "sha256:aefc51675b0b533d56bb5fd1c8c6c0522fe31896679882e1c4c63d5e4a0fccb3"},
@@ -452,9 +464,9 @@ files = [
 name = "platformdirs"
 version = "3.11.0"
 description = "A small Python package for determining appropriate platform-specific dirs, e.g. a \"user data dir\"."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["lint"]
 files = [
     {file = "platformdirs-3.11.0-py3-none-any.whl", hash = "sha256:e9d171d00af68be50e9202731309c4e658fd8bc76f55c11c7dd760d023bda68e"},
     {file = "platformdirs-3.11.0.tar.gz", hash = "sha256:cf8ee52a3afdb965072dcc652433e0c7e3e40cf5ea1477cd4b3b1d2eb75495b3"},
@@ -468,9 +480,9 @@ test = ["appdirs (==1.4.4)", "covdefaults (>=2.3)", "pytest (>=7.4)", "pytest-co
 name = "pycodestyle"
 version = "2.8.0"
 description = "Python style guide checker"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+groups = ["lint"]
 files = [
     {file = "pycodestyle-2.8.0-py2.py3-none-any.whl", hash = "sha256:720f8b39dde8b293825e7ff02c475f3077124006db4f440dcbc9a20b76548a20"},
     {file = "pycodestyle-2.8.0.tar.gz", hash = "sha256:eddd5847ef438ea1c7870ca7eb78a9d47ce0cdb4851a5523949f2601d0cbbe7f"},
@@ -480,9 +492,9 @@ files = [
 name = "pyflakes"
 version = "2.4.0"
 description = "passive checker of Python programs"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+groups = ["lint"]
 files = [
     {file = "pyflakes-2.4.0-py2.py3-none-any.whl", hash = "sha256:3bb3a3f256f4b7968c9c788781e4ff07dce46bdf12339dcda61053375426ee2e"},
     {file = "pyflakes-2.4.0.tar.gz", hash = "sha256:05a85c2872edf37a4ed30b0cce2f6093e1d0581f8c19d7393122da7e25b2b24c"},
@@ -492,24 +504,25 @@ files = [
 name = "pygments"
 version = "2.16.1"
 description = "Pygments is a syntax highlighting package written in Python."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc", "lint"]
 files = [
     {file = "Pygments-2.16.1-py3-none-any.whl", hash = "sha256:13fc09fa63bc8d8671a6d247e1eb303c4b343eaee81d861f3404db2935653692"},
     {file = "Pygments-2.16.1.tar.gz", hash = "sha256:1daff0494820c69bc8941e407aa20f577374ee88364ee10a98fdbe0aece96e29"},
 ]
 
 [package.extras]
-plugins = ["importlib-metadata"]
+plugins = ["importlib-metadata ; python_version < \"3.8\""]
 
 [[package]]
 name = "pytz"
 version = "2023.3.post1"
 description = "World timezone definitions, modern and historical"
-category = "dev"
 optional = false
 python-versions = "*"
+groups = ["doc"]
+markers = "python_version == \"3.8\""
 files = [
     {file = "pytz-2023.3.post1-py2.py3-none-any.whl", hash = "sha256:ce42d816b81b68506614c11e8937d3aa9e41007ceb50bfdcb0749b921bf646c7"},
     {file = "pytz-2023.3.post1.tar.gz", hash = "sha256:7b4fddbeb94a1eba4b557da24f19fdf9db575192544270a9101d8509f9f43d7b"},
@@ -519,9 +532,9 @@ files = [
 name = "requests"
 version = "2.31.0"
 description = "Python HTTP for Humans."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc"]
 files = [
     {file = "requests-2.31.0-py3-none-any.whl", hash = "sha256:58cd2187c01e70e6e26505bca751777aa9f2ee0b7f4300988b709f44e013003f"},
     {file = "requests-2.31.0.tar.gz", hash = "sha256:942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af05c3d2791656dbd6ad1e1"},
@@ -541,9 +554,9 @@ use-chardet-on-py3 = ["chardet (>=3.0.2,<6)"]
 name = "restructuredtext-lint"
 version = "1.4.0"
 description = "reStructuredText linter"
-category = "dev"
 optional = false
 python-versions = "*"
+groups = ["lint"]
 files = [
     {file = "restructuredtext_lint-1.4.0.tar.gz", hash = "sha256:1b235c0c922341ab6c530390892eb9e92f90b9b75046063e047cacfb0f050c45"},
 ]
@@ -555,9 +568,9 @@ docutils = ">=0.11,<1.0"
 name = "six"
 version = "1.16.0"
 description = "Python 2 and 3 compatibility utilities"
-category = "dev"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*"
+groups = ["lint"]
 files = [
     {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"},
     {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"},
@@ -567,9 +580,9 @@ files = [
 name = "snowballstemmer"
 version = "2.2.0"
 description = "This package provides 29 stemmers for 28 languages generated from Snowball algorithms."
-category = "dev"
 optional = false
 python-versions = "*"
+groups = ["doc"]
 files = [
     {file = "snowballstemmer-2.2.0-py2.py3-none-any.whl", hash = "sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a"},
     {file = "snowballstemmer-2.2.0.tar.gz", hash = "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1"},
@@ -579,9 +592,9 @@ files = [
 name = "Sphinx"
 version = "5.1.0.dev20231023"
 description = "Python documentation generator"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
+groups = ["doc"]
 files = []
 develop = false
 
@@ -619,9 +632,9 @@ resolved_reference = "cd277d098ea2df9c79f0a4cbce28a426ec4120bc"
 name = "sphinx-rtd-theme"
 version = "1.3.0"
 description = "Read the Docs theme for Sphinx"
-category = "dev"
 optional = false
 python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7"
+groups = ["doc"]
 files = [
     {file = "sphinx_rtd_theme-1.3.0-py2.py3-none-any.whl", hash = "sha256:46ddef89cc2416a81ecfbeaceab1881948c014b1b6e4450b815311a89fb977b0"},
     {file = "sphinx_rtd_theme-1.3.0.tar.gz", hash = "sha256:590b030c7abb9cf038ec053b95e5380b5c70d61591eb0b552063fbe7c41f0931"},
@@ -639,9 +652,9 @@ dev = ["bump2version", "sphinxcontrib-httpdomain", "transifex-client", "wheel"]
 name = "sphinxcontrib-applehelp"
 version = "1.0.4"
 description = "sphinxcontrib-applehelp is a Sphinx extension which outputs Apple help books"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-applehelp-1.0.4.tar.gz", hash = "sha256:828f867945bbe39817c210a1abfd1bc4895c8b73fcaade56d45357a348a07d7e"},
     {file = "sphinxcontrib_applehelp-1.0.4-py3-none-any.whl", hash = "sha256:29d341f67fb0f6f586b23ad80e072c8e6ad0b48417db2bde114a4c9746feb228"},
@@ -655,9 +668,9 @@ test = ["pytest"]
 name = "sphinxcontrib-devhelp"
 version = "1.0.2"
 description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document."
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-devhelp-1.0.2.tar.gz", hash = "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"},
     {file = "sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e"},
@@ -671,9 +684,9 @@ test = ["pytest"]
 name = "sphinxcontrib-htmlhelp"
 version = "2.0.1"
 description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-htmlhelp-2.0.1.tar.gz", hash = "sha256:0cbdd302815330058422b98a113195c9249825d681e18f11e8b1f78a2f11efff"},
     {file = "sphinxcontrib_htmlhelp-2.0.1-py3-none-any.whl", hash = "sha256:c38cb46dccf316c79de6e5515e1770414b797162b23cd3d06e67020e1d2a6903"},
@@ -687,9 +700,9 @@ test = ["html5lib", "pytest"]
 name = "sphinxcontrib-jquery"
 version = "4.1"
 description = "Extension to include jQuery on newer Sphinx releases"
-category = "dev"
 optional = false
 python-versions = ">=2.7"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-jquery-4.1.tar.gz", hash = "sha256:1620739f04e36a2c779f1a131a2dfd49b2fd07351bf1968ced074365933abc7a"},
     {file = "sphinxcontrib_jquery-4.1-py2.py3-none-any.whl", hash = "sha256:f936030d7d0147dd026a4f2b5a57343d233f1fc7b363f68b3d4f1cb0993878ae"},
@@ -702,9 +715,9 @@ Sphinx = ">=1.8"
 name = "sphinxcontrib-jsmath"
 version = "1.0.1"
 description = "A sphinx extension which renders display math in HTML via JavaScript"
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"},
     {file = "sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178"},
@@ -717,9 +730,9 @@ test = ["flake8", "mypy", "pytest"]
 name = "sphinxcontrib-qthelp"
 version = "1.0.3"
 description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document."
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-qthelp-1.0.3.tar.gz", hash = "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72"},
     {file = "sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"},
@@ -733,9 +746,9 @@ test = ["pytest"]
 name = "sphinxcontrib-serializinghtml"
 version = "1.1.5"
 description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)."
-category = "dev"
 optional = false
 python-versions = ">=3.5"
+groups = ["doc"]
 files = [
     {file = "sphinxcontrib-serializinghtml-1.1.5.tar.gz", hash = "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"},
     {file = "sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl", hash = "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd"},
@@ -749,9 +762,9 @@ test = ["pytest"]
 name = "stevedore"
 version = "5.1.0"
 description = "Manage dynamic plugins for Python applications"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["lint"]
 files = [
     {file = "stevedore-5.1.0-py3-none-any.whl", hash = "sha256:8cc040628f3cea5d7128f2e76cf486b2251a4e543c7b938f58d9a377f6694a2d"},
     {file = "stevedore-5.1.0.tar.gz", hash = "sha256:a54534acf9b89bc7ed264807013b505bf07f74dbe4bcfa37d32bd063870b087c"},
@@ -764,9 +777,9 @@ pbr = ">=2.0.0,<2.1.0 || >2.1.0"
 name = "toml"
 version = "0.10.2"
 description = "Python Library for Tom's Obvious, Minimal Language"
-category = "dev"
 optional = false
 python-versions = ">=2.6, !=3.0.*, !=3.1.*, !=3.2.*"
+groups = ["doc"]
 files = [
     {file = "toml-0.10.2-py2.py3-none-any.whl", hash = "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b"},
     {file = "toml-0.10.2.tar.gz", hash = "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"},
@@ -776,9 +789,10 @@ files = [
 name = "tomli"
 version = "2.0.1"
 description = "A lil' TOML parser"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["lint"]
+markers = "python_full_version < \"3.11.0a7\""
 files = [
     {file = "tomli-2.0.1-py3-none-any.whl", hash = "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc"},
     {file = "tomli-2.0.1.tar.gz", hash = "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f"},
@@ -788,9 +802,10 @@ files = [
 name = "typing-extensions"
 version = "4.8.0"
 description = "Backported and Experimental Type Hints for Python 3.8+"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["lint"]
+markers = "python_version < \"3.10\""
 files = [
     {file = "typing_extensions-4.8.0-py3-none-any.whl", hash = "sha256:8f92fc8806f9a6b641eaa5318da32b44d401efaac0f6678c9bc448ba3605faa0"},
     {file = "typing_extensions-4.8.0.tar.gz", hash = "sha256:df8e4339e9cb77357558cbdbceca33c303714cf861d1eef15e1070055ae8b7ef"},
@@ -800,16 +815,16 @@ files = [
 name = "urllib3"
 version = "2.0.7"
 description = "HTTP library with thread-safe connection pooling, file post, and more."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
+groups = ["doc"]
 files = [
     {file = "urllib3-2.0.7-py3-none-any.whl", hash = "sha256:fdb6d215c776278489906c2f8916e6e7d4f5a9b602ccbcfdf7f016fc8da0596e"},
     {file = "urllib3-2.0.7.tar.gz", hash = "sha256:c97dfde1f7bd43a71c8d2a58e369e9b2bf692d1334ea9f9cae55add7d0dd0f84"},
 ]
 
 [package.extras]
-brotli = ["brotli (>=1.0.9)", "brotlicffi (>=0.8.0)"]
+brotli = ["brotli (>=1.0.9) ; platform_python_implementation == \"CPython\"", "brotlicffi (>=0.8.0) ; platform_python_implementation != \"CPython\""]
 secure = ["certifi", "cryptography (>=1.9)", "idna (>=2.0.0)", "pyopenssl (>=17.1.0)", "urllib3-secure-extra"]
 socks = ["pysocks (>=1.5.6,!=1.5.7,<2.0)"]
 zstd = ["zstandard (>=0.18.0)"]
@@ -818,9 +833,10 @@ zstd = ["zstandard (>=0.18.0)"]
 name = "zipp"
 version = "3.17.0"
 description = "Backport of pathlib-compatible object wrapper for zip files"
-category = "dev"
 optional = false
 python-versions = ">=3.8"
+groups = ["doc"]
+markers = "python_version < \"3.10\""
 files = [
     {file = "zipp-3.17.0-py3-none-any.whl", hash = "sha256:0e923e726174922dce09c53c59ad483ff7bbb8e572e00c7f7c46b88556409f31"},
     {file = "zipp-3.17.0.tar.gz", hash = "sha256:84e64a1c28cf7e91ed2078bb8cc8c259cb19b76942096c8d7b84947690cabaf0"},
@@ -828,9 +844,9 @@ files = [
 
 [package.extras]
 docs = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "rst.linker (>=1.9)", "sphinx (<7.2.5)", "sphinx (>=3.5)", "sphinx-lint"]
-testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-ignore-flaky", "pytest-mypy (>=0.9.1)", "pytest-ruff"]
+testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "pytest (>=6)", "pytest-black (>=0.3.7) ; platform_python_implementation != \"PyPy\"", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-ignore-flaky", "pytest-mypy (>=0.9.1) ; platform_python_implementation != \"PyPy\"", "pytest-ruff"]
 
 [metadata]
-lock-version = "2.0"
+lock-version = "2.1"
 python-versions = "^3.8"
 content-hash = "c3ac22f3861c372d4572b51aa6263a693a8c42a7fa77ff5e735fea3be0e3f15b"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.6.0b5"
+version = "4.0.0b11"
 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

@@ -40,6 +40,8 @@ if TYPE_CHECKING:
 
     class MaybeAwaitableColor(Color, Awaitable[Color]): ...
 
+    class MaybeAwaitableBytes(bytes, Awaitable[bytes]): ...
+
 
 class System:
     """System control actions for a hub."""
@@ -123,12 +125,15 @@ class System:
            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.
+         - ``"host_connected_ble"``: ``True`` if the hub is connected to a
+           computer, tablet, or phone via Bluetooth, and ``False`` otherwise.
+         - ``"host_connected_usb"``: ``True`` if the hub is connected to a computer
+           via USB and activated in the app. ``False`` otherwise.
          - ``"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.
+         - `"program_id"`: Program (slot) number of the currently running program.
 
         Returns:
             A dictionary with system info.
@@ -136,7 +141,7 @@ class System:
         .. 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.
+            are still available for backwards compatibility.
         """
 
 
@@ -828,7 +833,7 @@ class LightMatrix:
         contents remain unchanged.
 
         Arguments:
-            top (Side): Which side of the light matrix display is "up" in your
+            up (Side): Which side of the light matrix display is "up" in your
                 design. Choose ``Side.TOP``, ``Side.LEFT``, ``Side.RIGHT``,
                 or ``Side.BOTTOM``.
         """
@@ -1165,7 +1170,7 @@ class IMU:
         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
+        with ``hub.imu.rotation(-Axis.Z, calibrated=False)`` 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.
@@ -1179,17 +1184,19 @@ class IMU:
                 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.
+            heading_correction (Number, deg): Number of degrees
+                reported by for one full rotation of your robot.
+                After a reset the value is 360 degrees. This is applied on top
+                of any scaling that is done by the ``angular_velocity_scale``
+                setting.
             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.
+                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
@@ -1209,17 +1216,6 @@ class IMU:
         even as the robot turns more than 180 degrees. It does not wrap around
         to -180 like it does in some apps.
 
-
-        .. note:: *For now, this method only keeps track of the heading while
-                  the robot is on a flat surface.*
-
-                  This means that the value is
-                  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.
 
@@ -1437,86 +1433,3 @@ class AmbientColorSensor(CommonColorSensor):
             Measured color. The color is described by a hue (0--359), a
             saturation (0--100), and a brightness value (0--100).
         """
-
-
-class BLE:
-    """
-    Bluetooth Low Energy.
-
-    .. versionadded:: 3.3
-    """
-
-    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``. 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
-        at the same time.
-
-        The total data size is quite limited (26 bytes). ``True`` and
-        ``False`` take 1 byte each. ``float`` takes 5 bytes. ``int`` takes 2 to
-        5 bytes depending on how big the number is. ``str`` and ``bytes`` take
-        the number of bytes in the object plus one extra byte.
-
-        When multitasking, only one task can broadcast at a time. To broadcast
-        information from multiple tasks (or block stacks), you could use a
-        dedicated separate task that broadcast new values when one or more
-        variables change.
-
-        Args:
-            data: The value or values to be broadcast.
-
-        .. versionadded:: 3.3
-        """
-
-    def observe(
-        self, channel: int
-    ) -> Optional[Tuple[Union[bool, int, float, str, bytes], ...]]:
-        """observe(channel) -> bool | int | float | str | bytes | tuple | None
-
-        Retrieves the last observed data for a given channel.
-
-        Receiving data is more reliable when the hub is not connected
-        to a computer or other devices at the same time.
-
-        Args:
-            channel (int): The channel to observe (0 to 255).
-
-        Returns:
-            The received data in the same format as it was sent, or ``None``
-            if no recent data is available.
-
-        .. versionadded:: 3.3
-        """
-
-    def signal_strength(self, channel: int) -> int:
-        """signal_strength(channel) -> int: dBm
-
-        Gets the average signal strength in dBm for the given channel.
-
-        This indicates how near the broadcasting device is. Nearby devices
-        may have a signal strength around -40 dBm, while far away devices
-        might have a signal strength around -70 dBm.
-
-        Args:
-            channel (int): The channel number (0 to 255).
-
-        Returns:
-            The signal strength or ``-128`` if there is no recent observed data.
-
-        .. versionadded:: 3.3
-        """
-
-    def version(self) -> str:
-        """version() -> str
-
-        Gets the firmware version from the Bluetooth chip.
-
-        .. versionadded:: 3.3
-        """

src/pybricks/ev3devices.py

@@ -3,7 +3,7 @@
 
 """LEGO® MINDSTORMS® EV3 motors and sensors."""
 
-from typing import Optional, Tuple, List
+from typing import Optional, Tuple, List, Set
 
 from . import _common
 from .parameters import (
@@ -57,7 +57,7 @@ class ColorSensor:
         Returns:
             ``Color.BLACK``, ``Color.BLUE``, ``Color.GREEN``,
             ``Color.YELLOW``, ``Color.RED``, ``Color.WHITE``, ``Color.BROWN``,
-            or ``None`` if no color is detected.
+            or ``Color.NONE`` if no color is detected.
 
         """
 
@@ -134,8 +134,8 @@ class InfraredSensor:
             a tuple of (``None``, ``None``) if no remote is detected.
         """
 
-    def buttons(self, channel: int) -> List[_Button]:
-        """buttons(channel) -> List[Button]
+    def buttons(self, channel: int) -> Set[_Button]:
+        """buttons(channel) -> Set[Button]
 
         Checks which buttons on the infrared remote are pressed.
 

src/pybricks/hubs.py

@@ -3,8 +3,6 @@
 
 """LEGO® Programmable Hubs."""
 
-from typing import Sequence
-
 from . import _common
 from .ev3dev import _speaker
 from .media.ev3dev import Image as _Image
@@ -41,28 +39,19 @@ class MoveHub:
     imu = _common.SimpleAccelerometer()
     system = _common.System()
     buttons = _common.Keypad([_Button.CENTER])
-    ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
     ):
-        """MoveHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
+        """MoveHub(top_side=Axis.Z, front_side=Axis.X)
 
         Arguments:
             top_side (Axis): The axis that passes through the *top side* of
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
-            broadcast_channel:
-                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.
-                Default is an empty list (no channels).
-
-        .. versionchanged:: 3.3
-            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 
@@ -75,25 +64,9 @@ class CityHub:
     light = _common.ColorLight()
     system = _common.System()
     buttons = _common.Keypad([_Button.CENTER])
-    ble = _common.BLE()
 
-    def __init__(
-        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
-    ):
-        """CityHub(broadcast_channel=None, observe_channels=[])
-
-        Arguments:
-            broadcast_channel:
-                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.
-                Default is an empty list (no channels).
-
-        .. versionchanged:: 3.3
-            Added *broadcast_channel* and *observe_channels* arguments.
-        """
+    def __init__(self):
+        """CityHub()"""
 
 
 class TechnicHub:
@@ -106,16 +79,13 @@ class TechnicHub:
     imu = _common.IMU()
     system = _common.System()
     buttons = _common.Keypad([_Button.CENTER])
-    ble = _common.BLE()
 
     def __init__(
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = None,
-        observe_channels: Sequence[int] = [],
     ):
-        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
+        """TechnicHub(top_side=Axis.Z, front_side=Axis.X)
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -127,16 +97,6 @@ class TechnicHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
-            broadcast_channel:
-                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.
-                Default is an empty list (no channels).
-
-        .. versionchanged:: 3.3
-            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 
@@ -151,16 +111,13 @@ class EssentialHub:
     light = _common.ColorLight()
     imu = _common.IMU()
     system = _common.System()
-    ble = _common.BLE()
 
     def __init__(
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = None,
-        observe_channels: Sequence[int] = [],
     ):
-        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
+        """EssentialHub(top_side=Axis.Z, front_side=Axis.X)
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -172,16 +129,6 @@ class EssentialHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
-            broadcast_channel:
-                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.
-                Default is an empty list (no channels).
-
-        .. versionchanged:: 3.3
-            Added *broadcast_channel* and *observe_channels* arguments.
         """
         pass
 
@@ -206,16 +153,13 @@ class PrimeHub:
     speaker = _common.Speaker()
     imu = _common.IMU()
     system = _common.System()
-    ble = _common.BLE()
 
     def __init__(
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = None,
-        observe_channels: Sequence[int] = [],
     ):
-        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
+        """PrimeHub(top_side=Axis.Z, front_side=Axis.X)
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -227,16 +171,6 @@ class PrimeHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
-            broadcast_channel:
-                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.
-                Default is an empty list (no channels).
-
-        .. versionchanged:: 3.3
-            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 

src/pybricks/iodevices.py

@@ -5,13 +5,13 @@
 
 from __future__ import annotations
 
-from typing import Dict, Tuple, Optional, overload, TYPE_CHECKING
+from typing import Tuple, Optional, overload, TYPE_CHECKING
 
 from . import _common
 from .parameters import Port as _Port
 
 if TYPE_CHECKING:
-    from ._common import MaybeAwaitable, MaybeAwaitableTuple
+    from ._common import MaybeAwaitable, MaybeAwaitableBytes, MaybeAwaitableTuple
     from .parameters import Number
 
 
@@ -25,13 +25,21 @@ class PUPDevice:
             port (Port): Port to which the device is connected.
         """
 
-    def info(self) -> Dict[str, str]:
+    def info(self) -> dict:
         """info() -> Dict
 
         Gets information about the device.
 
+        For passive devices (such as DC motors or lights), returns a
+        dictionary with only the ``id`` key.
+
+        For UART devices, returns a dictionary with an ``id`` key and a
+        ``modes`` key. The ``modes`` value is a tuple of tuples, one per
+        mode, each containing the mode name, number of values, and data
+        type.
+
         Returns:
-            Dictionary with information, such as the device ``id``.
+            Dictionary with device information.
         """
 
     def read(self, mode: int) -> MaybeAwaitableTuple:
@@ -39,89 +47,86 @@ class PUPDevice:
 
         Reads values from a given mode.
 
+        For passive touch sensors, this returns a single boolean value
+        indicating whether the sensor is pressed, regardless of the
+        ``mode`` argument.
+
+        Raises an error for other passive devices such as DC motors and
+        lights, which do not support reading.
+
         Arguments:
             mode (int): Device mode.
 
         Returns:
-            Values read from the sensor.
+            Values read from the device.
+
+        Raises:
+            OSError: If the device is a passive device that does not
+                support reading (e.g. a DC motor or light).
         """
 
     def write(self, mode: int, data: Tuple) -> MaybeAwaitable:
         """write(mode, data)
 
-        Writes values to the sensor. Only selected sensors and modes support
-        this.
+        Writes values to the device. Only selected UART devices and modes
+        support this.
 
         Arguments:
             mode (int): Device mode.
-            data (tuple): Values to be written.
+            data (tuple): Values to be written. The number of values and
+                their types must match what the device expects for the
+                given mode.
+
+        Raises:
+            OSError: If the device is a passive device that does not
+                support writing.
+            ValueError: If the mode is invalid, the mode is not writable,
+                the number of values does not match, or a value is out of
+                range for its data type.
+        """
+
+    def reset(self) -> None:
+        """reset()
+
+        Resets the UART device. After this, it should automatically synchronize
+        and be ready for use after a few seconds. This is useful to forcefully
+        re-trigger what such a sensor does when plugged in.
+
+        Raises:
+            OSError: If the device is a passive device that does not
+                support reset.
         """
 
 
-class LUMPDevice:
-    """Devices using the LEGO UART Messaging Protocol."""
+class LUMPDevice(PUPDevice):
+    """Devices using the LEGO UART Messaging Protocol.
 
-    def __init__(self, port: _Port):
-        """LUMPDevice(port)
+    See the equivalent :class:`PUPDevice() <pybricks.iodevices.PUPDevice>` for
+    a description of available methods.
 
-        Arguments:
-            port (Port): Port to which the device is connected.
-        """
-
-    def read(self, mode: int) -> MaybeAwaitableTuple:
-        """read(mode) -> Tuple
-
-        Reads values from a given mode.
-
-        Arguments:
-            mode (int): Device mode.
-
-        Returns:
-            Values read from the sensor.
-        """
+    On EV3, this class provides access to UART devices only. You can use other
+    classes to interact with passive devices.
+    """
 
 
 class DCMotor(_common.DCMotor):
     """DC Motor for LEGO® MINDSTORMS EV3."""
 
 
-class Ev3devSensor:
-    """Read values of an ev3dev-compatible sensor."""
-
-    sensor_index: int
-    """Index of the ev3dev sysfs `lego-sensor`_ class."""
-
-    port_index: int
-    """Index of the ev3dev sysfs `lego-port`_ class."""
-
-    def __init__(self, port: _Port):
-        """Ev3devSensor(port)
-
-        Arguments:
-            port (Port): Port to which the device is connected.
-        """
-
-    def read(self, mode: str) -> MaybeAwaitableTuple:
-        """read(mode) -> Tuple
-
-        Reads values at a given mode.
-
-        Arguments:
-            mode (str): `Mode name`_.
-
-        Returns:
-            values read from the sensor.
-        """
-
-
 class AnalogSensor:
     """Generic or custom analog sensor."""
 
-    def __init__(self, port: _Port):
-        """AnalogSensor(port)
+    def __init__(self, port: _Port, custom: bool = False):
+        """AnalogSensor(port, custom=False)
 
         Arguments:
             port (Port): Port to which the sensor is connected.
+            custom (bool): Set to ``True`` if you are using a custom analog
+                sensor.
+
+        Raises:
+            OSError: If no standard LEGO analog sensor is
+                detected on the port. Only applies if ``custom=False``.
         """
 
     def voltage(self) -> int:
@@ -139,10 +144,15 @@ class AnalogSensor:
         Measures resistance.
 
         This value is only meaningful if the analog device is a passive load
-        such as a resistor or thermistor.
+        such as a resistor or thermistor. It is calculated assuming a 10 kΩ
+        internal pull-up resistor forming a voltage divider.
+
+        If the circuit is open (no load connected), the maximum integer value
+        is returned.
 
         Returns:
-            Resistance of the analog device.
+            Resistance of the analog device, or the maximum integer value
+            if the circuit is open.
         """
 
     def active(self) -> None:
@@ -171,58 +181,125 @@ class AnalogSensor:
 
 
 class I2CDevice:
-    """Generic or custom I2C device."""
+    """Generic or custom I2C device.
 
-    def __init__(self, port: _Port, address: int):
-        """I2CDevice(port, address)
+    Note: Use the ``power_pin`` option at your own risk. Applying power to the
+    pins can damage your hub or device if you are not careful. When you use
+    this option, you will be prompted to confirm that you understand the risks.
+    """
+
+    def __init__(
+        self,
+        port: _Port,
+        address: int,
+        custom: bool = False,
+        power_pin: int = 0,
+        nxt_quirk: bool = False,
+    ):
+        """I2CDevice(port, address, custom=False, power_pin=0, nxt_quirk=False)
 
         Arguments:
             port (Port): Port to which the device is connected.
-            address(int): I2C address of the client device. See
+            address (int): I2C address of the client device. See
                 :ref:`I2C Addresses <i2caddress>`.
+            custom (bool): Set to ``True`` if you are using a custom I2C device.
+            power_pin (int): Power requirements for the device. Use
+                ``0`` (default) for no power on the pins. On NXT and EV3, use ``1``
+                to apply battery power to pin 1. Other pins are not supported.
+            nxt_quirk (bool): Set to ``True`` for older NXT I2C sensors that
+                need slower compatibility timing to communicate reliably,
+                such as the old NXT Ultrasonic Sensor.
         """
 
-    def read(self, reg: Optional[int], length: Optional[int] = 1) -> bytes:
-        """read(reg, length=1)
+    @overload
+    def read(
+        self, reg: Optional[int] = None, length: int = 1
+    ) -> MaybeAwaitableBytes: ...
 
-        Reads bytes, starting at a given register.
+    @overload
+    def read(
+        self, reg: Optional[int] = None, length: int = 1, map: callable = ...
+    ) -> MaybeAwaitable: ...
+
+    def read(
+        self, reg: Optional[int] = None, length: int = 1, map=None
+    ) -> MaybeAwaitableBytes:
+        """read(reg=None, length=1) -> bytes
+        read(reg=None, length=1, map=callable) -> Any
+
+        Reads bytes starting at a given register.
 
         Arguments:
-            reg (int): Register at which to begin
-                reading: 0--255 or 0x00--0xFF.
+            reg (int): Register at which to begin reading: 0--255 or
+                0x00--0xFF. Use ``None`` to read without writing a register
+                address first.
             length (int): How many bytes to read.
+            map (callable): Optional callable to convert the returned bytes.
+                If given, it is called with the bytes as its argument and its
+                return value is returned instead.
 
         Returns:
-            Bytes returned from the device.
+            Bytes returned from the device, or the return value of ``map``
+            if a callable was provided.
         """
 
-    def write(self, reg: Optional[int], data: Optional[bytes] = None) -> None:
-        """write(reg, data=None)
+    def write(
+        self, reg: Optional[int] = None, data: Optional[bytes] = None
+    ) -> MaybeAwaitable:
+        """write(reg=None, data=None)
 
-        Writes bytes, starting at a given register.
+        Writes bytes, optionally starting at a given register.
 
         Arguments:
-            reg (int): Register at which to begin
-                writing: 0--255 or 0x00--0xFF.
-            data (bytes): Bytes to be written.
+            reg (int): Register at which to begin writing: 0--255 or
+                0x00--0xFF. Use ``None`` to write without a register prefix.
+            data (bytes): Bytes to be written. Use ``None`` to write nothing
+                after the register.
+
+        Raises:
+            ValueError: If ``reg`` is given and ``data`` is more than 32 bytes.
+                To write more data, omit the ``reg`` argument and include the
+                register as the first byte of ``data``.
         """
 
 
 class UARTDevice:
-    """Generic UART device."""
+    """Generic UART device.
 
-    def __init__(self, port: _Port, baudrate: int, timeout: Optional[int] = None):
-        """UARTDevice(port, baudrate, timeout=None)
+    Note: Use the ``power_pin`` option at your own risk. Applying power to the
+    pins can damage your hub or device if you are not careful. When you use
+    this option, you will be prompted to confirm that you understand the risks.
+    """
+
+    def __init__(
+        self,
+        port: _Port,
+        baudrate: int = 115200,
+        timeout: Optional[int] = None,
+        power_pin: int = 0,
+    ):
+        """UARTDevice(port, baudrate=115200, timeout=None, power_pin=0)
 
         Arguments:
-            port (Port): Port to which the device is connected.
+            port (Port): Port to which the device is connected. On Powered UP
+                hubs, all ports are supported. On EV3, only the sensor ports
+                are supported.
             baudrate (int): Baudrate of the UART device.
-            timeout (Number, ms): How long to wait
-                during ``read`` before giving up. If you choose ``None``,
-                it will wait forever.
+            timeout (Number, ms): How long to wait during ``read`` and
+                ``write`` before giving up. If you choose ``None``, it will
+                wait forever.
+            power_pin (int): Power requirements for the device. Use ``0``
+                (default) for no power on the pins. On Powered UP hubs, use
+                ``1`` or ``2`` for pin 1 or 2, respectively. This will apply
+                battery power to the pin, equivalent to powering a motor.
+                On EV3, use ``1`` to apply battery power to pin 1, though only
+                minimal current is available.
+
+        Raises:
+            ValueError: If ``timeout`` is 0 or negative.
         """
 
-    def read(self, length: int = 1) -> bytes:
+    def read(self, length: int = 1) -> MaybeAwaitableBytes:
         """read(length=1) -> bytes
 
         Reads a given number of bytes from the buffer.
@@ -232,28 +309,38 @@ class UARTDevice:
         exception is raised.
 
         Arguments:
-            length (int): How many bytes to read.
+            length (int): How many bytes to read. Must be at least 1.
 
         Returns:
             Bytes returned from the device.
+
+        Raises:
+            ValueError: If ``length`` is less than 1.
+            OSError: If the read takes longer than ``timeout``.
         """
 
     def read_all(self) -> bytes:
         """read_all() -> bytes
 
-        Reads all bytes from the buffer.
+        Reads all bytes currently in the buffer. Returns immediately without
+        waiting, even if the buffer is empty.
 
         Returns:
-            Bytes returned from the device.
+            Bytes currently in the buffer, or an empty bytes object if there
+            is nothing to read.
         """
 
-    def write(self, data: bytes) -> None:
+    def write(self, data: bytes) -> MaybeAwaitable:
         """write(data)
 
-        Writes bytes.
+        Writes bytes to the device.
 
         Arguments:
             data (bytes): Bytes to be written.
+
+        Raises:
+            TypeError: If ``data`` is not ``bytes``, ``bytearray``, or ``str``.
+            OSError: If the write takes longer than ``timeout``.
         """
 
     def waiting(self) -> int:
@@ -265,23 +352,57 @@ class UARTDevice:
             Number of bytes in the buffer.
         """
 
+    def set_baudrate(self, baudrate: int) -> None:
+        """set_baudrate(baudrate)
+
+        Changes the baud rate of the UART device.
+
+        Arguments:
+            baudrate (int): Not all values may be supported.
+
+        Raises:
+            ValueError: If ``baudrate`` is less than 1.
+        """
+
+    def wait_until(self, pattern: bytes) -> MaybeAwaitable:
+        """wait_until(pattern)
+
+        Waits until a specific byte sequence is received. Bytes that do not
+        match the pattern are discarded.
+
+        Arguments:
+            pattern (bytes): Byte sequence to wait for. Must not be empty.
+
+        Raises:
+            ValueError: If ``pattern`` is empty.
+            OSError: If this method is already in progress.
+        """
+
     def clear(self) -> None:
         """clear()
 
-        Empties the buffer."""
+        Empties the receive buffer."""
 
 
 class LWP3Device:
     """
     Connects to a hub running official LEGO firmware using the
-    `LEGO Wireless Protocol v3`_
+    `LEGO Wireless Protocol v3`_.
 
     .. _`LEGO Wireless Protocol v3`:
         https://lego.github.io/lego-ble-wireless-protocol-docs/
     """
 
-    def __init__(self, hub_kind: int, name: str = None, timeout: int = 10000):
-        """LWP3Device(hub_kind, name=None, timeout=10000)
+    def __init__(
+        self,
+        hub_kind: int,
+        name: str = None,
+        timeout: int = 10000,
+        pair: bool = False,
+        num_notifications: int = 8,
+        connect: bool = True,
+    ):
+        """LWP3Device(hub_kind, name=None, timeout=10000, pair=False, num_notifications=8, connect=True)
 
         Arguments:
             hub_kind (int):
@@ -292,12 +413,35 @@ class LWP3Device:
             timeout (int):
                 The time, in milliseconds, to wait for a connection before
                 raising an exception.
+            pair (bool): Whether to attempt pairing for a secure connection.
+                This is required for some newer hubs.
+            num_notifications (int): Number of incoming messages from the remote
+                hub to store before discarding older messages.
+            connect (bool): Choose ``False`` to skip connecting.
+                ``connect()`` can be called later to connect.
 
+        .. versionchanged:: 3.6
+
+            Added ``pair`` parameter.
+
+        .. versionchanged:: 3.7
+
+            Added ``num_notifications`` parameter.
 
         .. _`hub type identifier`:
             https://github.com/pybricks/technical-info/blob/master/assigned-numbers.md#hub-type-ids
         """
 
+    def connect(self) -> MaybeAwaitable:
+        """connect()
+
+        Connects to the device. Only needed if you disconnected or initialized
+        with ``connect=False``.
+
+        Raises:
+            OSError: If the connection attempt fails or times out.
+        """
+
     @overload
     def name(self, name: str) -> MaybeAwaitable: ...
 
@@ -313,6 +457,9 @@ class LWP3Device:
         Arguments:
             name (str): New Bluetooth name of the device. If no name is given,
                 this method returns the current name.
+
+        Raises:
+            OSError: If the device is not connected.
         """
 
     def write(self, buf: bytes) -> MaybeAwaitable:
@@ -321,25 +468,36 @@ class LWP3Device:
         Sends a message to the remote hub.
 
         Arguments:
-            buf (bytes): The raw binary message to send.
+            buf (bytes): The raw binary message to send. Maximum 20 bytes.
+
+        Raises:
+            ValueError: If the message exceeds 20 bytes.
+            OSError: If the device is not connected or the write fails.
         """
 
-    def read(self) -> bytes:
-        """read() -> bytes
+    def read(self) -> bytes | None:
+        """read() -> bytes | None
 
-        Retrieves the most recent message received from the remote hub.
+        Retrieves the oldest buffered message received from the remote hub.
 
-        If a message has not been received since the last read, the method will
-        block until a message is received.
+        If all buffered messages have already been read, this returns ``None``.
 
         Returns:
-            The raw binary message.
+            The oldest raw binary message or ``None`` if there are no more messages.
+
+        .. versionchanged:: 3.7
+
+            Now supports reading multiple buffered messages instead of blocking
+            until one new message was received.
         """
 
     def disconnect(self) -> MaybeAwaitable:
         """disconnect()
 
-        Disconnects the remote LWP3Device from the hub.
+        Disconnects the device.
+
+        Raises:
+            OSError: If disconnecting fails.
         """
 
 
@@ -355,27 +513,95 @@ class XboxController:
 
     buttons = _common.Keypad([])
 
-    def __init__(self):
-        """"""
+    def __init__(
+        self,
+        joystick_deadzone: int = 10,
+        name: Optional[str] = None,
+        timeout: int = 10000,
+        connect: bool = True,
+    ):
+        """__init__(joystick_deadzone=10, name=None, timeout=10000, connect=True)
+
+        Arguments:
+            joystick_deadzone (Number, %): Joystick deadzone (0 to 100). Values
+                below this threshold in both axes will be reported as 0 to
+                prevent stick drift.
+            name (str): The Bluetooth name of the Xbox controller to connect to,
+                or ``None`` to connect to any available controller.
+            timeout (Number, ms): How long to wait for a connection before
+                giving up. Choose ``None`` to wait indefinitely.
+            connect (bool): Choose ``False`` to skip connecting to the controller.
+                ``connect()`` can be called later to connect.
+        """
+
+    def connect(self) -> MaybeAwaitable:
+        """connect()
+
+        Connects to the Xbox controller. Only needed if you disconnected or
+        initialized the controller with ``connect=False``.
+        """
+
+    def disconnect(self) -> MaybeAwaitable:
+        """disconnect()
+
+        Disconnects the Xbox controller.
+        """
+
+    def name(self) -> str:
+        """name() -> str
+
+        Gets the Bluetooth name of the connected controller.
+
+        Returns:
+            Bluetooth name of the controller.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
+
+    def state(self) -> Tuple:
+        """state() -> Tuple
+
+        Gets all raw controller input values as a single tuple. This gives
+        access to values not exposed by the other methods.
+
+        The joystick axes (x, y, z, rz) are centered at 0. The trigger axes
+        are raw 10-bit values (0-1023).
+
+        Returns:
+            Tuple of ``(x, y, z, rz, left_trigger, right_trigger, dpad,
+            buttons, upload, profile, trigger_switches, paddles)``.
+
+        Raises:
+            OSError: If the controller is not connected.
+        """
 
     def joystick_left(self) -> Tuple[int, int]:
         """joystick_left() -> Tuple
 
         Gets the left joystick position as percentages between -100%
-        and 100%. The center position is (0, 0).
+        and 100%. The center position is (0, 0). A square deadzone is applied:
+        if both axes are within the deadzone, both are reported as 0.
 
         Returns:
             Tuple of X (horizontal) and Y (vertical) position.
+
+        Raises:
+            OSError: If the controller is not connected.
         """
 
     def joystick_right(self) -> Tuple[int, int]:
         """joystick_right() -> Tuple
 
         Gets the right joystick position as percentages between -100%
-        and 100%. The center position is (0, 0).
+        and 100%. The center position is (0, 0). A square deadzone is applied:
+        if both axes are within the deadzone, both are reported as 0.
 
         Returns:
             Tuple of X (horizontal) and Y (vertical) position.
+
+        Raises:
+            OSError: If the controller is not connected.
         """
 
     def triggers(self) -> Tuple[int, int]:
@@ -386,6 +612,9 @@ class XboxController:
 
         Returns:
             Tuple of left and right trigger positions.
+
+        Raises:
+            OSError: If the controller is not connected.
         """
 
     def dpad(self) -> int:
@@ -402,6 +631,9 @@ class XboxController:
 
         Returns:
             Direction-pad position, indicating a direction.
+
+        Raises:
+            OSError: If the controller is not connected.
         """
 
     def profile(self) -> int:
@@ -412,6 +644,9 @@ class XboxController:
 
         Returns:
             Profile number.
+
+        Raises:
+            OSError: If the controller is not connected.
         """
 
     def rumble(
@@ -426,27 +661,34 @@ class XboxController:
         Makes the builtin actuators rumble, creating force feedback.
 
         If you give a single ``power`` value, the left and right main actuators
-        will both rumble with that power. For more fine-grained control, set
-        ``power`` as a tuple of four values, which control the left main
-        actuator, right main actuator, left trigger actuator, and the right
-        trigger actuator, respectively. For example, ``power=(0, 0, 100, 0)``
-        makes the left trigger rumble at full power.
+        will both rumble with that power while the trigger actuators stay off.
+        For more fine-grained control, set ``power`` as a tuple of four values,
+        which control the left main actuator, right main actuator, left trigger
+        actuator, and the right trigger actuator, respectively. For example,
+        ``power=(0, 0, 100, 0)`` makes the left trigger rumble at full power.
 
         The rumble runs in the background while your program continues. To
         make your program wait, just pause the program for a matching duration.
         For one rumble, this equals ``duration``. For multiple rumbles, this
         equals ``count * (duration + delay)``.
 
+        This method does nothing if all actuator powers are zero, if
+        ``duration`` is zero, or if ``count`` is less than 1.
+
         Arguments:
-            power (Number, % or tuple): Rumble power.
-            duration (Number, ms): Rumble duration.
-            count (int): Rumble count.
-            delay (Number, ms): Delay before each rumble. Only if ``count > 1``.
+            power (Number, % or tuple): Rumble power. A single value applies
+                to both main actuators (0-100%). A tuple applies individually
+                to (left handle, right handle, left trigger, right trigger).
+            duration (Number, ms): Duration of each rumble. Capped at 2500 ms.
+            count (int): Number of rumbles (0-100).
+            delay (Number, ms): Delay before each rumble. Only used if
+                ``count > 1``. Capped at 2500 ms.
         """
 
 
 # hide from jedi
 if TYPE_CHECKING:
     del MaybeAwaitable
+    del MaybeAwaitableBytes
     del MaybeAwaitableTuple
     del Number

src/pybricks/messaging.py

@@ -1,29 +1,170 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2018-2020 The Pybricks Authors
+# Copyright (c) 2018-2026 The Pybricks Authors
 
 """
-Classes to exchange messages between EV3 bricks.
+Classes to send and receive messages from another device.
 """
 
 from __future__ import annotations
 
-from typing import abstractmethod, TypeVar, Optional, Callable, Generic
+
+from typing import (
+    abstractmethod,
+    Callable,
+    Generic,
+    Iterable,
+    List,
+    Optional,
+    overload,
+    Sequence,
+    Tuple,
+    TYPE_CHECKING,
+    TypeVar,
+    Union,
+)
+
+if TYPE_CHECKING:
+    from ._common import (
+        MaybeAwaitable,
+    )
 
 T = TypeVar("T")
 
 
+class BLERadio:
+    """
+    Send and receive messages without a connection using Bluetooth Low Energy.
+
+    .. versionadded:: 4.0
+
+        This used to be part of each hub class.
+    """
+
+    def __init__(
+        self,
+        broadcast_channel: Optional[int] = None,
+        observe_channels: Sequence[int] = [],
+    ):
+        """BLERadio(broadcast_channel=None, observe_channels=[])
+
+        Arguments:
+            broadcast_channel:
+                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.
+                Default is an empty list (no channels).
+        """
+
+    @overload
+    def broadcast(self, data: None) -> MaybeAwaitable: ...
+
+    @overload
+    def broadcast(
+        self, data: Iterable[Union[bool, int, float, str, bytes]]
+    ) -> MaybeAwaitable: ...
+
+    @overload
+    def broadcast(
+        self, data: Union[bool, int, float, str, bytes]
+    ) -> MaybeAwaitable: ...
+
+    def broadcast(self, data: object) -> MaybeAwaitable:
+        """broadcast(data)
+
+        Starts broadcasting the given data on the previously selected
+        ``broadcast_channel``.
+
+        Data may be of type ``int``, ``float``, ``str``, ``bytes``,
+        ``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
+        at the same time.
+
+        The total data size is quite limited (26 bytes). ``True`` and
+        ``False`` take 1 byte each. ``float`` takes 5 bytes. ``int`` takes 2 to
+        5 bytes depending on how big the number is. ``str`` and ``bytes`` take
+        the number of bytes in the object plus one extra byte.
+
+        When multitasking, only one task can broadcast at a time. To broadcast
+        information from multiple tasks (or block stacks), you could use a
+        dedicated separate task that broadcast new values when one or more
+        variables change.
+
+        Args:
+            data: The value or values to be broadcast.
+
+        Raises:
+            RuntimeError: If no ``broadcast_channel`` was configured.
+            ValueError: If the encoded data exceeds 26 bytes.
+            TypeError: If ``data`` contains a value that is not ``bool``,
+                ``int``, ``float``, ``str``, or ``bytes``.
+        """
+
+    def observe(self, channel: int) -> Optional[
+        Union[
+            Tuple[Union[bool, int, float, str, bytes], ...],
+            Union[bool, int, float, str, bytes],
+        ]
+    ]:
+        """observe(channel) -> bool | int | float | str | bytes | tuple | None
+
+        Retrieves the last observed data for a given channel.
+
+        Receiving data is more reliable when the hub is not connected
+        to a computer or other devices at the same time.
+
+        Args:
+            channel (int): The channel to observe. Must be one of the channels
+                given to ``observe_channels`` when creating this object.
+
+        Returns:
+            The received data in the same format as it was sent, or ``None``
+            if no data has been received within the last second.
+
+        Raises:
+            ValueError: If ``channel`` was not in ``observe_channels``.
+        """
+
+    def signal_strength(self, channel: int) -> int:
+        """signal_strength(channel) -> int: dBm
+
+        Gets the average signal strength in dBm for the given channel.
+
+        This indicates how near the broadcasting device is. Nearby devices
+        may have a signal strength around -40 dBm, while far away devices
+        might have a signal strength around -70 dBm.
+
+        Args:
+            channel (int): The channel number. Must be one of the channels
+                given to ``observe_channels`` when creating this object.
+
+        Returns:
+            The signal strength, or ``-128`` if no data has been received
+            within the last second.
+
+        Raises:
+            ValueError: If ``channel`` was not in ``observe_channels``.
+        """
+
+    def version(self) -> str:
+        """version() -> str
+
+        Gets the firmware version from the Bluetooth chip.
+        """
+
+
 class Connection:
     @abstractmethod
-    def read_from_mailbox(self, name: str) -> bytes:
-        ...
+    def read_from_mailbox(self, name: str) -> bytes: ...
 
     @abstractmethod
-    def send_to_mailbox(self, name: str, data: bytes) -> None:
-        ...
+    def send_to_mailbox(self, name: str, data: bytes) -> None: ...
 
     @abstractmethod
-    def wait_for_mailbox_update(self, name: str) -> None:
-        ...
+    def wait_for_mailbox_update(self, name: str) -> None: ...
 
 
 class Mailbox(Generic[T]):
@@ -231,3 +372,94 @@ class BluetoothMailboxClient:
         """close()
 
         Closes all connections."""
+
+
+class AppData:
+    """
+    Exchange raw data with the Pybricks Code host application over USB or
+    Bluetooth. This is used by the smart sensor features like the vision
+    processors.
+
+    Each processor has on emode and produces a fixed amount of data. These are
+    continuously sent to the hub as they change. The user code can read these
+    buffered values at any time without blocking. All values are initially zero.
+
+    From the hub's perspective, writing back to the host is an awaitable operation.
+    Can be used to configure modes and mode settings.
+
+    Only one instance may exist at a time. Must be created during program
+    initialization. After that, all methods may be used while multi-tasking.
+    """
+
+    def __init__(self, modes: List[Tuple[int, int]]):
+        """AppData(modes)
+
+        Arguments:
+            modes:
+                A list of ``(mode, size)`` tuples, where ``mode`` is a mode
+                number (0 to 255) and ``size`` is the number of bytes to
+                allocate for that mode's receive buffer. Mode numbers must be
+                unique. The list is sorted by mode number automatically.
+
+        Raises:
+            RuntimeError: If an ``AppData`` instance already exists.
+            TypeError: If ``modes`` is not a list, or if any element is not a
+                ``(mode, size)`` tuple with a mode value of 0 to 255.
+            ValueError: If any mode number appears more than once.
+        """
+
+    def get_bytes(self, mode: int, index: Optional[int] = None) -> Union[bytes, int]:
+        """get_bytes(mode, index=None) -> bytes | int
+
+        Gets data received from the host for the given mode.
+
+        Args:
+            mode (int): The mode number to read.
+            index (int): If given, returns the single byte at this position
+                within the mode's buffer as an integer. Otherwise returns
+                the entire mode buffer as ``bytes``.
+
+        Returns:
+            All received bytes for the mode, or a single byte as an integer
+            if ``index`` is given.
+
+        Raises:
+            ValueError: If ``mode`` was not configured, or if ``index`` is
+                out of range.
+        """
+
+    def write_bytes(self, data: bytes) -> MaybeAwaitable:
+        """write_bytes(data)
+
+        Sends raw bytes to the host application.
+
+        Args:
+            data (bytes): The data to send.
+        """
+
+    def configure(self, mode: int, parameter: int, value: bytes) -> MaybeAwaitable:
+        """configure(mode, parameter, value)
+
+        Sends a configuration command to the host for the given mode.
+
+        This is a wrapper around :meth:`write_bytes`. It prepends a
+        ``[0x01, mode, parameter]`` header to configure mode settings.
+
+        Args:
+            mode (int): The mode number to configure.
+            parameter (int): The parameter identifier within the mode.
+            value (bytes): The configuration value to send.
+        """
+
+    def close(self) -> None:
+        """close()
+
+        Deactivates the data callback and releases the receive buffer.
+
+        This is also called automatically when the object is garbage collected.
+        """
+
+
+if TYPE_CHECKING:
+    del MaybeAwaitable
+    del T

src/pybricks/parameters.py

@@ -58,16 +58,12 @@ class _PybricksEnum(Enum, metaclass=_PybricksEnumMeta):
 
 
 class Axis:
-    """Unit axes of a coordinate system.
-
-    .. data:: X = vector(1, 0, 0)
-    .. data:: Y = vector(0, 1, 0)
-    .. data:: Z = vector(0, 0, 1)
-
-    """
+    """Unit axes of a coordinate system."""
 
     X: _Matrix = _vector(1, 0, 0)
+
     Y: _Matrix = _vector(0, 1, 0)
+
     Z: _Matrix = _vector(0, 0, 1)
 
 
@@ -112,6 +108,13 @@ class Color:
         The brightness value.
         """
 
+    def __setattr__(self, key, value):
+        if key not in ("h", "s", "v"):
+            raise AttributeError("Can't modify unknown attribute: " + key)
+        if hasattr(self, key):  # immutable after __init__
+            raise AttributeError("Can't modify immutable attribute: " + key)
+        super().__setattr__(key, value)
+
     def __iter__(self):
         """Allows unpacking of the Color instance into h, s, and v."""
         return iter((self.h, self.s, self.v))
@@ -119,11 +122,12 @@ class Color:
     def __repr__(self):
         return "Color(h={}, s={}, v={})".format(self.h, self.s, self.v)
 
-    def __eq__(self, other: Color) -> bool: ...
+    def __eq__(self, other: Color) -> bool:
+        return self.h == other.h and self.s == other.s and self.v == other.v
 
     def __mul__(self, scale: float) -> Color:
         v = max(0, min(self.v * scale, 100))
-        return Color(self.h, self.s, int(v), self.name)
+        return Color(self.h, self.s, int(v))
 
     def __rmul__(self, scale: float) -> Color:
         return self.__mul__(scale)
@@ -134,6 +138,12 @@ class Color:
     def __floordiv__(self, scale: int) -> Color:
         return self.__mul__(1 / scale)
 
+    def __lshift__(self, shift: int) -> Color:
+        return self.__rshift__(-shift)
+
+    def __rshift__(self, shift: int) -> Color:
+        return Color((self.h + shift) % 360, self.s, self.v)
+
 
 Color.NONE = Color(0, 0, 0)
 Color.BLACK = Color(0, 0, 10)

src/pybricks/pupdevices.py

@@ -5,9 +5,10 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Collection, Optional, Union, overload
+from typing import TYPE_CHECKING, Collection, Optional, Union
 
 from . import _common
+from .iodevices import LWP3Device
 from .parameters import Button, Color, Direction
 
 if TYPE_CHECKING:
@@ -98,7 +99,7 @@ class Motor(_common.Motor):
         """
 
 
-class Remote:
+class Remote(LWP3Device):
     """LEGO® Powered Up Bluetooth Remote Control."""
 
     light = _common.ExternalColorLight()
@@ -115,42 +116,238 @@ class Remote:
     )
     address: Union[str, None]
 
-    def __init__(self, name: Optional[str] = None, timeout: int = 10000):
-        """Remote(name=None, timeout=10000)
-
-        When you instantiate this class, the hub will search for a remote
-        and connect automatically.
-
-        The remote must be on and ready for a connection, as indicated by a
-        white blinking light.
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        timeout: int = 10000,
+        connect: bool = True,
+    ):
+        """Remote(name=None, timeout=10000, connect=True)
 
         Arguments:
             name (str): Bluetooth name of the remote. If no name is given,
                 the hub connects to the first remote that it finds.
             timeout (Number, ms): How long to search for the remote.
+                Choose ``None`` to wait indefinitely.
+            connect (bool): Choose ``False`` to skip connecting.
+                ``connect()`` can be called later to connect.
+
+        Raises:
+            OSError: If the connection attempt fails or times out.
         """
 
-    @overload
-    def name(self, name: str) -> None: ...
 
-    @overload
-    def name(self) -> str: ...
+class TechnicMoveHub(LWP3Device):
+    """LEGO® Technic Move Hub (set 42176, 42214, 42239).
 
-    def name(self, *args):
-        """name(name)
-        name() -> str
+    This newer hub is found in the latest Technic Control+ sets. It requires
+    a special password to update the firmware, so Pybricks cannot be installed
+    on it. However, you can connect a supported hub running Pybricks to it
+    and control its motors that way.
+    """
 
-        Sets or gets the Bluetooth name of the remote.
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        timeout: int = 10000,
+        connect: bool = True,
+    ):
+        """TechnicMoveHub(name=None, timeout=10000, connect=True)
 
         Arguments:
-            name (str): New Bluetooth name of the remote. If no name is given,
-                this method returns the current name.
+            name (str): Bluetooth name of the hub. If no name is given,
+                the hub connects to the first Technic Move Hub it finds.
+            timeout (Number, ms): How long to search for the hub.
+                Choose ``None`` to wait indefinitely.
+            connect (bool): Choose ``False`` to skip connecting.
+                ``connect()`` can be called later to connect.
+
+        Raises:
+            OSError: If the connection attempt fails or times out.
         """
 
-    def disconnect(self) -> MaybeAwaitable:
-        """disconnect()
+    def drive(self, speed: int, steering: int) -> MaybeAwaitable:
+        """drive(speed, steering)
 
-        Disconnects the remote from the hub.
+        Drives the hub's motor outputs at the given speed and steering.
+
+        Arguments:
+            speed (int): Drive speed as a percentage (-100 to 100).
+            steering (int): Steering as a percentage (-100 to 100). Positive
+                values steer right. Values exceeding ±97 are clamped to ±97
+                to avoid pushing against the mechanical constraint.
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+
+class MarioHub(LWP3Device):
+    """LEGO® Super Mario hub (sets 71360, 71387, 71441 and similar).
+
+    Connect a supported hub running Pybricks to a LEGO Mario, Luigi, or Peach
+    figure and reads its color sensor.
+    """
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        timeout: int = 10000,
+        connect: bool = True,
+    ):
+        """MarioHub(name=None, timeout=10000, connect=True)
+
+        Arguments:
+            name (str): Bluetooth name of the hub. If no name is given,
+                the hub connects to the first Mario hub it finds.
+            timeout (Number, ms): How long to search for the hub.
+                Choose ``None`` to wait indefinitely.
+            connect (bool): Choose ``False`` to skip connecting.
+                ``connect()`` can be called later to connect.
+
+        Raises:
+            OSError: If the connection attempt fails or times out.
+        """
+
+    def color(self) -> Color:
+        """color() -> Color
+
+        Reads the color detected by the color sensor from the latest received
+        notification.
+
+        Returns:
+            Detected color.
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+    def hsv(self) -> Color:
+        """hsv() -> Color
+
+        Reads the hue, saturation, and brightness of the color detected by the
+        color sensor from the latest received notification, as a
+        :class:`Color <.parameters.Color>` object.
+
+        Returns:
+            Measured color.
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+    def detectable_colors(self, colors: Collection[Color] = None) -> None:
+        """detectable_colors(colors)
+
+        Configures the list of colors that :meth:`color` may return.
+
+        Only the colors in this list will be returned. This helps reduce
+        false positives when you only care about a specific subset of colors.
+
+        Arguments:
+            colors (list): List of :class:`Color <.parameters.Color>` objects
+                to detect, or ``None`` to restore the default list.
+        """
+
+
+class DuploTrain(LWP3Device):
+    """LEGO® Duplo Train hub (sets 10874, 10875, 10427, 10428 similar).
+
+    The Duplo Hub cannot be updated, so you cannot install Pybricks on it.
+    However, you can connect a supported hub running Pybricks to the Duplo Hub
+    and control the train that way.
+
+    You can you control the motor, sound, and headlights, and read the speed
+    and color sensors.
+    """
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        timeout: int = 10000,
+        connect: bool = True,
+    ):
+        """DuploTrain(name=None, timeout=10000, connect=True)
+
+        Arguments:
+            name (str): Bluetooth name of the hub. If no name is given,
+                the hub connects to the first Duplo Train hub it finds.
+            timeout (Number, ms): How long to search for the hub.
+                Choose ``None`` to wait indefinitely.
+            connect (bool): Choose ``False`` to skip connecting.
+                ``connect()`` can be called later to connect.
+
+        Raises:
+            OSError: If the connection attempt fails or times out.
+        """
+
+    def drive(self, speed: int) -> MaybeAwaitable:
+        """drive(speed)
+
+        Drives the train motor at the given speed.
+
+        Arguments:
+            speed (int): Speed as a percentage (-100 to 100). Negative values
+                drive in reverse.
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+    def headlights(self, color: Color) -> MaybeAwaitable:
+        """headlights(color)
+
+        Sets the color of the train headlights. Not all colors are supported,
+        so the hub will choose the closest color it can produce.
+
+        Arguments:
+            color (Color): Color of the headlights.
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+    def sound(self, sound: str) -> MaybeAwaitable:
+        """sound(sound)
+
+        Plays one of the built-in train sounds.
+
+        For the newer (dark blue) train, we have not yet figured out the right
+        sound codes. Please open a discussion or pull request if you know how
+        to do it. Thanks!
+
+        Arguments:
+            sound (str): Name of the sound to play. Choose from
+                ``"brake"``, ``"depart"``, ``"water"``, ``"horn"``,
+                or ``"steam"``.
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+    def speed(self) -> int:
+        """speed() -> int: %
+
+        Reads the train speed from the latest received notification.
+
+        Returns:
+            Speed as a percentage (-100 to 100).
+
+        Raises:
+            OSError: If the hub is not connected.
+        """
+
+    def color(self) -> Color:
+        """color() -> Color
+
+        Reads the color detected by the color sensor from the latest received
+        notification.
+
+        Returns:
+            Detected color.
+
+        Raises:
+            OSError: If the hub is not connected.
         """
 
 
@@ -461,6 +658,7 @@ if TYPE_CHECKING:
     del Button
     del Color
     del Direction
+    del LWP3Device
     del MaybeAwaitable
     del MaybeAwaitableBool
     del MaybeAwaitableFloat

src/pybricks/robotics.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import Tuple, Optional, overload, TYPE_CHECKING
+from typing import Tuple, Union, Optional, overload, TYPE_CHECKING
 
 from . import _common
 from .parameters import Stop
@@ -92,6 +92,12 @@ class DriveBase:
         Stops the robot by passively braking the motors.
         """
 
+    def hold(self) -> None:
+        """hold()
+
+        Stops the robot and actively holds it in place.
+        """
+
     def distance(self) -> int:
         """distance() -> int: mm
 
@@ -101,11 +107,15 @@ class DriveBase:
             Driven distance since last reset.
         """
 
-    def angle(self) -> int:
-        """angle() -> int: deg
+    def angle(self) -> float:
+        """angle() -> float: deg
 
         Gets the estimated rotation angle of the drive base.
 
+        When the gyro is used for this drive base, this gives the gyro angle.
+        Otherwise, it gives the estimated angle estimated from the motor
+        displacement.
+
         Returns:
             Accumulated angle since last reset.
         """
@@ -115,6 +125,10 @@ class DriveBase:
 
         Gets the state of the robot.
 
+        As with the :meth:`.angle` methods, the reported angle and turn rate
+        are those of the gyro if the gyro is used. Otherwise they are
+        estimated from the motor displacement.
+
         Returns:
             Tuple of distance, drive speed, angle, and turn rate of the robot.
         """
@@ -129,26 +143,29 @@ class DriveBase:
         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.
+            distance (Number, mm): New value of the driven distance.
+            angle (Number, deg): New heading angle of the robot.
         """
 
     @overload
     def settings(
         self,
         straight_speed: Optional[Number] = None,
-        straight_acceleration: Optional[Number] = None,
+        straight_acceleration: Optional[Union[Number, Tuple[Number, Number]]] = None,
         turn_rate: Optional[Number] = None,
-        turn_acceleration: Optional[Number] = None,
+        turn_acceleration: Optional[Union[Number, Tuple[Number, Number]]] = None,
     ) -> None: ...
 
     @overload
-    def settings(self) -> Tuple[int, int, int, int]: ...
+    def settings(
+        self,
+    ) -> Tuple[int, Union[int, Tuple[int, int]], int, Union[int, Tuple[int, int]]]: ...
 
     def settings(self, *args):
         """
         settings(straight_speed, straight_acceleration, turn_rate, turn_acceleration)
         settings() -> Tuple[int, int, int, int]
+        settings() -> Tuple[int, Tuple[int, int], int, Tuple[int, int]]
 
         Configures the drive base speed and acceleration.
 
@@ -161,15 +178,22 @@ class DriveBase:
         The speed values given here do not apply to the :meth:`.drive` method,
         since you provide your own speed values as arguments in that method.
 
+        Speed and rate values are treated as absolute; negative values are
+        converted to positive automatically.
+
         Arguments:
             straight_speed (Number, mm/s): Straight-line speed of the robot.
-            straight_acceleration (Number, mm/s²): Straight-line
-                acceleration and deceleration of the robot. Provide a tuple with
-                two values to set acceleration and deceleration separately.
+            straight_acceleration (Number or Tuple[Number, Number], mm/s²):
+                Straight-line acceleration and deceleration of the robot.
+                Provide a single value to use the same acceleration and
+                deceleration. Provide a tuple with two values to set them
+                separately.
             turn_rate (Number, deg/s): Turn rate of the robot.
-            turn_acceleration (Number, deg/s²): Angular acceleration and
-                deceleration of the robot. Provide a tuple with
-                two values to set acceleration and deceleration separately.
+            turn_acceleration (Number or Tuple[Number, Number], deg/s²):
+                Angular acceleration and deceleration of the robot.
+                Provide a single value to use the same acceleration and
+                deceleration. Provide a tuple with two values to set them
+                separately.
         """
 
     def straight(
@@ -187,9 +211,13 @@ class DriveBase:
         """
 
     def turn(
-        self, angle: Number, then: Stop = Stop.HOLD, wait: bool = True
+        self,
+        angle: Number,
+        then: Stop = Stop.HOLD,
+        wait: bool = True,
+        absolute: bool = False,
     ) -> MaybeAwaitable:
-        """turn(angle, then=Stop.HOLD, wait=True)
+        """turn(angle, then=Stop.HOLD, wait=True, absolute=False)
 
         Turns in place by a given angle and then stops.
 
@@ -198,6 +226,9 @@ class DriveBase:
             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.
+            absolute (bool): If ``False`` (default), the robot turns _by_ the
+                given angle relative to its current heading. If ``True``,
+                the robot turns to the given absolute heading angle.
         """
 
     def arc(
@@ -234,21 +265,6 @@ class DriveBase:
                 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:
-        """curve(radius, angle, then=Stop.HOLD, wait=True)
-
-        Drives an arc along a circle of a given radius, by a given angle.
-
-        Arguments:
-            radius (Number, mm): Radius of the circle.
-            angle (Number, deg): Angle along the circle.
-            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.
-        """
-
     def done(self) -> bool:
         """done() -> bool
 
@@ -270,6 +286,26 @@ class DriveBase:
             ``True`` if the drive base is stalled, ``False`` if not.
         """
 
+    def move_by(self, dx: Number, dy: Number, then: Stop = Stop.HOLD) -> MaybeAwaitable:
+        """move_by(dx, dy, then=Stop.HOLD)
+
+        Moves the robot by an amount given as X-and-Y coordinates on the robot
+        drive area. The X-axis is what was forward when the program started.
+        The Y-axis is 90° left of that. You can reset this by resetting the heading.
+
+        The robot first turns to the required heading and then drives the
+        straight-line distance. Because the heading target is absolute, the
+        result is independent of the robot's current heading.
+
+        Arguments:
+            dx (Number, mm): X-distance on the drive area.
+            dy (Number, mm): Y-distance on the drive area.
+            then (Stop): What to do after coming to a standstill.
+
+        Raises:
+            ValueError: If one of the distances is more than 30 m.
+        """
+
     def use_gyro(self, use_gyro: bool) -> None:
         """use_gyro(use_gyro)