wedopy 0.1.0__tar.gz

wedopy-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0.dev0
+
+First implementation of design spec 1.2.0 (`WeDo_2_0_con_Cython.md`).
+
+- Cython core `wedopy_core._wedopy`: protocol codecs, state machine, single-writer coordinator
+  (normal/emergency queues), heartbeat and watchdog.
+- Public API: `Hub`, `Motor`, `MotorGroup`, `DistanceSensor`, `TiltSensor`, `LED`, `Button`,
+  cooperative tasks (`hub.tasks`, `task.sleep`, `task.yield_now`), `running_time`.
+- BLE backend `BleakTransport` (Linux/BlueZ first) and `SimulatedHub` transport for tests.
+- Validated on real WeDo 2.0 hardware (Nov 2026): compiled build, `BleakTransport`
+  (Linux/BlueZ), port discovery, tilt sensor (direction and angle), distance, LED,
+  motor, battery, button.
+- Tilt sensor: angle mode uses `UNIT_RAW` with `expected_len=2` (`int8` pairs).
+  `UNIT_SI` makes the hub silently ignore the configuration and never notify.
+- Tilt bump mode (2) is not implemented by the hub firmware; documented as a spec
+  artifact, not a wedopy bug.
+- Not yet validated on hardware: watchdog timings under a real BLE stall,
+  `refresh_ports()` replay, behaviour when the process is killed with the link
+  open, and the `strong` stop profile (not implemented).

wedopy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wedopy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wedopy-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include pyproject.toml
+include setup.py
+include wedopy_core/_wedopy.pyx
+include wedopy_core/_wedopy.pxd
+include wedopy_core/_wedopy.c
+recursive-include wedopy_core *.py
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include examples *.py

