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.
Hardware target
Section titled “Hardware target”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.
DUT compatibility
Section titled “DUT compatibility”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.
Subsystems
Section titled “Subsystems”On-pod SWD debugger [validated]
Section titled “On-pod SWD debugger [validated]”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).
Flashing a DUT over Wi-Fi [validated]
Section titled “Flashing a DUT over Wi-Fi [validated]”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).
GDB through the pod [validated]
Section titled “GDB through the pod [validated]”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).
Logic analyser [validated]
Section titled “Logic analyser [validated]”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.
DUT-facing peripherals [validated]
Section titled “DUT-facing peripherals [validated]”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.
USB/IP DUT export [validated]
Section titled “USB/IP DUT export [validated]”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.
Networking and discovery [validated]
Section titled “Networking and discovery [validated]”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.
Management REPL over Wi-Fi [validated]
Section titled “Management REPL over Wi-Fi [validated]”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.
Local benches (no pod) [validated]
Section titled “Local benches (no pod) [validated]”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.
pod pack fetch Keil STM32H5xx_DFPpod local add nucleo-h5 --family STM32H563ZITx --from-mpy-dev nucleo-h5 \ --flash-base 0x08000000 --flash-size 0x200000pod dut flash nucleo-h5 firmware.elfpod bench uart nucleo-h5 --duration 5pod route nucleo-h5 instruments pod --pod lab1 # optional: borrow a pod's GPIO / ADC / logic analyserLimits:
- Flash algorithms are the pack default only. pyOCD can’t select a named
algorithm, so
dut_flash/dut_eraserefuse 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;
forcebypasses it. - Borrowed logic capture on a bench is not hardware-validated.
MCP surface
Section titled “MCP surface”Transport is stdio via the pod-mcp console script that ships with the host
tooling. An agent adds it with, for example:
claude mcp add pod -- pod-mcpThe 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=trueun-sticks a DUT latched in raw mode first) returns a session id, whichsession_send(stdin, or Ctrl-C / Ctrl-B / Ctrl-D viacontrol=),session_read(tail by cursor) andsession_closethen take.dut_execis the one-shot: it runs over an open session when there is one, otherwise over a fresh attach, and reports which route asvia. 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 whenvalueis given),dut_mem(reads inline or toout_path, writes whendatais 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, anddut_linkwithaction=status|up|down|reprobe.statusis a pure read;upbrings the pod USB host + usbip server up and attaches;reproberecovers 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 viabus=, withaction=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.
Quickstart
Section titled “Quickstart”- Flash the pod firmware onto a Pico 2 W and set Wi-Fi credentials in
config.py(templateconfig.example.py). Two paths: for a first install, hold BOOTSEL, plug in the board, and drag the build’sfirmware.uf2onto theRPI-RP2drive (no probe needed); to reflash a live pod safely, usemake flash(probe-based, via OpenOCD with both cores halted). - Wire the DUT to the pod. At minimum, SWD: pod GP14 to SWDIO, GP15 to SWCLK, and a common ground. See the pinout below.
- Install the host tooling from
src/host,uv tool install --editable .(orpip install -e ./src/host). This installs thepodCLI and thepod-mcpserver and pulls theampremotefork from git. Install it editable, so thepodon your PATH follows the checkout. - Find and register the pod:
pod discover, thenpod register <label> --address <ip>(use the discovered address; stores the pod’s handles + identity fingerprint under the label).pod info <label>confirms it. - Drive the DUT:
pod dut flash <label> firmware.bin,pod dut reset <label>(add--mode haltto 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). - 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
mbmto add the in-treemachine-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, hostnameannealage-pod.local. - Host tooling: Python
podCLI +Podclient +pod-mcpMCP server, talking to the pod overampremote(a git-pinned async fork ofmpremote) and raw TCP for the binary streams.
Pico 2 W wiring / pinout
Section titled “Pico 2 W wiring / pinout”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.
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 |
Carrier board
Section titled “Carrier board”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.
Connect your agent
Section titled “Connect your agent”Annealage Pod speaks MCP over stdio. Register the pod-mcp console script as
an MCP server:
claude mcp add pod -- pod-mcpWith 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.
Licence
Section titled “Licence”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.