agentcube-sim

Local device twin for AgentCube Firmware and GeekMagic HelloCubic-class cubes (ESP8266 + ST7789 240×240).

Not a cycle-accurate ESP8266 emulator. It mirrors the device HTTP API, a virtual RGB565 framebuffer, and soft flash/FS limits so you can develop the admin UI and clients without a physical cube.

Features

• REST API compatible with GeekMagic Open Firmware / AgentCube (/api/v1/*)
• Drawing API (/api/v1/draw/*) for programmatic screen tests
• Virtual ST7789 240×240 screen (/screen, /api/sim/frame.png)
• Serves compact AgentCube admin UI from web/
• Simulated GIF store + OTA file drops under sim-data/
• Open API by default (optional bearer token)

Hardware profile

Item	Value
MCU	ESP8266 (esp12e) — simulated quotas only
Display	ST7789, 240×240, RGB565
Flash	4 MB (soft limit)
LittleFS	~2 MB partition (soft limit)
RAM	~80 KB heap (reported only)

Requirements

• Python 3.9+ (stdlib only; no pip packages)

Tests

python3 -m unittest tests.test_sim_api -v
# or
python3 tests/test_sim_api.py -v

In-process HTTP server: health, draw, batch, RGB565 frame blit, wifi, client lib smoke, optional auth.

Quick start

git clone git@github.com:a2u/agentcube-sim.git
cd agentcube-sim
python3 agentcube_sim.py

URL	Purpose
http://127.0.0.1:8765/	Admin UI
http://127.0.0.1:8765/screen	Virtual display
http://127.0.0.1:8765/api/sim/hw	Hardware / sim metadata JSON

Options

python3 agentcube_sim.py --host 127.0.0.1 --port 8765
python3 agentcube_sim.py --token secret   # require Authorization: Bearer secret
python3 agentcube_sim.py --web ./web      # custom admin static root
python3 agentcube_sim.py --data ./sim-data

Example: draw on the virtual screen

curl -sS -X POST http://127.0.0.1:8765/api/v1/draw/batch \
  -H 'Content-Type: application/json' \
  -d '{
    "commands": [
      {"type":"clear","color":"#112233"},
      {"type":"circle","x":120,"y":120,"r":40,"color":"#ff0066","fill":true},
      {"type":"text","x":40,"y":180,"text":"SIM OK","size":2,"color":"#00ffff"}
    ]
  }'
# then open /screen

Python client (MVP)

# from repo root (stdlib only)
python3 examples/demo_mvp.py
# or
PYTHONPATH=. python3 -c "from agentcube import Cube, Color; c=Cube(); c.show_message(['Hi'], [Color.CYAN])"

Package: agentcube/ — Cube, Color, Layout, scenes, frame_rgb565 for PC→screen.

Agent skill: skills/agentcube/SKILL.md

Protocol: HTTP or something else?

Use case	Recommendation
UI commands, text, shapes, batch	HTTP JSON (/api/v1/draw/*, /batch) — simple, matches HoloClawd, works with curl/agents
Still images / low-FPS frames from PC	HTTP binary POST /api/v1/draw/frame (RGB565 LE, optional region headers)
Soft video 15–30+ FPS	Later: WebSocket binary or raw TCP — less overhead than new HTTP request per frame; ESP8266 still limited by SPI + RAM (~115 KB/full frame)

MVP sticks to HTTP. Full-screen RGB565 @ few FPS is fine on sim; on real ESP prefer dirty rectangles and ≤10 FPS.

# full red frame (115200 bytes raw)
python3 -c "from agentcube import Cube; Cube().frame_solid(0xF800)"

What this is not

• Does not execute real ESP8266 firmware binaries
• Does not emulate SPI timing, Wi‑Fi radio, or true GIF decoding (play is a visual stub)
• C++ firmware on the physical cube still needs draw endpoints ported; sim already implements them

License

MIT (simulator + client tooling). AgentCube / GeekMagic firmware remain under their own licenses.