Skip to content

Annealage Canvas

Annealage Canvas pairs a MicroPython LVGL harness with Canvas Studio, a browser-based editor and review surface. The harness runs standalone under SDL or embedded in firmware, serving a live framebuffer with browser-driven touch.

Studio adds a file tree and multi-file editor, managed OMP chat, approval-gated writes, pause controls, source conflict handling, and screenshot review. Review pins stay tied to the captured image, source revision, and runtime generation. Managed mode is an internal trusted-code tool, not an OS sandbox or public hosted service.

Canvas runs in two modes from one code path:

  • Standalone: the harness boots MicroPython with the LVGL bindings under SDL and serves the framebuffer over HTTP. No board required; it runs on your laptop.
  • Embedded: the same package freezes into your firmware project as a library and mounts its viewer and MCP endpoints onto the device’s own HTTP server, so the browser viewer and the MCP surface point at the real panel’s framebuffer over the network.

The contract for a user app is a single function:

import lvgl as lv
def build_ui():
scr = lv.screen_active()
label = lv.label(scr)
label.set_text("Hello LVGL")
label.center()

That is the only thing your file must expose. The harness owns the display, input, reload, and MCP server around it.

Canvas is in private use. Its product repository is private, so there is no public setup path for the harness. The annealage-canvas Python package provides the host-side Studio launcher; it does not include the MicroPython harness or provide a public managed service.

The rest of this page describes the current harness and MCP interface. The Studio page is a local interface for a running harness, not a signup or hosted service.

The harness can reload the active app file and redraw the canvas. In standalone soft-reload mode (--no-restart or ?soft=1), the in-process re-run closes in under 10ms on a normal laptop. Managed mode restarts the native MicroPython process so the new source loads cleanly. A reload can be triggered three ways:

  • Saving the file in any editor (or in Studio, the in-browser editor).
  • A POST /reload to the harness.
  • An agent calling set_source(content, reload=true) or the reload action over MCP.

Each reload increments a counter and records last_error, which is null on success or the exception text on failure. The agent reads those back rather than parsing a terminal:

get_source → edit → set_source(content, reload=true) → screenshot

A deep reload (reload(deep=true)) purges helper modules before re-running, so edits to imported modules take effect, not just the top-level app file.

Standalone Embedded
Display backend SDL, in Docker real MCU panel, served over HTTP
Where it runs your laptop the host firmware project, as a frozen library
Hardware needed none the target board
LVGL / MicroPython shipped in deps/ provided by the host project
Wiring make run host calls attach_to_app()

Embedded mode freezes the harness into a firmware project and mounts its viewer and MCP endpoints on the host’s existing HTTP server. The host calls attach_to_app() to wire display, touch, state, reload handling and the LVGL pump onto its app. The product repository is private, so the source setup instructions are not available publicly.

The harness exposes an MCP Streamable HTTP endpoint at /mcp in the same asyncio loop. In standalone or embedded mode, it has no authentication, so use it only on localhost or a trusted network. This is separate from managed Studio’s authenticated local MCP surface.

The harness surface is split into 8 core tools, always visible at tools/list, and a 23-action catalog discovered on demand. The split keeps the always-loaded tool schemas small: the model calls search_actions(query) to find a catalog action and its schema, then execute_action(name, params) to run it. Together the surface is 31 entries: the 8 core tools and the 23 catalog actions.

These eight are always present and cover the main loop.

Tool Args Returns Class
screenshot format?: "png"|"raw" PNG image or raw RGB565 bytes read
get_source none {path, content} read
set_source content, reload?=true {reload_count, last_error} write
tap x, y {ok: true} write
find_widget text?, type?, area? {bbox, type, properties} or null read
search_actions query, limit?=5 matching {name, description, inputSchema} read
execute_action name, params action-specific varies
get_pause_status none {paused, since, reason} read

screenshot calls lv.refr_now() first, so the frame reflects current widget state rather than a stale buffer. find_widget returns the bounding box; feed the centre of bbox to tap rather than hardcoding coordinates.

Discoverable via search_actions, invoked via execute_action(name, params). The class column reflects each action’s annotation hints; write-class actions refuse while the agent is paused.

Action Description Class
touch_down(x, y) Register a touch-down at a pixel coordinate. write
touch_move(x, y) Move the held touch point to new coordinates. write
touch_up() Release the active touch point. write
drag(x1, y1, x2, y2, steps?=10) Drag between two points for sliders, scroll, and swipes. write
type_text(text) Send a string to the focused widget as key events. write
key(code) Send one key event (ENTER, ESC, a character) to the focused widget. write
wait_ms(ms) Sleep, yielding to the LVGL pump so animations and timers run. read
reload(deep?=false) Reload the app without restarting the harness. write
load_app(path) Tear down the current app and load another by path. write
list_apps(directory?) List .py files in a directory that can be loaded. read
get_display_info() Width, height, colour format, and stride of the display. read
get_widget_tree(screen?="active") JSON tree of all widgets: type, bbox, text, value per node. read
get_last_error() Most recent reload-cycle error, or null. read
get_reload_count() Reload cycles completed since the harness started. read
get_harness_state() Snapshot: reload count, last error, harness error, app path. read
screenshot_raw() Raw RGB565-LE snapshot as a resource link; resolve via resources/read. read
set_perf_overlay(on?=true) Toggle the LVGL performance overlay. write
get_log_tail(n?=50) Last N lines of the harness log buffer. read
measure_redraw() Synthetic full-screen redraw benchmark; returns min/p50/p95/max render time (µs) and mean/worst fps. read
profile_widget_tree() Per-widget render cost via paired visible/hidden redraw sampling; returns a cost-annotated widget tree. read
profile_widget_style(path) Per-style-property render cost for one widget, by toggling each property to a neutral value. read
navigate_screen(index) Call the app’s navigate_to(index) to switch screens with an optional animated transition. write
exec_python(code) Run arbitrary Python in the harness; reserve for one-off introspection. write

The catalog above is the canonical 23 actions surfaced through search_actions. Deeper profiling detail lives in the skill references (file:///skill/references/), reached over MCP resources.

If you would rather browse than search, read the mcp://harness/actions resource once: it is a JSON array of every action’s name, description, and input schema.

A typical agent-driven edit cycle:

get_source # read the current app
set_source(content, reload=true) # write the edit, trigger reload
screenshot # confirm the redraw
find_widget(text="OK") # locate a target widget
tap(x, y) # drive its centre

Discovering and running a catalog action, here typing into a focused textarea:

{"name": "search_actions", "arguments": {"query": "keyboard", "limit": 3}}
{"name": "execute_action",
"arguments": {"name": "type_text", "params": {"text": "hello"}}}

Profiling a slow screen uses the performance actions documented in the skill references (measure_redraw, profile_widget_tree). Warm the cache first: call measure_redraw a few times before profile_widget_tree, as cold-cache costs run roughly 3× the warmed figures:

{"name": "measure_redraw", "arguments": {"iterations": 50}}
{"name": "profile_widget_tree", "arguments": {"max_depth": 3}}

The performance run reports min, p50, p95, and max redraw time in microseconds plus fps_mean and fps_worst, so the agent can compare layout cost across edits rather than guessing. Per-property costs from profile_widget_style are not additive: radius and border_width interact, so read each as the saving from neutralizing one property in isolation.