Skip to content

Annealage Pod

Annealage Pod is a Wi-Fi hardware-in-the-loop test rig. It flashes, debugs, resets and exercises a device-under-test (DUT) over the network. The debugger runs on the pod itself, in MicroPython: PIO-driven SWD, an ADIv5 DP/AP/MEM-AP stack, a Cortex-M control layer, a flash loader and a GDB server. There is no wired host PC and no separate debug probe in the loop. A host pod CLI, Python client and MCP server are the control plane, so an AI agent or an engineer drives the same iteration loop over Wi-Fi.

Available now. Open source under AGPL-3.0-only.

Annealage Pod runs on an off-the-shelf Raspberry Pi Pico 2 W (RP2350, CYW43 Wi-Fi). The bare Pico 2 W is wired to the DUT with jumper wires. The native USB controller is the DUT host port; pod management rides Wi-Fi.

Per-DUT-family status of the SWD debug/flash path. The on-pod debugger speaks SWD to ARM Cortex-M targets only. Any Cortex-M with a CMSIS pack is reachable in principle through the generic CMSIS-FLM runner (the host supplies the flash algorithm from the target’s CMSIS Device Family Pack, resolved from a local cache or downloaded from the vendor index on demand via dut_flm), but a family is listed validated only after the operations were exercised on that silicon.

DUT family Status Flash path Validated operations Known limits
nRF52840 validated generic CMSIS-FLM (validated) SWD debug (halt/resume/reset, FPB breakpoints, DWT watchpoints), GDB through the pod, register/memory peek-poke, flash + verify over Wi-Fi, USB/IP CDC forward USB/IP forward validated for the CDC class only; bulk/MSC unproven
i.MX RT1052 (Seeed Arch Mix) validated (flash) generic CMSIS-FLM, NXP pack’s QuadSPI algorithm (validated) SWD identify, sector erase + program + read-back CRC verify of external QSPI flash over Wi-Fi, bulk memory read, reset back into the DUT’s own firmware Mass erase, ELF flash and GDB not exercised on this board; the board’s flash is not the pack default, so its DUT entry declares flash_algorithm
STM32 pending generic CMSIS-FLM none yet (no STM32 DUT wired to a pod) FLM generality on real STM32 silicon is unproven; needs per-target algo extraction plus validation on that silicon
RP2350 as DUT pending RP-native bootrom (not built); CMSIS-FLM in principle none yet (no RP DUT wired) needs SWD multidrop (dormant + TARGETSEL) bring-up; an interrupted SWD flash can wedge the RP2350’s QSPI/XIP state, recoverable only by a power cycle

Non-Cortex-M DUTs (ESP32-class and similar) are out of scope for the SWD debug/flash path; they remain reachable over USB/IP, GPIO/ADC, and the DUT-facing peripherals.

The pod speaks SWD over a PIO state machine (pod GP14 = SWDIO, GP15 = SWCLK) at 9.375 MHz, with an ADIv5 DebugPort / MEM-AP stack and a Cortex-M control layer: halt, resume, reset-and-halt, single-step, core-register and memory access, fault-cause readout, FPB hardware breakpoints, and DWT data watchpoints (write/read/access, reachable over GDB). Validated against an nRF52840 (DPIDR 0x2BA01477, 100/100 clean transfers).

A DUT image streams straight into pod RAM over TCP and is programmed chunk-by-chunk over SWD with verify; it never touches a pod filesystem. Flashing runs a generic CMSIS-FLM runner that executes a standard CMSIS pack flash algorithm in the target’s own SRAM, so any chip with a CMSIS pack is reachable in principle (validated end-to-end on nRF52840 and, for QSPI flash, i.MX RT1052).

A host-side translator presents a standard GDB remote-serial endpoint and bridges to a small binary DAP RPC server on the pod. A stock arm-none-eabi-gdb connects over Wi-Fi and gets reset-halt, register and memory read/write, a hardware breakpoint hit, a data-watchpoint hit, backtrace, single-step, continue and re-hit, and a clean detach. The pod holds no GDB protocol state; the RSP semantics live host-side.

Direct register / memory access [validated]

Section titled “Direct register / memory access [validated]”

