From cddecebf06d8f471fde166355385d912d7184e40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= <sebastien@nedjar.com>
Date: Mon, 13 Apr 2026 05:27:08 +0200
Subject: [PATCH 1/6] tooling: Add make daplink-firmware and make
 daplink-deploy targets.

---
 .devcontainer/Dockerfile |   4 +-
 CONTRIBUTING.md          |  32 +++++++++--
 Makefile                 |  55 +++++++++++++++++-
 env.mk                   |  12 +++-
 scripts/deploy_usb.py    | 118 +++++++++++++++++++++++++--------------
 5 files changed, 171 insertions(+), 50 deletions(-)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index ca3a52eb..d83205db 100644
--- a/.devcontainer/Dockerfile
+++ b/.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)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1b4593d9..d2bd9b27 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/Makefile b/Makefile
index f374819c..246ceaa2 100644
--- a/Makefile
+++ b/Makefile
@@ -136,7 +136,9 @@ micropython-deploy-openocd: $(MPY_DIR) ## Flash MicroPython firmware via OpenOCD
 
 .PHONY: micropython-deploy-usb
 micropython-deploy-usb: $(MPY_DIR) ## Flash MicroPython firmware via DAPLink USB mass-storage
-	@$(PYTHON) scripts/deploy_usb.py $(STM32_DIR)/build-$(BOARD)/firmware.bin
+	@$(PYTHON) scripts/deploy_usb.py \
+		--build-target micropython-firmware \
+		$(STM32_DIR)/build-$(BOARD)/firmware.bin
 
 # --- Deprecated targets (ambiguous since DAPLink build is also planned) ---
 # Replaced by explicit micropython-* / daplink-* targets to avoid confusion
@@ -191,6 +193,57 @@ 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: $(DAPLINK_DIR) ## 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 \
+		--build-target daplink-firmware \
+		$(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
diff --git a/env.mk b/env.mk
index 54f24d91..dc1aee5d 100644
--- a/env.mk
+++ b/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
diff --git a/scripts/deploy_usb.py b/scripts/deploy_usb.py
index 93a2afda..d6aafe02 100644
--- a/scripts/deploy_usb.py
+++ b/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,88 @@ 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)."
+        ),
+    )
+    parser.add_argument(
+        "--build-target",
+        default="micropython-firmware",
+        help=(
+            "Make target to suggest if the firmware binary is missing "
+            "(default: 'micropython-firmware')."
+        ),
+    )
+    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("Run 'make " + args.build_target + "' 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 +193,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"):

From 58759bd86527d4559e5b3c73f6a9cd3b30653a3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= <sebastien@nedjar.com>
Date: Mon, 13 Apr 2026 06:13:34 +0200
Subject: [PATCH 2/6] fix(daplink_bridge): Pin gcc 10.3 and expose venv python
 for DAPLink build.

The DAPLink build failed on systems without a `python` symlink (Debian/Ubuntu
ship only `python3`) because the generated Makefile invokes
`tools/pre_build_script.py` via its `#!/usr/bin/env python` shebang, which
silently skips `version_git.h` generation. It also failed on modern toolchains
(arm-none-eabi-gcc >= 11) because the firmware overflows the m_text region;
DAPLink's docs pin gcc-arm-none-eabi to 10.3-2021.10.

Prepend the DAPLink venv to PATH so `python` resolves, and download the pinned
toolchain into .build/ on first build, using it only for daplink-firmware.
---
 Makefile | 12 ++++++++++--
 env.mk   |  7 +++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 246ceaa2..e3c46fbc 100644
--- a/Makefile
+++ b/Makefile
@@ -205,16 +205,24 @@ $(DAPLINK_DIR):
 	@mkdir -p $(dir $(CURDIR)/$(DAPLINK_DIR))
 	git clone --branch $(DAPLINK_BRANCH) $(DAPLINK_REPO) $(CURDIR)/$(DAPLINK_DIR)
 
+$(DAPLINK_GCC_DIR)/bin/arm-none-eabi-gcc:
+	@echo "Downloading gcc-arm-none-eabi $(DAPLINK_GCC_VERSION) for DAPLink..."
+	@mkdir -p $(BUILD_DIR)
+	curl -fL -o $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2 "$(DAPLINK_GCC_URL)"
+	tar -xjf $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2 -C $(BUILD_DIR)
+	rm -f $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2
+
 .PHONY: daplink-firmware
