Skip to content

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.

  • 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.

The harness is MicroPython with the LVGL bindings; it runs from the source tree in a container, not from a pip install:

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

Start the harness against your app file. The only contract is that the file defines a build_ui() function:

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

A 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.

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.

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:

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

The 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) → screenshot

For the full tool surface, addressing an embedded target, and the read-class/write-class split while the harness is paused, see Connect an agent.