wedopy-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: wedopy
+Version: 0.1.0
+Summary: Python library for the LEGO WeDo 2.0 Smart Hub over BLE (API in Python, core in Cython)
+License-Expression: MIT
+Keywords: lego,wedo,wedo2,ble,bluetooth,robotics,iot,cython
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: Cython>=3.0; extra == "dev"
+Dynamic: license-file
+
+# wedopy
+
+Python library for the **LEGO WeDo 2.0 Smart Hub** over Bluetooth Low Energy.
+Public API in Python, execution core in Cython. Implements design spec 1.2.0.
+
+```python
+from wedopy import Hub, task
+
+with Hub() as hub:
+    motor = hub.motor("A")
+    motor.run(100)
+```
+
+## Install (development)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+python -m pip install -e ".[dev]"      # builds the Cython extension, installs bleak
+python -m pytest
+```
+
+Or with uv:
+
+```bash
+uv sync
+uv run pytest
+```
+
+Linux/BlueZ is the first supported platform (BLE through `bleak`).
+
+## Layout
+
+| Path                      | Contents                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------- |
+| `src/wedopy/`             | Public API: `Hub`, `Motor`, `MotorGroup`, sensors, `LED`, `Button`, `task`, `tasks`, exceptions |
+| `wedopy_core/_wedopy.pyx` | Cython core: protocol codecs, state machine, single-writer coordinator, heartbeat, watchdog     |
+| `wedopy_core/transport/`  | `Transport` interface, `BleakTransport` (BLE), `SimulatedHub` (tests)                           |
+| `wedopy_core/protocol/`   | UUIDs and constants                                                                             |
+| `wedopy_core/runtime/`    | `Timing` parameters, process `supervisor`                                                       |
+| `tests/`, `examples/`     | pytest suite (simulated hub), runnable examples                                                 |
+
+Deviations from the spec's tree: `src/wedo/` is `src/wedopy/` (the import name is `wedopy`); the
+compiled module is `wedopy_core._wedopy`; protocol codecs live in the Cython core instead of
+separate `.py` files; exceptions are defined in `wedopy_core/exceptions.py` and re-exported by
+`wedopy.exceptions`, so the core never imports the public package.
+
+## Behaviour worth knowing
+
+- Every BLE operation goes through one coordinator thread (single writer). Writes and the
+  heartbeat are always _with response_; there is no silent fallback to write-without-response.
+- While any motor has a non-zero speed, a heartbeat (Battery Level read) runs every 0.5 s. With
+  no valid ACK for 2 s the watchdog stops the motors with emergency priority (2 attempts), logs
+  the result on `wedopy.watchdog`, and moves the hub to `error`. The watchdog and heartbeat run on
+  their own thread, so a blocked task scheduler cannot disable them.
+- Normal operations time out after 1 s, which bounds how long an emergency request can wait
+  behind an in-flight operation (an in-flight BLE call cannot be aborted).
+- Stop profile is `nobarrier`. `strong` is not offered.
+- `hub.tasks.cancel()` never stops motors; protect motors with `try/finally`, or call
+  `hub.stop_all()`. Leaving `with Hub()` cancels tasks first, then stops motors.
+- Logging goes through the standard `logging` module (`wedopy`, `wedopy.watchdog`, `wedopy.tasks`).
+- Sensors only notify on change. `read_angle()`, `read_direction()` and the distance sensor
+  return the _last_ value; if the physical value has not changed since the last notification,
+  the call blocks until the sensor sends a new sample or the timeout fires. Move/incline the
+  sensor (or expose it to a new distance) after configuring it.
+- The tilt sensor is a 4-position switch, not an accelerometer. Its direction mode (1) uses
+  `UNIT_SI` (4-byte `float32`); its angle mode (0) requires `UNIT_RAW` (2-byte `int8` pair)
+  — with `UNIT_SI` the hub silently ignores the configuration. Bump mode (2) is accepted by
+  the hub but never emits; the firmware does not implement it.
+
+## Status
+
+Verified with the simulated hub and on real WeDo 2.0 hardware (Nov 2026):
+
+- Compiled Cython build (`wedopy_core._wedopy`).
+- `BleakTransport` on Linux/BlueZ: connect, port discovery, notifications.
+- Tilt sensor: direction mode (1, `UNIT_SI`) and angle mode (0, `UNIT_RAW`).
+- Battery, button, LED, motor, distance sensor.
+
+**Not yet verified on hardware:** watchdog timings under a real BLE stall,
+`refresh_ports()` replay, behaviour when the process is killed with the link
+open, and the `strong` stop profile (not implemented).
+
+`wedopy_core/_wedopy.pyx` is written in the subset of Cython that is also valid Python, so
+`tests/conftest.py` can run it uncompiled when the extension is not built (it warns). Typed
+`cdef` optimisations can be added later once profiling shows they matter.

wedopy-0.1.0/README.md

@@ -0,0 +1,85 @@
+# wedopy
+
+Python library for the **LEGO WeDo 2.0 Smart Hub** over Bluetooth Low Energy.
+Public API in Python, execution core in Cython. Implements design spec 1.2.0.
+
+```python
+from wedopy import Hub, task
+
+with Hub() as hub:
+    motor = hub.motor("A")
+    motor.run(100)
+```
+
+## Install (development)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+python -m pip install -e ".[dev]"      # builds the Cython extension, installs bleak
+python -m pytest
+```
+
+Or with uv:
+
+```bash
+uv sync
+uv run pytest
+```
+
+Linux/BlueZ is the first supported platform (BLE through `bleak`).
+
+## Layout
+
+| Path                      | Contents                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------- |
+| `src/wedopy/`             | Public API: `Hub`, `Motor`, `MotorGroup`, sensors, `LED`, `Button`, `task`, `tasks`, exceptions |
+| `wedopy_core/_wedopy.pyx` | Cython core: protocol codecs, state machine, single-writer coordinator, heartbeat, watchdog     |
+| `wedopy_core/transport/`  | `Transport` interface, `BleakTransport` (BLE), `SimulatedHub` (tests)                           |
+| `wedopy_core/protocol/`   | UUIDs and constants                                                                             |
+| `wedopy_core/runtime/`    | `Timing` parameters, process `supervisor`                                                       |
+| `tests/`, `examples/`     | pytest suite (simulated hub), runnable examples                                                 |
+
+Deviations from the spec's tree: `src/wedo/` is `src/wedopy/` (the import name is `wedopy`); the
+compiled module is `wedopy_core._wedopy`; protocol codecs live in the Cython core instead of
+separate `.py` files; exceptions are defined in `wedopy_core/exceptions.py` and re-exported by
+`wedopy.exceptions`, so the core never imports the public package.
+
+## Behaviour worth knowing
+
+- Every BLE operation goes through one coordinator thread (single writer). Writes and the
+  heartbeat are always _with response_; there is no silent fallback to write-without-response.
+- While any motor has a non-zero speed, a heartbeat (Battery Level read) runs every 0.5 s. With
+  no valid ACK for 2 s the watchdog stops the motors with emergency priority (2 attempts), logs
+  the result on `wedopy.watchdog`, and moves the hub to `error`. The watchdog and heartbeat run on
+  their own thread, so a blocked task scheduler cannot disable them.
+- Normal operations time out after 1 s, which bounds how long an emergency request can wait
+  behind an in-flight operation (an in-flight BLE call cannot be aborted).
+- Stop profile is `nobarrier`. `strong` is not offered.
+- `hub.tasks.cancel()` never stops motors; protect motors with `try/finally`, or call
+  `hub.stop_all()`. Leaving `with Hub()` cancels tasks first, then stops motors.
+- Logging goes through the standard `logging` module (`wedopy`, `wedopy.watchdog`, `wedopy.tasks`).
+- Sensors only notify on change. `read_angle()`, `read_direction()` and the distance sensor
+  return the _last_ value; if the physical value has not changed since the last notification,
+  the call blocks until the sensor sends a new sample or the timeout fires. Move/incline the
+  sensor (or expose it to a new distance) after configuring it.
+- The tilt sensor is a 4-position switch, not an accelerometer. Its direction mode (1) uses
+  `UNIT_SI` (4-byte `float32`); its angle mode (0) requires `UNIT_RAW` (2-byte `int8` pair)
+  — with `UNIT_SI` the hub silently ignores the configuration. Bump mode (2) is accepted by
+  the hub but never emits; the firmware does not implement it.
+
+## Status
+
+Verified with the simulated hub and on real WeDo 2.0 hardware (Nov 2026):
+
+- Compiled Cython build (`wedopy_core._wedopy`).
+- `BleakTransport` on Linux/BlueZ: connect, port discovery, notifications.
+- Tilt sensor: direction mode (1, `UNIT_SI`) and angle mode (0, `UNIT_RAW`).
+- Battery, button, LED, motor, distance sensor.
+
+**Not yet verified on hardware:** watchdog timings under a real BLE stall,
+`refresh_ports()` replay, behaviour when the process is killed with the link
+open, and the `strong` stop profile (not implemented).
+
+`wedopy_core/_wedopy.pyx` is written in the subset of Cython that is also valid Python, so
+`tests/conftest.py` can run it uncompiled when the extension is not built (it warns). Typed
+`cdef` optimisations can be added later once profiling shows they matter.

