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.
What it is
Section titled “What it is”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.
Availability
Section titled “Availability”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 reload loop
Section titled “The reload loop”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 /reloadto the harness. - An agent calling
set_source(content, reload=true)or thereloadaction 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) → screenshotA 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 vs embedded
Section titled “Standalone vs embedded”| 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.
Connect an agent over MCP
Section titled “Connect an agent over MCP”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.
MCP action reference
Section titled “MCP action reference”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.
Core tools
Section titled “Core tools”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.
Catalog actions
Section titled “Catalog actions”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.
Usage examples
Section titled “Usage examples”A typical agent-driven edit cycle:
get_source # read the current appset_source(content, reload=true) # write the edit, trigger reloadscreenshot # confirm the redrawfind_widget(text="OK") # locate a target widgettap(x, y) # drive its centreDiscovering 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.