-daplink-firmware: $(DAPLINK_DIR) ## Build DAPLink interface firmware for the STeaMi STM32F103
+daplink-firmware: $(DAPLINK_DIR) $(DAPLINK_GCC_DIR)/bin/arm-none-eabi-gcc ## 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)..."
+	@echo "Building DAPLink target $(DAPLINK_TARGET) with gcc-arm-none-eabi $(DAPLINK_GCC_VERSION)..."
 	cd $(CURDIR)/$(DAPLINK_DIR) && \
+		PATH="$(CURDIR)/$(DAPLINK_GCC_DIR)/bin:$(CURDIR)/$(DAPLINK_DIR)/venv/bin:$$PATH" \
 		./venv/bin/python tools/progen_compile.py -t make_gcc_arm $(DAPLINK_TARGET)
 	@echo "DAPLink firmware ready: $(DAPLINK_BUILD_DIR)/$(DAPLINK_TARGET)_crc.bin"
 
diff --git a/env.mk b/env.mk
index dc1aee5d..df14757b 100644
--- a/env.mk
+++ b/env.mk
@@ -16,3 +16,10 @@ 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
+
+# DAPLink requires gcc-arm-none-eabi 10.3-2021.10. System toolchains >= 11.3
+# produce code that overflows m_text (see DAPLink docs/DEVELOPERS-GUIDE.md and
+# ARMmbed/DAPLink#1043). The toolchain is downloaded once into BUILD_DIR.
+DAPLINK_GCC_VERSION ?= 10.3-2021.10
+DAPLINK_GCC_DIR ?= $(BUILD_DIR)/gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)
+DAPLINK_GCC_URL ?= https://developer.arm.com/-/media/Files/downloads/gnu-rm/$(DAPLINK_GCC_VERSION)/gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)-x86_64-linux.tar.bz2

From d0a5783718d3386844db170f2f939c9349ea51b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= <sebastien@nedjar.com>
Date: Mon, 13 Apr 2026 06:17:16 +0200
Subject: [PATCH 3/6] ci(daplink_bridge): Attach DAPLink interface firmware to
 GitHub releases.

Mirror the existing micropython-firmware release job: build the DAPLink
interface firmware after each semantic-release publish and upload the
CRC-signed .bin / .hex (the artifacts users flash via MAINTENANCE mode).
---
 .github/workflows/release.yml | 40 +++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 28d22ebc..dd218496 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -85,3 +85,43 @@ jobs:
             "steami-micropython-firmware-${VERSION}.hex" \
             "steami-micropython-firmware-${VERSION}.bin" \
             --clobber
+
+  daplink-firmware:
+    name: Build and attach DAPLink firmware
+    needs: release
+    if: needs.release.outputs.new-release-published == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Generate token
+        id: generate_token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.RELEASE_APP_ID }}
+          private_key: ${{ secrets.RELEASE_APP_SECRET }}
+
+      - uses: actions/checkout@v4
+        with:
+          ref: v${{ needs.release.outputs.new-release-version }}
+
+      - name: Install build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ccache ninja-build python3-venv
+
+      - name: Build DAPLink firmware
+        run: make daplink-firmware
+
+      - name: Attach DAPLink firmware to release
+        env:
+          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+        run: |
+          VERSION="v${{ needs.release.outputs.new-release-version }}"
+          BUILD_DIR=".build/DAPLink/projectfiles/make_gcc_arm/stm32f103xb_steami32_if/build"
+          cp "${BUILD_DIR}/stm32f103xb_steami32_if_crc.bin" "steami-daplink-firmware-${VERSION}.bin"
+          cp "${BUILD_DIR}/stm32f103xb_steami32_if_crc.hex" "steami-daplink-firmware-${VERSION}.hex"
+          gh release upload "$VERSION" \
+            "steami-daplink-firmware-${VERSION}.bin" \
+            "steami-daplink-firmware-${VERSION}.hex" \
+            --clobber

From 9e6ac933bf67ef46654690eec6cf19581236fe69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= <sebastien@nedjar.com>
Date: Mon, 13 Apr 2026 06:20:40 +0200
Subject: [PATCH 4/6] ci(daplink_bridge): Cache gcc toolchain and Python venv
 for DAPLink builds.

