tooling: Add make daplink-firmware and make daplink-deploy targets.

Author: nedseb

.devcontainer/Dockerfile

@@ -1,11 +1,13 @@
 FROM mcr.microsoft.com/devcontainers/python:3.10
 
-# System packages for MicroPython firmware build and board communication
+# System packages for MicroPython and DAPLink firmware builds, board communication
 RUN apt-get update && apt-get install -y --no-install-recommends \
     gcc-arm-none-eabi \
     libnewlib-arm-none-eabi \
     openocd \
     udev \
+    ccache \
+    ninja-build \
     && rm -rf /var/lib/apt/lists/*
 
 # udev rules for STeaMi board (DAPLink / STM32)

CONTRIBUTING.md

@@ -119,7 +119,8 @@ For local development (without dev container):
 
 * Python 3.10+
 * Node.js 22+ (for husky, commitlint, lint-staged, semantic-release)
-* `arm-none-eabi-gcc` toolchain (for `make micropython-firmware`)
+* `arm-none-eabi-gcc` toolchain (for `make micropython-firmware` and `make daplink-firmware`)
+* `ccache` and `ninja-build` (for `make daplink-firmware`)
 * `pyocd` (for `make micropython-deploy`, installed via `pip install -e ".[flash]"`)
 * OpenOCD (optional, for `make micropython-deploy-openocd`)
 * `mpremote` (installed via `pip install -e ".[test]"`)
@@ -129,7 +130,7 @@ Then run `make setup` to install all dependencies and git hooks. This creates a
 
 ## Dev Container
 
-A dev container is available for VS Code (local Docker only, not GitHub Codespaces). It includes all prerequisites out of the box: Python 3.10, Node.js 22, ruff, pytest, mpremote, pyOCD, arm-none-eabi-gcc, OpenOCD, and the GitHub CLI.
+A dev container is available for VS Code (local Docker only, not GitHub Codespaces). It includes all prerequisites out of the box: Python 3.10, Node.js 22, ruff, pytest, mpremote, pyOCD, arm-none-eabi-gcc, OpenOCD, ccache, ninja-build, and the GitHub CLI.
 
 1. Open the repository in VS Code
 2. When prompted, click **Reopen in Container** (or use the command palette: *Dev Containers: Reopen in Container*)
@@ -191,9 +192,11 @@ make bump PART=major   # major: v1.1.0 → v2.0.0
 The STeaMi board has two distinct firmwares:
 
 - **MicroPython firmware** — runs on the STM32WB55 main MCU and exposes the drivers from this repository
-- **DAPLink firmware** — runs on the STM32F103 interface chip and provides the I2C bridge, mass-storage, and CMSIS-DAP debug interface (build targets planned in #377)
+- **DAPLink firmware** — runs on the STM32F103 interface chip and provides the I2C bridge, mass-storage, and CMSIS-DAP debug interface
 
-This section covers the **MicroPython firmware** only. The drivers in this repository are "frozen" into it. The Makefile automates cloning, building, and flashing:
+The drivers in this repository are "frozen" into the **MicroPython firmware**. The Makefile automates cloning, building, and flashing both firmwares.
+
+### MicroPython firmware
 
 ```bash
 make micropython-firmware         # Clone micropython-steami (if needed), link local drivers, build
@@ -215,6 +218,27 @@ Use `make micropython-firmware` for normal rebuilds from the existing local clon
 
 All these tools are included in the dev container. For local development, see the [Prerequisites](#prerequisites) section.
 
+### DAPLink firmware
+
+DAPLink is the firmware running on the STM32F103 interface chip. It provides the USB mass-storage, CMSIS-DAP debug interface, and the I2C bridge used by `daplink_bridge` / `daplink_flash` / `steami_config`.
+
+DAPLink consists of **two parts**:
+
+- **Bootloader** (first stage, flashed at `0x08000000`) — installed once at the factory, rarely updated. It provides the MAINTENANCE mode used to update the interface firmware. Updating the bootloader requires an external SWD probe and is not covered by these targets.
+- **Interface firmware** (second stage, flashed at `0x08002000`) — the part that contains the I2C bridge, mass-storage, debug interface, and is updated routinely. This is what the `daplink-*` Makefile targets manage.
+
+```bash
+make daplink-firmware             # Clone steamicc/DAPLink and build stm32f103xb_steami32_if
+make daplink-update               # Refresh the DAPLink clone
+make daplink-deploy               # Flash DAPLink interface firmware (default: usb mass-storage)
+make daplink-deploy-usb           # Flash DAPLink interface firmware via MAINTENANCE volume
+make daplink-clean                # Clean DAPLink build artifacts
+```
+
+The DAPLink source is cloned from [steamicc/DAPLink](https://github.com/steamicc/DAPLink) into `.build/DAPLink/` (gitignored). A Python virtualenv is created automatically inside the clone for the progen build tool.
+
+**Maintenance mode:** to flash the DAPLink interface firmware, the board must be in maintenance mode. Power on the board with the RESET button held until a `MAINTENANCE` USB volume appears (instead of the usual `STeaMi` volume). The `make daplink-deploy-usb` target then copies the firmware to that volume and the board reboots automatically with the new interface firmware.
+
 ## Notes
 
 * Keep implementations simple and readable

Makefile

@@ -191,6 +191,55 @@ micropython-clean: ## Clean MicroPython firmware build artifacts
 		$(MAKE) -C $(STM32_DIR) BOARD=$(BOARD) clean; \
 	fi
 
+# --- DAPLink firmware ---
+# These targets manage the DAPLink **interface firmware** only (the second
+# stage of DAPLink, flashed at 0x08002000). The bootloader (first stage,
+# flashed at 0x08000000) is installed once at the factory and is not
+# managed here. A future `daplink-deploy-bootloader` target could be added
+# if needed, but it requires an external SWD probe and is rarely necessary.
+
+$(DAPLINK_DIR):
+	@echo "Cloning DAPLink into $(CURDIR)/$(DAPLINK_DIR)..."
+	@mkdir -p $(dir $(CURDIR)/$(DAPLINK_DIR))
+	git clone --branch $(DAPLINK_BRANCH) $(DAPLINK_REPO) $(CURDIR)/$(DAPLINK_DIR)
+
+.PHONY: daplink-firmware
+daplink-firmware: $(DAPLINK_DIR) ## Build DAPLink interface firmware for the STeaMi STM32F103
+	@set -e
+	@if [ ! -d "$(DAPLINK_DIR)/venv" ]; then \
+		echo "Setting up DAPLink Python virtualenv..."; \
+		$(PYTHON) -m venv $(DAPLINK_DIR)/venv; \
+		$(DAPLINK_DIR)/venv/bin/pip install -r $(DAPLINK_DIR)/requirements.txt; \
+	fi
+	@echo "Building DAPLink target $(DAPLINK_TARGET)..."
+	cd $(CURDIR)/$(DAPLINK_DIR) && \
+		./venv/bin/python tools/progen_compile.py -t make_gcc_arm $(DAPLINK_TARGET)
+	@echo "DAPLink firmware ready: $(DAPLINK_BUILD_DIR)/$(DAPLINK_TARGET)_crc.bin"
+
+.PHONY: daplink-update
+daplink-update: $(DAPLINK_DIR) ## Update the DAPLink clone
+	@set -e
+	@echo "Updating DAPLink..."
+	git -C $(CURDIR)/$(DAPLINK_DIR) fetch origin
+	git -C $(CURDIR)/$(DAPLINK_DIR) checkout $(DAPLINK_BRANCH)
+	git -C $(CURDIR)/$(DAPLINK_DIR) pull --ff-only
+
+.PHONY: daplink-deploy
+daplink-deploy: daplink-deploy-usb ## Flash DAPLink interface firmware (default: usb mass-storage)
+
+.PHONY: daplink-deploy-usb
+daplink-deploy-usb: ## Flash DAPLink interface firmware via MAINTENANCE USB mass-storage
+	@echo "Note: the board must be in MAINTENANCE mode."
+	@echo "Power on the board with the RESET button held until the MAINTENANCE volume appears."
+	@echo ""
+	@$(PYTHON) scripts/deploy_usb.py --label MAINTENANCE $(DAPLINK_BUILD_DIR)/$(DAPLINK_TARGET)_crc.bin
+
+.PHONY: daplink-clean
+daplink-clean: ## Clean DAPLink firmware build artifacts
+	@if [ -d "$(DAPLINK_DIR)" ]; then \
+		rm -rf $(DAPLINK_DIR)/projectfiles; \
+	fi
+
 # --- Hardware ---
 
 .PHONY: repl

env.mk

@@ -1,10 +1,18 @@
 export PATH := $(CURDIR)/node_modules/.bin:$(PATH)
 PORT ?= /dev/ttyACM0
 
-# Firmware build configuration
+BUILD_DIR ?= .build
+
+# MicroPython firmware build configuration
 MICROPYTHON_REPO ?= https://github.com/steamicc/micropython-steami.git
 MICROPYTHON_BRANCH ?= stm32-steami-rev1d-final
 BOARD ?= STEAM32_WB55RG
-BUILD_DIR ?= .build
 MPY_DIR ?= $(BUILD_DIR)/micropython-steami
 STM32_DIR ?= $(MPY_DIR)/ports/stm32
+
+# DAPLink firmware build configuration
+DAPLINK_REPO ?= https://github.com/steamicc/DAPLink.git
+DAPLINK_BRANCH ?= release_letssteam
+DAPLINK_DIR ?= $(BUILD_DIR)/DAPLink
+DAPLINK_TARGET ?= stm32f103xb_steami32_if
+DAPLINK_BUILD_DIR ?= $(DAPLINK_DIR)/projectfiles/make_gcc_arm/$(DAPLINK_TARGET)/build

scripts/deploy_usb.py

@@ -1,30 +1,34 @@
-"""Deploy MicroPython firmware to a STeaMi board via DAPLink USB mass-storage.
+"""Deploy a firmware binary to a STeaMi board via DAPLink USB mass-storage.
 
-Detects the STeaMi volume by its label across Linux, macOS, and Windows,
+Detects the target volume by its label across Linux, macOS, and Windows,
 copies the firmware .bin to it, and lets DAPLink auto-reset the target.
 
+The default label is ``STeaMi`` (normal mode, used for MicroPython firmware).
+For DAPLink firmware updates, the board must be in maintenance mode (boot
+with the RESET button held) and the volume label is ``MAINTENANCE``.
+
 Usage:
     python scripts/deploy_usb.py path/to/firmware.bin
+    python scripts/deploy_usb.py --label MAINTENANCE path/to/daplink.bin
 """
 
+import argparse
 import os
 import platform
 import shutil
 import subprocess
 import sys
 
-VOLUME_LABEL = "STeaMi"
-
 
-def find_steami_linux():
-    """Find STeaMi mount point on Linux via findmnt.
+def find_volume_linux(label):
+    """Find the mount point of a labelled volume on Linux via findmnt.
 
-    Returns the mount path, or ``None`` if the board is not mounted
+    Returns the mount path, or ``None`` if the volume is not mounted
     or ``findmnt`` is not available.
     """
     try:
         result = subprocess.run(
-            ["findmnt", "-n", "-o", "TARGET", "-S", "LABEL=" + VOLUME_LABEL],
+            ["findmnt", "-n", "-o", "TARGET", "-S", "LABEL=" + label],
             capture_output=True,
             text=True,
             check=False,
@@ -37,22 +41,22 @@ def find_steami_linux():
     return None
 
 
-def find_steami_macos():
-    """Find STeaMi mount point on macOS.
+def find_volume_macos(label):
+    """Find the mount point of a labelled volume on macOS.
 
-    Returns ``/Volumes/STeaMi`` if the board is mounted, or ``None``.
+    Returns ``/Volumes/<label>`` if the volume is mounted, or ``None``.
     """
-    path = "/Volumes/" + VOLUME_LABEL
+    path = "/Volumes/" + label
     if os.path.isdir(path):
         return path
     return None
 
 
-def _find_steami_windows_powershell():
-    """Find STeaMi drive letter via PowerShell Get-Volume (preferred)."""
+def _find_volume_windows_powershell(label):
+    """Find a labelled volume drive letter via PowerShell Get-Volume."""
     ps_cmd = (
         "Get-Volume | Where-Object FileSystemLabel -eq '"
-        + VOLUME_LABEL
+        + label
         + "' | Select-Object -First 1 -ExpandProperty DriveLetter"
     )
     try:
@@ -71,15 +75,15 @@ def _find_steami_windows_powershell():
     return None
 
 
-def _find_steami_windows_wmic():
-    """Find STeaMi drive letter via legacy wmic (fallback for older Windows)."""
+def _find_volume_windows_wmic(label):
+    """Find a labelled volume drive letter via legacy wmic (fallback)."""
     try:
         result = subprocess.run(
             [
                 "wmic",
                 "logicaldisk",
                 "where",
-                "VolumeName='" + VOLUME_LABEL + "'",
+                "VolumeName='" + label + "'",
                 "get",
                 "DeviceID",
                 "/value",
@@ -99,58 +103,80 @@ def _find_steami_windows_wmic():
     return None
 
 
-def find_steami_windows():
-    """Find STeaMi drive letter on Windows.
+def find_volume_windows(label):
+    """Find a labelled volume drive letter on Windows.
 
     Tries PowerShell Get-Volume first (works on all modern Windows),
     falls back to wmic for older systems where PowerShell is unavailable.
-    Returns the drive path (e.g. ``E:\\``), or ``None`` if the board is
+    Returns the drive path (e.g. ``E:\\``), or ``None`` if the volume is
     not mounted or neither tool is available.
     """
-    return _find_steami_windows_powershell() or _find_steami_windows_wmic()
+    return _find_volume_windows_powershell(label) or _find_volume_windows_wmic(label)
 
 
-def find_steami():
-    """Detect the STeaMi USB volume across platforms.
+def find_volume(label):
+    """Detect a USB volume by its filesystem label across platforms.
 
     Returns the mount path as a string (e.g. ``/media/user/STeaMi``,
-    ``/Volumes/STeaMi``, or ``E:\\``) when a volume with label ``STeaMi``
-    is found, or ``None`` if the board is not mounted (or the detection
+    ``/Volumes/STeaMi``, or ``E:\\``) when a volume with the given label
+    is found, or ``None`` if the volume is not mounted (or the detection
     tool — findmnt, PowerShell, wmic — is not available on the system).
 
     Exits with an error on unsupported operating systems.
     """
     system = platform.system()
     if system == "Linux":
-        return find_steami_linux()
+        return find_volume_linux(label)
     if system == "Darwin":
-        return find_steami_macos()
+        return find_volume_macos(label)
     if system == "Windows":
-        return find_steami_windows()
+        return find_volume_windows(label)
     print("Error: unsupported OS: " + system, file=sys.stderr)
     sys.exit(1)
 
 
 def main():
-    if len(sys.argv) != 2:
-        print("Usage: deploy_usb.py <firmware.bin>", file=sys.stderr)
-        sys.exit(1)
+    parser = argparse.ArgumentParser(
+        description="Deploy a firmware binary to a STeaMi board via USB mass-storage.",
+    )
+    parser.add_argument(
+        "firmware",
+        help="Path to the firmware .bin file to deploy.",
+    )
+    parser.add_argument(
+        "--label",
+        default="STeaMi",
+        help=(
+            "Filesystem label of the target volume. "
+            "Use 'STeaMi' (default) for MicroPython firmware updates "
+            "or 'MAINTENANCE' for DAPLink firmware updates "
+            "(the board must be powered on with RESET held to enter maintenance mode)."
+        ),
+    )
+    args = parser.parse_args()
 
-    firmware = sys.argv[1]
-    if not os.path.isfile(firmware):
-        print("Error: firmware binary not found: " + firmware, file=sys.stderr)
-        print("Run 'make micropython-firmware' first.", file=sys.stderr)
+    if not os.path.isfile(args.firmware):
+        print("Error: firmware binary not found: " + args.firmware, file=sys.stderr)
+        print("Build the firmware first.", file=sys.stderr)
         sys.exit(1)
 
-    mount = find_steami()
+    mount = find_volume(args.label)
     if not mount or not os.path.isdir(mount):
         print(
-            "Error: STeaMi board not found (no volume with label '"
-            + VOLUME_LABEL
-            + "').",
+            "Error: no volume with label '" + args.label + "' found.",
             file=sys.stderr,
         )
-        print("Check that the board is connected and mounted.", file=sys.stderr)
+        if args.label == "MAINTENANCE":
+            print(
+                "To enter DAPLink maintenance mode, power on the board with the "
+                "RESET button held until the MAINTENANCE volume appears.",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                "Check that the board is connected and mounted.",
+                file=sys.stderr,
+            )
         if platform.system() == "Windows":
             print(
                 "On Windows, this requires PowerShell (Get-Volume) or wmic.",
@@ -159,7 +185,7 @@ def main():
         sys.exit(1)
 
     print("Copying firmware to " + mount + "...")
-    shutil.copy(firmware, mount)
+    shutil.copy(args.firmware, mount)
 
     # Best-effort flush on Unix (no-op on Windows)
     if hasattr(os, "sync"):