connections.pybricks: add support for Pybricks Profile v1.5.0

Implement support for Pybricks Profile v1.5.0. Also add some missing
items from v1.4.0.

Author: dlech

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added support for Pybricks Profile v1.5.0.
+
 ## [1.1.0] - 2025-05-28
 
 ### Added

pybricksdev/ble/pybricks.py

@@ -255,6 +255,12 @@ class StatusFlag(IntFlag):
     .. availability:: Since Pybricks protocol v1.2.0.
     """
 
+    BLE_HOST_CONNECTED = 1 << 9
+    """Bluetooth Low Energy host is connected.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+
 
 class HubCapabilityFlag(IntFlag):
     """
@@ -277,14 +283,36 @@ class HubCapabilityFlag(IntFlag):
     .. availability:: Since Pybricks protocol v1.2.0.
     """
 
-    USER_PROG_MULTI_FILE_MPY6_1_NATIVE = 2 << 1
+    USER_PROG_MULTI_FILE_MPY6_1_NATIVE = 1 << 2
     """
     Hub supports user programs using a multi-file blob with MicroPython MPY (ABI V6.1) files
     including native module support.
 
     .. availability:: Since Pybricks protocol v1.3.0.
     """
 
+    BUILTIN_USER_PROGRAM_PORT_VIEW = 1 << 3
+    """
+    Hub has the built-in user program "port view" feature.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+
+    BUILTIN_USER_PROGRAM_IMU_CALIBRATION = 1 << 4
+    """
+    Hub has the built-in user program "IMU calibration" feature.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+
+    USER_PROG_FORMAT_MULTI_MPY_V6_3_NATIVE = 1 << 5
+    """
+    Hub supports user programs using a multi-file blob with MicroPython MPY (ABI V6.3) files
+    including native module support.
+
+    .. availability:: Since Pybricks protocol v1.5.0.
+    """
+
 
 def unpack_hub_capabilities(data: bytes) -> Tuple[int, HubCapabilityFlag, int]:
     """
@@ -295,10 +323,32 @@ def unpack_hub_capabilities(data: bytes) -> Tuple[int, HubCapabilityFlag, int]:
 
     Returns:
         A tuple of the maximum characteristic write size in bytes, the hub capability
-        flags and the max user program size in bytes.
+        flags and the max user program size in bytes and the number of slots.
+    """
+    if len(data) == 11:
+        # Pybricks protocol v1.5
+        max_char_size, flags, max_user_prog_size, num_of_slots = unpack("<HIIB", data)
+    else:
+        # Pybricks protocol v1.2
+        max_char_size, flags, max_user_prog_size = unpack("<HII", data)
+        num_of_slots = 0
+
+    return max_char_size, HubCapabilityFlag(flags), max_user_prog_size, num_of_slots
+
+
+def unpack_hub_capabilities_v15(data: bytes) -> Tuple[int, HubCapabilityFlag, int, int]:
+    """
+    Unpacks the value read from the hub capabilities characteristic. (Pybricks protocol v1.5)
+
+    Args:
+        data: The raw characteristic value.
+
+    Returns:
+        A tuple of the maximum characteristic write size in bytes, the hub capability
+        flags and the max user program size in bytes and the number of slots.
     """
-    max_char_size, flags, max_user_prog_size = unpack("<HII", data)
-    return max_char_size, HubCapabilityFlag(flags), max_user_prog_size
+    max_char_size, flags, max_user_prog_size, num_of_slots = unpack("<HIIB", data)
+    return max_char_size, HubCapabilityFlag(flags), max_user_prog_size, num_of_slots
 
 
 # The Pybricks Protocol version also implies certain other services and

pybricksdev/connections/pybricks.py

@@ -87,6 +87,25 @@ class PybricksHub:
     has not been connected yet or the connected hub has Pybricks profile < v1.2.0.
     """
 
+    _running_program: int
+    """
+    The ID number of the currently running user program on the connected hub.
+    Only valid if a user program is running and the hub supports Pybricks
+    profile >= v1.4.
+    """
+
+    _num_of_slots: int
+    """
+    The number of user program slots available on the connected hub. ``0`` if
+    the hub has not been connected yet or the hub does not support slots.
+    """
+
+    _selected_slot: int
+    """
+    The currently selected user program slot on the connected hub. Only valid
+    if ``_num_of_slots`` is greater than ``0``.
+    """
+
     def __init__(self):
         self.connection_state_observable = BehaviorSubject(ConnectionState.DISCONNECTED)
         self.status_observable = BehaviorSubject(StatusFlag(0))
@@ -97,6 +116,9 @@ def __init__(self):
         self._mpy_abi_version = 0
         self._capability_flags = HubCapabilityFlag(0)
         self._max_user_program_size = 0
+        self._running_program = 0
+        self._num_of_slots = 0
+        self._selected_slot = 0
 
         # whether to enable line handler features or not
         self._enable_line_handler = False
@@ -229,6 +251,11 @@ def _pybricks_service_handler(self, _: int, data: bytes) -> None:
             # decode the payload
             (flags,) = struct.unpack_from("<I", data, 1)
             self.status_observable.on_next(StatusFlag(flags))
+
+            if len(data) >= 6:
+                self._running_program = data[5]
+            if len(data) >= 7:
+                self._selected_slot = data[6]
         elif data[0] == Event.WRITE_STDOUT:
             payload = data[1:]
             self._stdout_subject.on_next(payload)
@@ -452,7 +479,11 @@ async def start_user_program(self) -> None:
         """
         await self.write_gatt_char(
             PYBRICKS_COMMAND_EVENT_UUID,
-            struct.pack("<B", Command.START_USER_PROGRAM),
+            (
+                struct.pack("<B", Command.START_USER_PROGRAM)
+                if self._num_of_slots == 0
+                else struct.pack("<BB", Command.START_USER_PROGRAM, self._selected_slot)
+            ),
             response=True,
         )
 
@@ -718,6 +749,7 @@ async def _client_connect(self) -> bool:
                 self._max_write_size,
                 self._capability_flags,
                 self._max_user_program_size,
+                self._num_of_slots,
             ) = unpack_hub_capabilities(caps)
         else:
             # HACK: prior to profile v1.2.0 isn't a proper way to get the
@@ -812,6 +844,7 @@ async def _client_connect(self) -> bool:
                         _,
                         self._capability_flags,
                         self._max_user_program_size,
+                        self._num_of_slots,
                     ) = unpack_hub_capabilities(caps)
 
             ofst += size