wedopy-0.1.0/examples/blink_and_move.py

@@ -0,0 +1,22 @@
+"""Blink the LED while a motor runs, using cooperative tasks (no threads, no asyncio)."""
+from wedopy import Hub, task
+
+with Hub() as hub:
+    def blink():
+        while True:
+            hub.led.index(6)
+            yield task.sleep(0.3)
+            hub.led.index(9)
+            yield task.sleep(0.3)
+
+    def move():
+        motor = hub.motor("A")
+        try:                      # cancelling a task never stops the motor by itself
+            motor.run(75)
+            yield task.sleep(3)
+        finally:
+            motor.stop()
+
+    hub.tasks.add(blink, background=True)   # does not keep wait() alive
+    hub.tasks.add(move)
+    hub.tasks.wait()                        # returns when move() ends; blink is cancelled

wedopy-0.1.0/examples/distance_sensor.py

@@ -0,0 +1,18 @@
+"""Drive until the distance sensor reports something nearer than 3 (scale 0..10)."""
+import time
+
+from wedopy import Hub, OperationTimeout
+
+with Hub() as hub:
+    sensor = hub.distance_sensor("B")
+    motor = hub.motor("A")
+    motor.run(70)
+    while True:
+        try:
+            if sensor.is_near(3):
+                break
+        except OperationTimeout:
+            print("no reading from the sensor; stopping")
+            break
+        time.sleep(0.05)
+    motor.stop()

