Getting started
This walkthrough takes you from a clean machine to a running Annealage Canvas harness with the framebuffer viewer open in a browser and an agent attached over MCP. It covers Canvas only; for the hardware-in-the-loop rig, see Set up Pod, and for 3D-printable parts, Mesh.
Canvas is an in-process LVGL development harness for the MicroPython unix port. It runs your LVGL UI in real LVGL, serves the framebuffer over HTTP, and exposes the same canvas to an agent through an MCP server. The same code path runs standalone and when frozen into firmware, where it serves a real MCU’s framebuffer over HTTP.
Prerequisites
Section titled “Prerequisites”- Docker and GNU make: the harness builds and runs in a container.
- An MCP client to drive the loop: these instructions use Claude Code, but any client that speaks MCP Streamable HTTP works.
1. Get the harness
Section titled “1. Get the harness”The harness is MicroPython with the LVGL bindings; it runs from the source tree in a container, not from a pip install:
git clone https://github.com/Annealage/canvascd annealage-canvasmake submodules2. Run the harness
Section titled “2. Run the harness”Start the harness against your app file. The only contract is that the file
defines a build_ui() function:
make run APP=path/to/myapp.pyA minimal myapp.py:
import lvgl as lv
def build_ui(): scr = lv.screen_active() label = lv.label(scr) label.set_text("Hello LVGL") label.center()The harness boots on port 5050, runs build_ui(), and starts serving the
framebuffer. Run make run without APP= to boot the bundled widget_demo
instead: a tabview of the widgets you reach for most often.
3. Open the framebuffer viewer
Section titled “3. Open the framebuffer viewer”Open the viewer in a browser:
http://localhost:5050/You get the live canvas, a frame-rate readout, and a reload counter. Edit your
app file in any editor and save; the harness re-runs build_ui() and the canvas
redraws. The /reload path drives that re-run, and it closes in under
10ms on a normal laptop, so iterating on a layout feels closer to editing in
browser dev tools than to compiling firmware.
The viewer accepts touch directly: click and drag on the canvas and LVGL sees real input events, the same ones an agent sends through MCP.
4. Connect an agent over MCP
Section titled “4. Connect an agent over MCP”The harness exposes an MCP Streamable HTTP server at /mcp in the same process,
with no sidecar or stdio bridge. Register the running harness with Claude Code:
claude mcp add annealage-canvas --transport http http://localhost:5050/mcpThe agent now drives the same canvas you are looking at. The core surface is eight
tools: screenshot, get_source, set_source, tap, find_widget,
search_actions, execute_action and get_pause_status. The rest of the catalog
(drag, keyboard input, widget-tree profiling, redraw measurement) is reachable on
demand through search_actions plus execute_action. The typical edit loop:
get_source → edit → set_source(content, reload=true) → screenshotFor the full tool surface, addressing an embedded target, and the read-class/write-class split while the harness is paused, see Connect an agent.
Next steps
Section titled “Next steps”- Canvas (private use): what Canvas is and how it fits the GUI loop.
- Connect an agent: the full MCP tool surface and the agent-driven edit loop.
- Set up Pod: add hardware-in-the-loop test over Wi-Fi.