Caches the pinned gcc-arm-none-eabi 10.3-2021.10 toolchain (~150 MB) and
the DAPLink Python virtualenv (~250 MB) between release runs. The toolchain
key is fixed (the version is pinned), and the venv key is derived from
requirements.txt so it invalidates when DAPLink upstream bumps a dependency.
---
 .github/workflows/release.yml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index dd218496..ebcd65f5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -110,6 +110,21 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends ccache ninja-build python3-venv
 
+      - name: Clone DAPLink (needed for venv cache key)
+        run: make .build/DAPLink
+
+      - name: Cache gcc-arm-none-eabi 10.3-2021.10
+        uses: actions/cache@v4
+        with:
+          path: .build/gcc-arm-none-eabi-10.3-2021.10
+          key: gcc-arm-none-eabi-10.3-2021.10-linux-x86_64
+
+      - name: Cache DAPLink Python venv
+        uses: actions/cache@v4
+        with:
+          path: .build/DAPLink/venv
+          key: daplink-venv-${{ runner.os }}-${{ hashFiles('.build/DAPLink/requirements.txt') }}
+
       - name: Build DAPLink firmware
         run: make daplink-firmware
 

From 79560dd32367c8fc6b9e0af965f362b5e48b616e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= <sebastien@nedjar.com>
Date: Mon, 13 Apr 2026 06:30:43 +0200
Subject: [PATCH 5/6] fix(daplink_bridge): Address review on portability and
 venv staleness.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three issues raised on PR #387:

1. Toolchain download was hard-coded to x86_64-linux. Detect uname and pick
   the matching ARM-published archive (Linux x86_64, Linux aarch64, Intel
   macOS). Fail with a clear message — and a pointer to the dev container —
   on Apple Silicon and Windows, where 10.3-2021.10 is not published.

2. Deprecated `deploy-pyocd` / `deploy-openocd` advertised non-existent
   `daplink-deploy-pyocd` / `daplink-deploy-openocd` targets. Suggest only
   the `micropython-` variant until the SWD-based DAPLink targets land
   (tracked in #388).

3. The DAPLink venv was created once and never refreshed, so a
   `daplink-update` that bumped requirements.txt would silently reuse stale
   dependencies. Replace the manual check with a sentinel file that depends
   on requirements.txt, so pip install re-runs whenever upstream bumps a dep.

Also document the platform constraint in CONTRIBUTING.md.
---
 CONTRIBUTING.md |  3 ++-
 Makefile        | 40 ++++++++++++++++++++++++++++++----------
 env.mk          | 21 ++++++++++++++++++++-
 3 files changed, 52 insertions(+), 12 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d2bd9b27..cb3f68c7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -119,8 +119,9 @@ 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` and `make daplink-firmware`)
+* `arm-none-eabi-gcc` toolchain (for `make micropython-firmware`; `make daplink-firmware` ignores the system toolchain and downloads its own pinned 10.3-2021.10 build)
 * `ccache` and `ninja-build` (for `make daplink-firmware`)
+* For `make daplink-firmware`: Linux x86_64, Linux aarch64, or Intel macOS only (the pinned toolchain is not published for Apple Silicon or Windows — use the dev container on those platforms)
 * `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]"`)
diff --git a/Makefile b/Makefile
index e3c46fbc..f844b967 100644
--- a/Makefile
+++ b/Makefile
@@ -147,7 +147,15 @@ micropython-deploy-usb: $(MPY_DIR) ## Flash MicroPython firmware via DAPLink USB
 define DEPRECATED_FIRMWARE
 @echo "Error: 'make $(1)' is ambiguous. Use one of:"; \
 echo "  make micropython-$(2)   (MicroPython firmware)"; \
-echo "  make daplink-$(2)       (DAPLink firmware, see #377)"; \
+echo "  make daplink-$(2)       (DAPLink firmware)"; \
+exit 1
+endef
+
+# Variant for short names whose DAPLink counterpart does not exist yet
+# (daplink-deploy-pyocd / daplink-deploy-openocd are tracked in #388).
+define DEPRECATED_MICROPYTHON_ONLY
+@echo "Error: 'make $(1)' has been renamed. Use:"; \
+echo "  make micropython-$(2)   (MicroPython firmware)"; \
 exit 1
 endef
 