wedopy-0.1.0/examples/led.py

@@ -0,0 +1,11 @@
+"""Cycle through the indexed LED colours, then show an RGB colour."""
+import time
+
+from wedopy import Hub
+
+with Hub() as hub:
+    for i in range(1, 11):
+        hub.led.index(i)
+        time.sleep(0.3)
+    hub.led.rgb(255, 80, 0)
+    time.sleep(1)

wedopy-0.1.0/examples/motor.py

@@ -0,0 +1,10 @@
+"""Run motor A for two seconds."""
+import time
+
+from wedopy import Hub
+
+with Hub() as hub:
+    motor = hub.motor("A")
+    motor.run(100)
+    time.sleep(2)
+    motor.stop()

wedopy-0.1.0/examples/tilt_diag.py

@@ -0,0 +1,22 @@
+import time
+from wedopy import Hub
+from wedopy_core.protocol import constants as K
+from wedopy_core import _wedopy as core
+
+_orig = core.Coordinator._on_notify
+def _patched(self, uuid, data):
+    if uuid == K.CHAR_SENSOR:
+        print(f"NOTIFY conn={data[1]:02x} value={data[2:].hex()} len={len(data)-2}")
+    return _orig(self, uuid, data)
+core.Coordinator._on_notify = _patched
+
+with Hub() as hub:
+    t = hub.tilt_sensor("A")
+    print(">>> mueve el sensor en X e Y por separado <<<")
+    for i in range(15):
+        raw = hub._session.core.read_sensor(
+            t._conn, K.TYPE_TILT, K.TILT_ANGLE, K.UNIT_RAW,
+            expected_len=None, timeout=3.0,
+        )
+        print(f"[{i}] raw={raw.hex()} len={len(raw)}")
+        time.sleep(1)

wedopy-0.1.0/examples/tilt_sensor.py

@@ -0,0 +1,9 @@
+"""Print the tilt angle and direction."""
+import time
+from wedopy import Hub
+
+with Hub() as hub:
+    tilt = hub.tilt_sensor("A")
+    for _ in range(20):
+        print("angle", tilt.read_angle(), "| direction", tilt.read_direction())
+        time.sleep(0.25)

wedopy-0.1.0/examples/two_motors.py

@@ -0,0 +1,10 @@
+"""Drive two motors together (A first, then B; not atomic), then stop."""
+import time
+
+from wedopy import Hub
+
+with Hub() as hub:
+    motors = hub.motors(("A", "B"))
+    motors.run(75)
+    time.sleep(2)
+    motors.stop()

wedopy-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel", "Cython>=3.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wedopy"
+version = "0.1.0"
+description = "Python library for the LEGO WeDo 2.0 Smart Hub over BLE (API in Python, core in Cython)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["bleak>=0.22"]
+keywords = ["lego", "wedo", "wedo2", "ble", "bluetooth", "robotics", "iot", "cython"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: System :: Hardware",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+]
+
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "Cython>=3.0"]
+
+[tool.setuptools]
+package-dir = { "wedopy" = "src/wedopy", "wedopy_core" = "wedopy_core" }
+packages = [
+    "wedopy",
+    "wedopy_core",
+    "wedopy_core.protocol",
+    "wedopy_core.transport",
+    "wedopy_core.runtime",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+]

wedopy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wedopy-0.1.0/setup.py

@@ -0,0 +1,15 @@
+"""Build script: compiles the private Cython core ``wedopy_core._wedopy``."""
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+
+extensions = [
+    Extension("wedopy_core._wedopy", ["wedopy_core/_wedopy.pyx"]),
+]
+
+setup(
+    ext_modules=cythonize(
+        extensions,
+        language_level=3,
+        compiler_directives={"binding": True},
+    ),
+)