Single-shot SWD peek-poke without a full GDB session: read/write core registers (core must be halted) and read/write target memory (live MEM-AP). Flash and the Cortex-M code region are write-protected by policy. Validated on an nRF52840 (halt, read pc/sp/xpsr, RAM read plus write/read-back/restore).

A PIO state machine samples up to 32 contiguous DUT GPIOs into a DMA RAM ring with an optional edge/level trigger, streams the capture to the host, and decodes to VCD. Validated end-to-end including the live Wi-Fi round-trip and a two-channel 50/25 kHz decode. Runs on PIO0; coexists with SWD (PIO1) and Wi-Fi (PIO2) simultaneously.

The pod presents hardware peripherals to a DUT-as-controller: a hardware I2C target (a register-file responder on I2C1, with address-match/ACK/clock-stretch in silicon), a PIO SPI target (the pod is the SPI peripheral; stream/counter and register-file personalities, SPI modes 0–3, DMA-driven so no MicroPython in the per-byte path, byte-exact from 125 kHz to 8 MHz against the test controller), plus GPIO drive/read and ADC sampling. Validated against an nRF52840 controller. This is a thin pass-through over MicroPython’s machine module.

The pod’s native USB port hosts the DUT, and an in-tree C USB/IP server (port 3240) exports it over Wi-Fi so a host can usbip attach and bind the DUT with a normal class driver. Device enumeration, attach, and a full forwarded CDC REPL session (usbip attach, then mpremote connect over the attached tty) are validated on an nRF52840, across repeated attach / round-trip / detach cycles, including sustained churn (100 cycles of attach → forwarded round-trip → detach at 0% Wi-Fi packet loss).

Host-OS scope: usbip attach needs a kernel-side USB/IP client, in practice Linux (vhci_hcd). Windows via usbip-win is best-effort and untested with the pod; macOS has no client. Every other pod capability (flash, GDB, peek-poke, REPL, logic analyser, peripherals, CLI/MCP) is plain TCP/Python and host-OS-agnostic.

The pod advertises a browsable mDNS service _annealage-pod._tcp (annealage-pod.local) with TXT records carrying its ports and identity. All pod TCP listeners are dual-stack (IPv4 + IPv6). The host resolves a pod IPv6-first (self-authenticating via EUI-64), falls back to a fingerprint-checked IPv4, then re-resolves via mDNS; it refuses to act on a fingerprint mismatch, so it cannot flash or reset the wrong board after a DHCP change.

The only management channel on a deployed pod is a Wi-Fi socket REPL (one client at a time; a second connect is refused without evicting the active one). The host tooling adds a persistent, auto-reconnecting streaming session: it tees DUT/pod stdout to a log file and the console, accepts async stdin, survives drops and reboots with backoff, and can chain setup (soft-reset, file copy, exec, mount) before connecting. A backup UART REPL on GP0/GP1 survives the native-USB switch to host mode.

Dev boards with a built-in programmer (validated on a NUCLEO-H563ZI with its ST-LINK) can be driven through the same pod dut verbs and dut_* MCP tools without a pod. pyOCD (a default dependency of the host tooling) drives the probe from the host, using targets and flash algorithms from the shared CMSIS pack cache (pod pack list|fetch|path).

Each channel of a registry entry has a route: debug (pod or pyocd), uart (pod or a host tty), usb (pod, pod-host or agent-direct), and instruments (pod, optionally another registered pod’s label, or none). A channel with no route uses the pod. A bench can stream its UART from a host tty, run dut_exec over its own USB serial port, and borrow a registered pod’s GPIO, ADC and logic analyser.

Terminal window
pod pack fetch Keil STM32H5xx_DFP
pod local add nucleo-h5 --family STM32H563ZITx --from-mpy-dev nucleo-h5 \
--flash-base 0x08000000 --flash-size 0x200000
pod dut flash nucleo-h5 firmware.elf
pod bench uart nucleo-h5 --duration 5
pod route nucleo-h5 instruments pod --pod lab1 # optional: borrow a pod's GPIO / ADC / logic analyser