@@ -161,9 +169,9 @@ firmware-clean:
 deploy:
 	$(call DEPRECATED_FIRMWARE,deploy,deploy)
 deploy-pyocd:
-	$(call DEPRECATED_FIRMWARE,deploy-pyocd,deploy-pyocd)
+	$(call DEPRECATED_MICROPYTHON_ONLY,deploy-pyocd,deploy-pyocd)
 deploy-openocd:
-	$(call DEPRECATED_FIRMWARE,deploy-openocd,deploy-openocd)
+	$(call DEPRECATED_MICROPYTHON_ONLY,deploy-openocd,deploy-openocd)
 deploy-usb:
 	$(call DEPRECATED_FIRMWARE,deploy-usb,deploy-usb)
 
@@ -206,20 +214,32 @@ $(DAPLINK_DIR):
 	git clone --branch $(DAPLINK_BRANCH) $(DAPLINK_REPO) $(CURDIR)/$(DAPLINK_DIR)
 
 $(DAPLINK_GCC_DIR)/bin/arm-none-eabi-gcc:
-	@echo "Downloading gcc-arm-none-eabi $(DAPLINK_GCC_VERSION) for DAPLink..."
+	@set -e
+	@if [ -z "$(DAPLINK_GCC_ARCHIVE)" ]; then \
+		echo "Error: no prebuilt gcc-arm-none-eabi $(DAPLINK_GCC_VERSION) for $(DAPLINK_GCC_HOST_OS)/$(DAPLINK_GCC_HOST_ARCH)."; \
+		echo "Supported by this target: Linux x86_64, Linux aarch64, macOS Intel."; \
+		echo "Other platforms: install the toolchain manually and override DAPLINK_GCC_DIR,"; \
+		echo "or build inside the dev container."; \
+		exit 1; \
+	fi
+	@echo "Downloading gcc-arm-none-eabi $(DAPLINK_GCC_VERSION) for $(DAPLINK_GCC_HOST_OS)/$(DAPLINK_GCC_HOST_ARCH)..."
 	@mkdir -p $(BUILD_DIR)
 	curl -fL -o $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2 "$(DAPLINK_GCC_URL)"
 	tar -xjf $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2 -C $(BUILD_DIR)
 	rm -f $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2
 
-.PHONY: daplink-firmware
-daplink-firmware: $(DAPLINK_DIR) $(DAPLINK_GCC_DIR)/bin/arm-none-eabi-gcc ## Build DAPLink interface firmware for the STeaMi STM32F103
-	@set -e
-	@if [ ! -d "$(DAPLINK_DIR)/venv" ]; then \
-		echo "Setting up DAPLink Python virtualenv..."; \
+# Sentinel: re-runs pip install whenever DAPLink's requirements.txt changes
+# (e.g. after `make daplink-update`).
+$(DAPLINK_DIR)/venv/.installed: $(DAPLINK_DIR)/requirements.txt
+	@echo "Setting up DAPLink Python virtualenv..."
+	@if [ ! -x "$(DAPLINK_DIR)/venv/bin/python" ]; then \
 		$(PYTHON) -m venv $(DAPLINK_DIR)/venv; \
-		$(DAPLINK_DIR)/venv/bin/pip install -r $(DAPLINK_DIR)/requirements.txt; \
 	fi
+	$(DAPLINK_DIR)/venv/bin/pip install -r $(DAPLINK_DIR)/requirements.txt
+	@touch $@
+
+.PHONY: daplink-firmware
+daplink-firmware: $(DAPLINK_DIR) $(DAPLINK_GCC_DIR)/bin/arm-none-eabi-gcc $(DAPLINK_DIR)/venv/.installed ## Build DAPLink interface firmware for the STeaMi STM32F103
 	@echo "Building DAPLink target $(DAPLINK_TARGET) with gcc-arm-none-eabi $(DAPLINK_GCC_VERSION)..."
 	cd $(CURDIR)/$(DAPLINK_DIR) && \
 		PATH="$(CURDIR)/$(DAPLINK_GCC_DIR)/bin:$(CURDIR)/$(DAPLINK_DIR)/venv/bin:$$PATH" \