wedopy-0.1.0/src/wedopy/__init__.py

@@ -0,0 +1,38 @@
+"""wedopy: control the LEGO WeDo 2.0 Smart Hub from Python.
+
+    from wedopy import Hub
+
+    with Hub() as hub:
+        motor = hub.motor("A")
+        motor.run(100)
+"""
+from . import task
+from .button import Button
+from .exceptions import (
+    AmbiguousDeviceError,
+    BLEError,
+    DeviceNotFoundError,
+    DeviceTypeError,
+    HubBusyError,
+    HubConnectionError,
+    HubDisconnectedError,
+    InvalidStateError,
+    OperationTimeout,
+    UnsupportedFeatureError,
+    WedoError,
+)
+from .hub import Hub
+from .led import LED
+from .motor import Motor, MotorGroup
+from .sensors import DistanceSensor, TiltSensor
+from .time import running_time
+
+__version__ = "0.1.0.dev0"
+
+__all__ = [
+    "Hub", "Motor", "MotorGroup", "DistanceSensor", "TiltSensor", "LED", "Button",
+    "task", "running_time",
+    "WedoError", "BLEError", "HubConnectionError", "HubDisconnectedError", "OperationTimeout",
+    "HubBusyError", "DeviceNotFoundError", "DeviceTypeError", "AmbiguousDeviceError",
+    "InvalidStateError", "UnsupportedFeatureError",
+]

wedopy-0.1.0/src/wedopy/button.py

@@ -0,0 +1,14 @@
+"""Built-in button (spec 5.6)."""
+
+
+class Button:
+    def __init__(self, session):
+        self._session = session
+
+    @property
+    def is_pressed(self):
+        return self._session.core.button_pressed()
+
+    @property
+    def is_released(self):
+        return not self.is_pressed

wedopy-0.1.0/src/wedopy/exceptions.py

@@ -0,0 +1,15 @@
+"""Public exceptions. The classes are defined in ``wedopy_core.exceptions`` (so the core does
+not depend on this package) and re-exported here."""
+from wedopy_core import exceptions as _core
+
+__all__ = [
+    "WedoError", "BLEError", "HubConnectionError", "HubDisconnectedError", "OperationTimeout",
+    "HubBusyError", "DeviceNotFoundError", "DeviceTypeError", "AmbiguousDeviceError",
+    "InvalidStateError", "UnsupportedFeatureError",
+]
+
+for _name in __all__:
+    _cls = getattr(_core, _name)
+    _cls.__module__ = __name__
+    globals()[_name] = _cls
+del _name, _cls

wedopy-0.1.0/src/wedopy/hub.py

