pybricksdev.cli: add support for flashing NXT bricks

This adds support to the `pybricksdev flash` command for flashing
firmware to LEGO MINDSTORMS NXT bricks.

Support for firmware metadata v2.1.0 is added to enable this.

Author: dlech

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Added `pybricksdev.ble.pybricks.Command.PBIO_PYBRICKS_COMMAND_REBOOT_TO_UPDATE_MODE`.
+- Added support for Pybricks firmware metadata v2.1.0.
+- Added support for flashing firmware to LEGO MINDSTORMS NXT bricks.
 
 ### Fixed
 - Fixed reboot in update mode for Pybricks Profile >= 1.2.0 in `pybricksdev flash` CLI.

pybricksdev/ble/lwp3/bytecodes.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021 The Pybricks Authors
+# Copyright (c) 2021-2023 The Pybricks Authors
 # Some portions of the documentation:
 # Copyright (c) 2018 LEGO System A/S
 
@@ -162,6 +162,9 @@ class SystemKind(IntEnum):
     TECHNIC = 4 << 5
     """LEGO Technic"""
 
+    LEGACY = 7 << 5
+    """Pre-Powered Up (unofficial Pybricks addition)"""
+
 
 @unique
 class HubKind(IntEnum):
@@ -201,6 +204,15 @@ class HubKind(IntEnum):
     TECHNIC_SMALL = 0x83
     """LEGO SPIKE Essential Hub."""
 
+    RCX = 0xE0
+    """LEGO MINDSTORMS RCX brick. (unofficial Pybricks addition)"""
+
+    NXT = 0xE1
+    """LEGO MINDSTORMS NXT brick. (unofficial Pybricks addition)"""
+
+    EV3 = 0xE2
+    """LEGO MINDSTORMS EV3 brick. (unofficial Pybricks addition)"""
+
     @property
     def system(self) -> SystemKind:
         """

pybricksdev/cli/flash.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2019-2022 The Pybricks Authors
+# Copyright (c) 2019-2023 The Pybricks Authors
 
 import asyncio
 import hashlib
@@ -312,9 +312,49 @@ async def flash_ble(hub_kind: HubKind, firmware: bytes, metadata: dict):
     await updater.flash(firmware, metadata)
 
 
+async def flash_nxt(firmware: bytes) -> None:
+    """
+    Flashes firmware to NXT using the Samba bootloader.
+
+    Args:
+        firmware:
+            A firmware blob with the NxOS header appended to the end.
+    """
+    from .._vendored.pynxt.samba import SambaBrick, SambaOpenError
+    from .._vendored.pynxt.firmware import Firmware
+    from .._vendored.pynxt.flash import FlashController
+
+    # parse the header
+    info = Firmware(firmware)
+
+    if info.samba:
+        raise ValueError("Firmware is not suitable for flashing.")
+
+    s = SambaBrick()
+
+    try:
+        print("Looking for the NXT in SAM-BA mode...")
+        s.open(timeout=5)
+        print("Brick found!")
+    except SambaOpenError as e:
+        print(e)
+        sys.exit(1)
+
+    print("Flashing firmware...")
+    f = FlashController(s)
+    f.flash(firmware)
+
+    print("Flashing complete, jumping to 0x100000...")
+    f._wait_for_flash()
+    s.jump(0x100000)
+
+    print("Firmware started.")
+    s.close()
+
+
 async def flash_firmware(firmware_zip: BinaryIO, new_name: Optional[str]) -> None:
     """
-    Command line tool for flasing firmware.
+    Command line tool for flashing firmware.
 
     Args:
         firmware_zip: The path to the ``firmware.zip`` file.
@@ -364,5 +404,9 @@ async def flash_firmware(firmware_zip: BinaryIO, new_name: Optional[str]) -> Non
         except OSError:
             print("Could not find hub in standard firmware mode. Trying DFU.")
             flash_dfu(firmware, metadata)
-    else:
+    elif hub_kind in [HubKind.BOOST, HubKind.CITY, HubKind.TECHNIC]:
         await flash_ble(hub_kind, firmware, metadata)
+    elif hub_kind == HubKind.NXT:
+        await flash_nxt(firmware)
+    else:
+        raise ValueError(f"unsupported hub kind: {hub_kind}")

pybricksdev/firmware.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2022 The Pybricks Authors
+# Copyright (c) 2022-2023 The Pybricks Authors
 
 """
 Utilities for working with Pybricks ``firmware.zip`` files.
@@ -15,9 +15,9 @@
 
 
 if sys.version_info < (3, 10):
-    from typing_extensions import TypeGuard, TypeAlias
+    from typing_extensions import TypeGuard
 else:
-    from typing import TypeGuard, TypeAlias
+    from typing import TypeGuard
 
 import semver
 
@@ -69,7 +69,7 @@ class FirmwareMetadataV200(
         {
             "metadata-version": Literal["2.0.0"],
             "firmware-version": str,
-            "device-id": Literal[0x40, 0x41, 0x80, 0x81, 83],
+            "device-id": Literal[0x40, 0x41, 0x80, 0x81, 0x83],
             "checksum-type": Literal["sum", "crc32"],
             "checksum-size": int,
             "hub-name-offset": int,
@@ -82,12 +82,29 @@ class FirmwareMetadataV200(
     """
 
 
+class FirmwareMetadataV210(
+    FirmwareMetadataV200,
+    TypedDict(
+        "V210",
+        {
+            # changed
+            "metadata-version": Literal["2.1.0"],
+            "device-id": Literal[0x40, 0x41, 0x80, 0x81, 0x83, 0xE0, 0xE1, 0xE2],
+            "checksum-type": Literal["sum", "crc32", "none"],
+        },
+    ),
+):
+    """
+    Type for data contained in v2.1.0 ``firmware.metadata.json`` files.
+    """
+
+
 AnyFirmwareV1Metadata = Union[FirmwareMetadataV100, FirmwareMetadataV110]
 """
 Type for data contained in ``firmware.metadata.json`` files of any 1.x version.
 """
 
-AnyFirmwareV2Metadata: TypeAlias = FirmwareMetadataV200
+AnyFirmwareV2Metadata = Union[FirmwareMetadataV200, FirmwareMetadataV210]
 """
 Type for data contained in ``firmware.metadata.json`` files of any 2.x version.
 """
@@ -180,6 +197,9 @@ async def _create_firmware_v2(
 
     # Update hub name if given
     if name:
+        if not metadata["hub-name-offset"]:
+            raise ValueError("this firmware does not support changing the hub name")
+
         name = name.encode() + b"\0"
 
         max_size = metadata["hub-name-size"]
@@ -197,6 +217,11 @@ async def _create_firmware_v2(
         checksum = sum_complement(io.BytesIO(firmware), metadata["checksum-size"])
     elif metadata["checksum-type"] == "crc32":
         checksum = crc32_checksum(io.BytesIO(firmware), metadata["checksum-size"])
+    elif (
+        semver.compare(metadata["metadata-version"], "2.1.0") >= 0
+        and metadata["checksum-type"] == "none"
+    ):
+        return firmware
     else:
         raise ValueError(f"unsupported checksum type: {metadata['checksum-type']}")