diff --git a/env.mk b/env.mk
index df14757b..364dde83 100644
--- a/env.mk
+++ b/env.mk
@@ -20,6 +20,25 @@ DAPLINK_BUILD_DIR ?= $(DAPLINK_DIR)/projectfiles/make_gcc_arm/$(DAPLINK_TARGET)/
 # DAPLink requires gcc-arm-none-eabi 10.3-2021.10. System toolchains >= 11.3
 # produce code that overflows m_text (see DAPLink docs/DEVELOPERS-GUIDE.md and
 # ARMmbed/DAPLink#1043). The toolchain is downloaded once into BUILD_DIR.
+#
+# ARM publishes 10.3-2021.10 binaries for: x86_64 Linux, aarch64 Linux, and
+# Intel macOS. Apple Silicon and Windows are NOT supported by this target —
+# users on those platforms must install the toolchain manually and override
+# DAPLINK_GCC_DIR / DAPLINK_GCC_URL, or build inside the dev container.
 DAPLINK_GCC_VERSION ?= 10.3-2021.10
 DAPLINK_GCC_DIR ?= $(BUILD_DIR)/gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)
-DAPLINK_GCC_URL ?= https://developer.arm.com/-/media/Files/downloads/gnu-rm/$(DAPLINK_GCC_VERSION)/gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)-x86_64-linux.tar.bz2
+
+DAPLINK_GCC_HOST_OS := $(shell uname -s)
+DAPLINK_GCC_HOST_ARCH := $(shell uname -m)
+ifeq ($(DAPLINK_GCC_HOST_OS),Linux)
+    ifeq ($(DAPLINK_GCC_HOST_ARCH),x86_64)
+        DAPLINK_GCC_ARCHIVE ?= gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)-x86_64-linux.tar.bz2
+    else ifeq ($(DAPLINK_GCC_HOST_ARCH),aarch64)
+        DAPLINK_GCC_ARCHIVE ?= gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)-aarch64-linux.tar.bz2
+    endif
+else ifeq ($(DAPLINK_GCC_HOST_OS),Darwin)
+    ifeq ($(DAPLINK_GCC_HOST_ARCH),x86_64)
+        DAPLINK_GCC_ARCHIVE ?= gcc-arm-none-eabi-$(DAPLINK_GCC_VERSION)-mac.tar.bz2
+    endif
+endif
+DAPLINK_GCC_URL ?= https://developer.arm.com/-/media/Files/downloads/gnu-rm/$(DAPLINK_GCC_VERSION)/$(DAPLINK_GCC_ARCHIVE)

From e8e001f6b50768642b053bc47a9c869b5c252da4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= <sebastien@nedjar.com>
Date: Mon, 13 Apr 2026 06:36:32 +0200
Subject: [PATCH 6/6] fix(daplink_bridge): Order venv sentinel after DAPLink
 clone.

On a fresh checkout, $(DAPLINK_DIR)/venv/.installed depended on
requirements.txt without any rule to produce it before the clone, so make
would fail with "No rule to make target requirements.txt" (especially under
parallel builds). Add an order-only prerequisite on $(DAPLINK_DIR) so the
clone always runs first and the file exists when make resolves the sentinel.
---
 Makefile | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index f844b967..deccc2fc 100644
--- a/Makefile
+++ b/Makefile
@@ -229,8 +229,10 @@ $(DAPLINK_GCC_DIR)/bin/arm-none-eabi-gcc:
 	rm -f $(BUILD_DIR)/gcc-arm-none-eabi.tar.bz2
 
 # Sentinel: re-runs pip install whenever DAPLink's requirements.txt changes
-# (e.g. after `make daplink-update`).
-$(DAPLINK_DIR)/venv/.installed: $(DAPLINK_DIR)/requirements.txt
+# (e.g. after `make daplink-update`). The order-only prerequisite on
+# $(DAPLINK_DIR) guarantees the clone happens first on a fresh checkout, so
+# requirements.txt exists by the time make checks it.
+$(DAPLINK_DIR)/venv/.installed: $(DAPLINK_DIR)/requirements.txt | $(DAPLINK_DIR)
 	@echo "Setting up DAPLink Python virtualenv..."
 	@if [ ! -x "$(DAPLINK_DIR)/venv/bin/python" ]; then \
 		$(PYTHON) -m venv $(DAPLINK_DIR)/venv; \