@@ -0,0 +1,146 @@
+"""``Hub``: the physical WeDo 2.0 Smart Hub (spec 5.1)."""
+from wedopy_core.exceptions import (
+    AmbiguousDeviceError,
+    DeviceNotFoundError,
+    DeviceTypeError,
+)
+from wedopy_core.protocol import constants as K
+
+from .button import Button
+from .led import LED
+from .motor import Motor, MotorGroup
+from .sensors import DistanceSensor, TiltSensor
+from .session import Session
+
+_PORTS = {"A": K.CONN_PORT_A, "B": K.CONN_PORT_B}
+_CONN_PORT = {v: k for k, v in _PORTS.items()}
+
+
+def _port_conn(port):
+    if not isinstance(port, str):
+        raise TypeError("port must be 'A' or 'B', not %s" % type(port).__name__)
+    conn = _PORTS.get(port.upper())
+    if conn is None:
+        raise ValueError("port must be 'A' or 'B', got %r" % port)
+    return conn
+
+
+class Hub:
+    """Create it, then ``connect()`` or use it as a context manager (recommended)::
+
+        with Hub() as hub:
+            hub.motor("A").run(100)
+
+    ``transport`` and ``timing`` are for tests and tuning; leave them out in normal use.
+    """
+
+    def __init__(self, *, transport=None, timing=None):
+        self._session = Session(transport, timing)
+        self._led = LED(self._session)
+        self._button = Button(self._session)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def connect(self):
+        """Connect to the first WeDo 2.0 hub found. Returns ``self``."""
+        self._session.connect()
+        return self
+
+    @property
+    def is_connected(self):
+        return self._session.is_connected
+
+    def disconnect(self):
+        """Cancel tasks, try to stop the motors, close BLE. Safe to call twice."""
+        self._session.disconnect()
+
+    def shutdown(self):
+        """Ask the hub to power off. It must be switched on by hand afterwards."""
+        self._session.shutdown()
+
+    def stop_all(self):
+        """Ask every motor to stop (``nobarrier`` profile: no ordering guarantee against other orders)."""
+        self._session.stop_all()
+
+    def __enter__(self):
+        return self.connect()
+
+    def __exit__(self, exc_type, exc, tb):
+        try:
+            self.disconnect()
+        except Exception:
+            if exc_type is None:
+                raise
+        return False
+
+    # -- ports and devices ----------------------------------------------------
+
+    @property
+    def ports(self):
+        """Snapshot of the known external devices, e.g. ``{"A": "motor", "B": "distance"}``."""
+        raw = self._session.ports_raw()
+        return {name: K.TYPE_NAMES.get(raw[conn], "unknown(0x%02x)" % raw[conn])
+                for name, conn in _PORTS.items() if conn in raw}
+
+    def refresh_ports(self):
+        """Ask the hub to report its devices again and return the new snapshot."""
+        self._session.refresh_ports()
+        return self.ports
+
+    def _select(self, type_code, port):
+        self._session.core.check_usable()
+        raw = self._session.ports_raw()
+        wanted = K.TYPE_NAMES[type_code]
+        if port is not None:
+            conn = _port_conn(port)
+            found = raw.get(conn)
+            label = port.upper()
+            if found is None:
+                raise DeviceNotFoundError("nothing is connected to port %s" % label)
+            if found != type_code:
+                raise DeviceTypeError("port %s holds a %s, not a %s" % (
+                    label, K.TYPE_NAMES.get(found, "unknown device"), wanted))
+            return conn
+        candidates = [c for c in (K.CONN_PORT_A, K.CONN_PORT_B) if raw.get(c) == type_code]
+        if not candidates:
+            raise DeviceNotFoundError("no %s is connected" % wanted)
+        if len(candidates) > 1:
+            raise AmbiguousDeviceError("more than one %s is connected; pass the port ('A' or 'B')" % wanted)
+        return candidates[0]
+
+    def motor(self, port=None):
+        conn = self._select(K.TYPE_MOTOR, port)
+        return Motor(self._session, conn, _CONN_PORT[conn])
+
+    def motors(self, ports):
+        """A group of motors, e.g. ``hub.motors(("A", "B"))``; driven A first, then B."""
+        if isinstance(ports, str):
+            raise TypeError("ports must be a sequence such as ('A', 'B')")
+        ports = list(ports)
+        if not ports:
+            raise ValueError("ports must not be empty")
+        conns = [_port_conn(p) for p in ports]
+        if len(set(conns)) != len(conns):
+            raise ValueError("duplicate port in %r" % (ports,))
+        return MotorGroup([self.motor(_CONN_PORT[c]) for c in conns])
+
+    def distance_sensor(self, port=None):
+        conn = self._select(K.TYPE_MOTION, port)
+        return DistanceSensor(self._session, conn, _CONN_PORT[conn])
+
+    def tilt_sensor(self, port=None):
+        conn = self._select(K.TYPE_TILT, port)
+        return TiltSensor(self._session, conn, _CONN_PORT[conn])
+
+    @property
+    def led(self):
+        return self._led
+
+    @property
+    def button(self):
+        return self._button
+
+    @property
+    def tasks(self):
+        """Cooperative task manager of this hub (``add`` / ``wait`` / ``cancel``)."""
+        return self._session.tasks