Limits:

  • Flash algorithms are the pack default only. pyOCD can’t select a named algorithm, so dut_flash / dut_erase refuse an entry that declares one; boards that need a named algorithm stay on a pod.
  • An ST-LINK resets the target when its session closes, so a halt holds across MCP calls but not across separate CLI invocations.
  • Pod-side verbs (pod exec, pod mount) refuse an entry with no pod.
  • Host-attached probes and ttys take a host-local lock that names the holder; force bypasses it.
  • Borrowed logic capture on a bench is not hardware-validated.

Transport is stdio via the pod-mcp console script that ships with the host tooling. An agent adds it with, for example:

Terminal window
claude mcp add pod -- pod-mcp

The server wraps the pod client and exposes 28 tools in subject-first groups, named so a tool and its CLI invocation are derivable from each other (dut_flash is pod dut flash, bench_la is pod bench la). The dut_* and bench_* tools accept local-bench entries as well as pods.

  • pod_: the pod as a managed device: pod_discover, pod_register, pod_info, pod_exec (run code on the pod’s own interpreter), pod_mount (one-shot; unmounts on return), pod_open (persistent session on the pod’s socket REPL; holds the pod’s single REPL slot for its lifetime).
  • Sessions: the DUT’s own REPL: dut_open (persistent, auto-reconnecting session on the DUT’s CDC tty; brings the USB/IP link up itself when given no device; recover=true un-sticks a DUT latched in raw mode first) returns a session id, which session_send (stdin, or Ctrl-C / Ctrl-B / Ctrl-D via control=), session_read (tail by cursor) and session_close then take. dut_exec is the one-shot: it runs over an open session when there is one, otherwise over a fresh attach, and reports which route as via.
  • dut_ debug over SWD (requires the DUT wired + powered): dut_identify (probe and reconcile the wired DUT’s SWD identity), dut_halt, dut_resume, dut_reg (reads, or writes when value is given), dut_mem (reads inline or to out_path, writes when data is given), dut_gdb. The register tools additionally require a halted core.
  • dut_ flash and link: dut_flash, dut_erase, dut_flm (report or install the CMSIS flash algorithm, including fetching one from the vendor index on demand), dut_reset, and dut_link with action=status|up|down|reprobe. status is a pure read; up brings the pod USB host + usbip server up and attaches; reprobe recovers a DUT the pod is not exporting without a cold cycle.
  • bench_: instruments pointed at the DUT: bench_gpio, bench_adc, bench_la, bench_device (present the pod as an I2C or SPI device on the DUT’s bus via bus=, with action=up|status|down), bench_device_regs (that device’s register file), bench_uart (read-only tail of the DUT UART). The SPI device and the logic analyser share PIO0 and run one at a time.

Read vs write. Read/query tools: pod_discover, pod_info, dut_identify, session_read, bench_adc, bench_uart, and dut_link(action="status"). State-mutating tools: dut_flash, dut_erase, dut_reset, pod_mount, bench_gpio (drive), bench_device, bench_device_regs, and dut_link with up/down/reprobe. dut_reg and dut_mem read or write depending on whether a value is supplied; dut_flm reports with no options and installs given any. To un-stick a silent forwarded DUT REPL, dut_open(recover=true) is the first, non-destructive thing to try before dut_reset.

  1. Flash the pod firmware onto a Pico 2 W and set Wi-Fi credentials in config.py (template config.example.py). Two paths: for a first install, hold BOOTSEL, plug in the board, and drag the build’s firmware.uf2 onto the RPI-RP2 drive (no probe needed); to reflash a live pod safely, use make flash (probe-based, via OpenOCD with both cores halted).
  2. Wire the DUT to the pod. At minimum, SWD: pod GP14 to SWDIO, GP15 to SWCLK, and a common ground. See the pinout below.
  3. Install the host tooling from src/host, uv tool install --editable . (or pip install -e ./src/host). This installs the pod CLI and the pod-mcp server and pulls the ampremote fork from git. Install it editable, so the pod on your PATH follows the checkout.
  4. Find and register the pod: pod discover, then pod register <label> --address <ip> (use the discovered address; stores the pod’s handles + identity fingerprint under the label). pod info <label> confirms it.
  5. Drive the DUT: pod dut flash <label> firmware.bin, pod dut reset <label> (add --mode halt to catch the reset vector), pod dut gdb <label> (starts an RSP listener for a stock gdb; FPB breakpoints and DWT data watchpoints both work), pod bench la <label> --pins 16-19 --out cap.vcd, pod dut open <label> (live session on the DUT’s REPL).
  6. For an agent: claude mcp add pod -- pod-mcp, then the 28 tools above are available over Wi-Fi.

