ble.pybricks: add Pybricks Profile v1.2.0 support

This updates the pybricksdev package to allow downloading and running
programs via BLE using Pybricks Profile v1.2.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.2.0 (BLE).
+
 ## [1.0.0-alpha.31] - 2022-09-14
 
 ### Added

pybricksdev/ble/pybricks.py

@@ -14,6 +14,9 @@
 After connecting, programs SHOULD read the Software Revision characteristic of
 the Device Information Service to determine the Pybricks protocol version. This
 version can be used to determine the capabilities of the device.
+
+Additional information about the Pybricks Profile can be found at
+_`https://github.com/pybricks/technical-info/blob/master/pybricks-ble-profile.md`.
 """
 
 from enum import IntEnum, IntFlag
@@ -30,12 +33,22 @@ def _pybricks_uuid(short: int) -> str:
 PYBRICKS_SERVICE_UUID = _pybricks_uuid(0x0001)
 """The Pybricks GATT service UUID."""
 
-PYBRICKS_CONTROL_UUID = _pybricks_uuid(0x0002)
-"""The Pybricks control GATT characteristic UUID.
+PYBRICKS_COMMAND_EVENT_UUID = _pybricks_uuid(0x0002)
+"""The Pybricks command/event GATT characteristic UUID.
+
+Commands are written to this characteristic and events are received via notifications.
+
+See :class:`Command` and :class:`Event`.
 
 .. availability:: Since Pybricks protocol v1.0.0.
 """
 
+PYBRICKS_HUB_CAPABILITIES_UUID = _pybricks_uuid(0x0003)
+"""The Pybricks hub capabilities GATT characteristic UUID.
+
+.. availability:: Since Pybricks protocol v1.2.0.
+"""
+
 PYBRICKS_PROTOCOL_VERSION = semver.VersionInfo(1, 1, 0)
 """The minimum required Pybricks protocol version supported by this library."""
 
@@ -55,6 +68,89 @@ class Command(IntEnum):
     .. availability:: Since Pybricks protocol v1.0.0.
     """
 
+    START_USER_PROGRAM = 1
+    """
+    Requests that the user program should be started.
+
+    Hub responds with :attr:`CommandError.BUSY` if a user program is currently running.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+    START_REPL = 2
+    """
+    Requests that the interactive REPL should be started.
+
+    Hub responds with :attr:`CommandError.INVALID_COMMAND` if the hub does not support the REPL.
+    Hub responds with :attr:`CommandError.BUSY` if a user program is currently running.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+    WRITE_USER_PROGRAM_META = 3
+    """
+    Requests to write user program metadata.
+
+    Parameters:
+        size: The size of the user program in bytes (32-bit unsigned integer).
+
+    Hub responds with :attr:`CommandError.BUSY` if a user program is currently running.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+    COMMAND_WRITE_USER_RAM = 4
+    """
+    Requests to write data to user RAM.
+
+    Parameters:
+        offset: The offset from the base user RAM address (32-bit unsigned integer).
+        payload: The data to write to this address (0 to ``max_char_size`` - 5 bytes).
+
+    Hub responds with :attr:`CommandError.VALUE_NOT_ALLOWED` if the offset and size exceeded the user RAM area.
+    Hub responds with :attr:`CommandError.BUSY` if a user program is currently running.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+
+class CommandError(IntEnum):
+    """
+    GATT Attribute error codes that can be sent in response to command write requests.
+    """
+
+    # NB: these values are standard BLE protocol values (i.e. Table 3.4 in v5.3 core specification)
+
+    INVALID_HANDLE = 0x01
+    """
+    The attribute handle given was not valid on this server.
+    """
+    NOT_SUPPORTED = 0x06
+    """
+    Attribute server does not support the request received from the client.
+    """
+    VALUE_NOT_ALLOWED = 0x13
+    """
+    The attribute parameter value was not allowed.
+    """
+
+    # NB: these values are limited to 0x80 – 0x9F as required by the Bluetooth
+    # spec (i.e. Table 3.4 in v5.3 core specification)
+
+    INVALID_COMMAND = 0x80
+    """
+    An invalid command was requested.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+    BUSY = 0x81
+    """
+    The command cannot be completed now because the required resources are busy.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
 
 class Event(IntEnum):
     """Event for Pybricks BLE protocol.
@@ -118,11 +214,52 @@ class StatusFlag(IntFlag):
     """
 
     SHUTDOWN = 1 << 7
-    """Hub shutdown was requested.
+    """Hub has entered shutdown state.
 
     .. availability:: Since Pybricks protocol v1.1.0.
     """
 
+    SHUTDOWN_REQUESTED = 1 << 8
+    """Hub shutdown was requested.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+
+class HubCapabilityFlag(IntFlag):
+    """
+    Hub capability flags.
+    """
+
+    HAS_REPL = 1 << 0
+    """
+    Indicates that the hub has an interactive REPL.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+    USER_PROG_MULTI_FILE_MPY6 = 1 << 1
+    """
+    Hub supports user programs using a multi-file blob with MicroPython MPY (ABI V6) files.
+
+    .. availability:: Since Pybricks protocol v1.2.0.
+    """
+
+
+def unpack_hub_capabilities(data: bytes) -> Tuple[int, HubCapabilityFlag, int]:
+    """
+    Unpacks the value read from the hub capabilities characteristic.
+
+    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.
+    """
+    max_char_size, flags, max_user_prog_size = unpack("<HII", data)
+    return max_char_size, HubCapabilityFlag(flags), max_user_prog_size
+
 
 # The Pybricks Protocol version also implies certain other services and
 # and characteristics are present.

pybricksdev/compile.py

@@ -78,9 +78,7 @@ async def compile_file(path: str, abi: int, compile_args: Optional[List[str]] =
         return mpy
 
 
-async def compile_multi_file(
-    path: str, abi: int, compile_args: Optional[List[str]] = None
-):
+async def compile_multi_file(path: str, abi: int):
     """Compiles a Python file and its dependencies with ``mpy-cross``.
 
     On the hub, all dependencies behave as independent modules. Any (leading)
@@ -106,8 +104,6 @@ async def compile_multi_file(
             Path to script that is to be compiled.
         abi:
             Expected MPY ABI version.
-        compile_args:
-            Extra arguments for ``mpy-cross``.
 
     Returns:
         Concatenation of all compiled files in the format given above.
@@ -160,15 +156,7 @@ def find_dependencies(module_name):
     # Subtract the (builtin or missing) modules we won't upload.
     dependencies = dependencies.difference(not_found)
 
-    print("Uploading:", path)
-    # If there are no dependencies, it is an old-style single file script.
-    # For backwards compatibility, upload just the mpy data. Once the new
-    # firmware is stable, we can remove this special case.
-    if not dependencies:
-        return await compile_file(path, abi)
-
     # Get the total tuple of main programs and module
-    print("Included modules:", dependencies)
     modules = [main_module] + sorted(tuple(dependencies))
 
     # Get a data blob with all scripts.