pybricksdev.connections.pybricks: add user program ID to start_user_program()

Add an optional user program ID argument to the start_user_program()
method of PybricksHub to allow starting built-in programs.

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 optional user program ID arg to `PybricksHub.start_user_program()`.
+
 ### Fixed
 - Fixed calling `PybricksHub.write()` methods.
 

pybricksdev/ble/pybricks.py

@@ -314,6 +314,43 @@ class HubCapabilityFlag(IntFlag):
     """
 
 
+class UserProgramId(IntEnum):
+    """
+    User program identifiers.
+    """
+
+    FIRST_SLOT = 0
+    """
+    The first user program slot.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+    LAST_SLOT = 127
+    """
+    The last user program slot.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+    REPL = 128
+    """
+    The REPL builtin program slot.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+    PORT_VIEW = 129
+    """
+    The port view builtin program slot.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+    IMU_CALIBRATION = 130
+    """
+    The IMU calibration builtin program slot.
+
+    .. availability:: Since Pybricks protocol v1.4.0.
+    """
+
+
 def unpack_hub_capabilities(data: bytes) -> Tuple[int, HubCapabilityFlag, int]:
     """
     Unpacks the value read from the hub capabilities characteristic.

pybricksdev/connections/pybricks.py

@@ -36,6 +36,7 @@
     Event,
     HubCapabilityFlag,
     StatusFlag,
+    UserProgramId,
     unpack_hub_capabilities,
     unpack_pnp_id,
 )
@@ -471,18 +472,29 @@ async def download_user_program(self, program: bytes) -> None:
             response=True,
         )
 
-    async def start_user_program(self) -> None:
+    async def start_user_program(self, slot: UserProgramId | int | None = None) -> None:
         """
         Starts the user program that is already in RAM on the hub.
 
+        Args:
+            slot: The user program slot to start. If None, the currently selected slot is used.
+
         Requires hub with Pybricks Profile >= v1.2.0.
+
+        User program ID requires hub with Pybricks Profile >= v1.4.0.
         """
+
+        if slot is None:
+            slot = self._selected_slot
+
+        # TODO: add fallback for starting REPL on older firmware
+
         await self.write_gatt_char(
             PYBRICKS_COMMAND_EVENT_UUID,
             (
                 struct.pack("<B", Command.START_USER_PROGRAM)
                 if self._num_of_slots == 0
-                else struct.pack("<BB", Command.START_USER_PROGRAM, self._selected_slot)
+                else struct.pack("<BB", Command.START_USER_PROGRAM, slot)
             ),
             response=True,
         )