Skip to content

Install

This page covers Pod and Mesh, which are available now, and Canvas setup for authorised users, since Canvas is in private use. Pod is firmware you flash onto a Raspberry Pi Pico 2 W, and Mesh is a Python package you run with uvx. Each is independent; neither requires the other.

For what each tool does and its full action list, see Canvas (private use), Set up Pod and Mesh.

Canvas is an in-process LVGL development harness for the MicroPython unix port. The following setup instructions are for authorised users only.

The published package is annealage-canvas.

Install the host-side Studio launcher with pip:

Terminal window
pip install annealage-canvas

Or with uv:

Terminal window
uv pip install annealage-canvas

This installs the annealage-canvas-studio console script: the browser editor that talks to a running harness. The Studio launcher binds to 127.0.0.1 and serves on port 5051 by default; point it at a harness with --harness:

Terminal window
annealage-canvas-studio --harness http://localhost:5050

The harness itself (MicroPython with the LVGL bindings, serving the live canvas and the MCP server on port 5050) runs from the source tree. You need Docker and GNU make:

Terminal window
git clone https://github.com/Annealage/canvas
cd annealage-canvas
make submodules run

make run builds and starts a container, then serves the harness at http://localhost:5050/. To run your own app instead of the bundled demo, pass APP=:

Terminal window
make run APP=path/to/myapp.py

Your file needs a build_ui() function, and that is the only contract.

The harness exposes an MCP server over Streamable HTTP at /mcp on port 5050. Register it with any MCP client; for Claude Code:

Terminal window
claude mcp add annealage-canvas --transport http http://localhost:5050/mcp

Once registered, the agent drives the same canvas you watch in the browser: screenshot, find_widget, set_source, and tap(x, y), among others. Read-class tools keep working while the agent is paused so it can still observe.

Pod is a Wi-Fi hardware-in-the-loop test rig that runs as MicroPython firmware on an off-the-shelf Raspberry Pi Pico 2 W (RP2350). You flash the pod firmware onto the board, then install the host tooling on your machine: the pod CLI, client, and the pod-mcp MCP server.

  • A Raspberry Pi Pico 2 W (RP2350, CYW43 Wi-Fi).
  • A way to program it once (an attached SWD probe for make flash, or BOOTSEL UF2).
  • Python on the host for the pod tooling, and jumper wires to the DUT (at minimum SWD: pod GP14→SWDIO, GP15→SWCLK, common ground).

The firmware is MicroPython on the rp2 port. The debug stack (PIO SWD, ADIv5, Cortex-M, flash loader, GDB server) is pure MicroPython; USB/IP is an in-tree C module.

Terminal window
git clone https://github.com/Annealage/pod
cd pod
# set Wi-Fi credentials in config.py (template config.example.py)

Two flash paths:

UF2 / BOOTSEL: recommended for a first install; no probe needed. The build produces firmware.uf2. Hold BOOTSEL, plug in the Pico 2 W, and drag firmware.uf2 onto the RPI-RP2 drive.

make flash: programs the pod over a wired CMSIS-DAP probe with both cores halted. Use this to reflash a live pod safely:

Terminal window
make flash

The host tooling is the annealage-pod-host package (v0.1.0). It provides the pod and pod-mcp console scripts and lives in the repo’s src/host. Install it from source, editable, so the pod on your PATH follows the checkout:

Terminal window
cd src/host
uv tool install --editable .

pip install -e ./src/host is equivalent. The ampremote dependency is a git-only fork, so installing needs network and git access.

Once flashed and joined to Wi-Fi, Pod announces itself over mDNS (_annealage-pod._tcp), IPv6-first. Discover and register it, then drive the DUT over the network:

Terminal window
pod discover
pod register bench-a --address <ip>
pod dut flash bench-a firmware.bin
pod dut gdb bench-a # prints a target line for arm-none-eabi-gdb

For an agent, add the stdio MCP server:

Terminal window
claude mcp add pod -- pod-mcp

Mesh is on PyPI as annealage-mesh and needs Python 3.10+. With uv there’s nothing to install first:

Terminal window
uvx annealage-mesh ./path/to/part

Or keep it as a tool with uv tool install annealage-mesh or pipx install annealage-mesh. On Linux, agent mode also needs bubblewrap and socat to contain the agent’s shell:

Terminal window
apt install bubblewrap socat

Mesh brings its own agent in the chat pane. The Claude backend uses the Claude Agent SDK, which bundles the Claude Code CLI (about 90 MB); the Codex and omp backends install separately. See Mesh for backends and the file contract for agents running elsewhere.