simulator-automation

EvenHub Simulator Automation

The simulator exposes an HTTP API on localhost when launched with --automation-port <PORT>.

evenhub-simulator https://my-app.example.com --automation-port 9898

Base URL: http://127.0.0.1:<PORT>

API Reference

Health check

GET /api/ping
→ "pong"

Glasses screenshot

Returns the current LVGL framebuffer as image/png (576×288, RGBA).

GET /api/screenshot/glasses
→ image/png binary (RGBA)

RGBA format — critical for image analysis:

• Background pixels: (R=0, G=255, B=0, A=0) — transparent (alpha = 0)
• Lit/text pixels: (R=0, G=255, B=0, A=255) — opaque (alpha = 255)

Always work in RGBA mode. Do NOT convert to RGB — it drops the alpha channel and makes background pixels indistinguishable from text pixels (both appear as pure green).

from PIL import

Webview screenshot

Captures the main browser webview using html2canvas. Returns image/png. May take a few seconds; times out after 10s.

Console logs

Returns captured console.* output, uncaught exceptions, unhandled promise rejections, and failed fetch calls from the main webview.

Each entry:

Prefixes for non-console sources:

• [uncaught] ... — uncaught exception
• [unhandledrejection] ... — unhandled promise rejection
• [fetch] ... — failed fetch (non-ok status or network error)

Poll for new entries only:

since_id must be a non-negative integer. Passing a negative value (e.g. -1) causes the server to return an error, not an empty list. For the first poll, omit the parameter entirely to retrieve all current entries, then track last_id from the response:

Clear the buffer:

Timing caution: Startup logs (e.g. a "ready" signal) are emitted once and lost if you clear the buffer before reading them. Pattern: poll for the ready signal first, then clear if needed.

Glasses input

Send a touchpad action to the glasses display.

Response: { "ok": true }

Actions map to the glasses touchpad:

• up / down — scroll through list items or text
• click — select the current item
• double_click — triggers a system-level double-click event (typically "back" or "dismiss")

Automation workflow

1. Verify the server is running: GET /api/ping
2. Poll for app ready (without clearing console first): look for a known log message.
3. Observe: Use /api/screenshot/glasses (RGBA) or /api/console to check state.
4. Act: Send input via POST /api/input. After each action, wait briefly (~300ms) then confirm state changed.
5. Iterate: Use since_id when polling console to avoid re-reading old entries.

Tips

• The glasses display is 576×288 pixels, monochrome green. Screenshots are RGBA PNGs.
• Input only works when the app has created an active event container. If no container is active, input is silently ignored.
• double_click is typically used to go back or dismiss the current view.
• Allow 4+ seconds after launching the simulator before polling — SDK init and createStartUpPageContainer take time.

Task

$ARGUMENTS