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 (private use)
Section titled “Canvas (private use)”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.
From PyPI
Section titled “From PyPI”Install the host-side Studio launcher with pip:
pip install annealage-canvasOr with uv:
uv pip install annealage-canvasThis 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:
annealage-canvas-studio --harness http://localhost:5050Running the harness from source
Section titled “Running the harness from source”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:
git clone https://github.com/Annealage/canvascd annealage-canvasmake submodules runmake 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=:
make run APP=path/to/myapp.pyYour file needs a build_ui() function, and that is the only contract.
Connect an agent
Section titled “Connect an agent”The harness exposes an MCP server over Streamable HTTP at /mcp on port 5050.
Register it with any MCP client; for Claude Code:
claude mcp add annealage-canvas --transport http http://localhost:5050/mcpOnce 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.
Set up Pod
Section titled “Set up Pod”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.
Prerequisites
Section titled “Prerequisites”- 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
podtooling, 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.
Flash the pod firmware
Section titled “Flash the pod firmware”git clone https://github.com/Annealage/podcd 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:
make flashInstall the host tooling
Section titled “Install the host tooling”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:
cd src/hostuv 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.
On the network
Section titled “On the network”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:
pod discoverpod register bench-a --address <ip>pod dut flash bench-a firmware.binpod dut gdb bench-a # prints a target line for arm-none-eabi-gdbFor an agent, add the stdio MCP server:
claude mcp add pod -- pod-mcpInstall Mesh
Section titled “Install Mesh”Mesh is on PyPI as annealage-mesh and needs Python 3.10+. With uv there’s
nothing to install first:
uvx annealage-mesh ./path/to/partOr 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:
apt install bubblewrap socatMesh 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.
Next steps
Section titled “Next steps”- Canvas (private use): the GUI loop, in detail.
- Set up Pod: the hardware-in-the-loop rig, in detail.
- Mesh: the printed-parts loop, in detail.
- Overview: connect an agent and run the iteration loop.