Ports in use:

Port Service
8266 socket REPL
3240 USB/IP
3335 GDB / DAP RPC
3333 flash-in
3334 memory-out
3336 logic-analyser-out
  • Board: Raspberry Pi Pico 2 W (RP2350, CYW43 Wi-Fi).
  • Firmware: MicroPython (rp2 port), composed with mbm to add the in-tree machine-usbhost, network-mdns, and a no-Werror TinyUSB host.
  • Debug stack: pure MicroPython (annealage_pod.debug): PIO SWD, ADIv5 DP/AP/MEM-AP, Cortex-M, FPB, a generic CMSIS-FLM runner, and a binary DAP RPC server with a host-side GDB RSP translator.
  • USB/IP: an in-tree C module (usbip) implemented as an lwIP-RAW callback state machine with static buffer pools (no libc malloc on the network path), forwarding raw URBs; a TinyUSB host backend (usbhost) runs the DUT enumeration. The pod is a raw forwarder and runs no USB class drivers of its own.
  • Discovery: native lwIP mDNS responder; service _annealage-pod._tcp, hostname annealage-pod.local.
  • Host tooling: Python pod CLI + Pod client + pod-mcp MCP server, talking to the pod over ampremote (a git-pinned async fork of mpremote) and raw TCP for the binary streams.

3.3 V logic only (RP2350 GPIOs are not 5 V tolerant); a common ground on every connection is mandatory; the ADC reference is 3.3 V. GP23/24/25/29 are internal CYW43 Wi-Fi pins and are not on the header. GP0/GP1 are reserved for the backup UART REPL.

Annealage Pod pinout: Pico 2 W with the pod’s DUT-facing assignments overlaid in gold, with a verified/suggested status key

The diagram shows the pod’s DUT-facing pin assignments over the Raspberry Pi Pico 2 W header, with a verified/suggested status key. The tables below carry the same assignments in text.

Validated interfaces (firmware-assigned and exercised on hardware):

DUT connection Pod side DUT side
SWD debug / flash GP14 SWDIO, GP15 SWCLK, GND SWDIO, SWCLK, GND
I2C (pod = target) GP10 SDA, GP11 SCL, GND SDA, SCL, GND
SPI (pod = target) GP16 MISO, GP17 CS, GP18 SCK, GP19 MOSI, GND MISO, CS, SCK, MOSI, GND
GPIO functional any free GP, GND pin under test
ADC measure GP26 / GP27 / GP28, GND 0–3.3 V analog node
Logic-analyser taps GP16–GP21 (default block), GND signals to observe
Backup pod console GP0 TX, GP1 RX (to a probe, not the DUT) n/a

Other pin assignments (firmware-assigned or placed on the header; not exercised on hardware):

DUT connection Pod side Status
DUT reset (nRST) GP13 assigned in code, not exercised on hardware
USB host (USB/IP) native USB connector cabling, VBUS and current limit are not specified here

Per-rail INA228 power telemetry, opto-isolated relays and DUT power switching belong to a purpose-built carrier board, which also wires the DUT interfaces. They are not on the bare Pico 2 W, which uses jumper wires to the DUT.

Annealage Pod speaks MCP over stdio. Register the pod-mcp console script as an MCP server:

Terminal window
claude mcp add pod -- pod-mcp

With the pod registered and a DUT wired, the agent runs the full hardware loop: flash the DUT over Wi-Fi, attach a stock gdb through the pod, capture logic to VCD, exercise peripherals and refine. It works the same way as the GUI loop in Canvas.

Annealage Pod is open source under AGPL-3.0-only: use it for anything, commercial included, and share your source if you distribute it or host a modified version for others. The firmware carries an extra linking permission for the cyw43-driver and BTstack in the built image. Hardware designs are CERN-OHL-S-2.0. A commercial licence covers shipping, embedding or hosting Pod without releasing your source; see Licensing.