The dev loop
your ESP32
has been
missing

A reusable C component, a Python CLI, a reference firmware, and a host simulator — all in one repo. Drop into any ESP-IDF + LVGL project and turn `idf.py monitor` into a structured, AI-driveable loop.

Quickstart → View on GitHub
esp-harness logo
§ Pitch — 30 seconds

From clone to
your first scene
in three commands.

No board needed for the simulator. No PlatformIO. No Arduino IDE. Just ESP-IDF and a laptop. The scaffolding is opinionated; the outputs are structured; the AI loop is the default, not an afterthought.

~/code
# 1. install $ git clone github.com/Caldis/esp-harness $ pip install -e esp-harness/tools/esp-harness/ # 2. scaffold a project $ esp-harness new my-thing scaffolded my_thing at ./my-thing (source: vendor) # 3. build + flash + iterate $ cd my-thing && esp-harness build && esp-harness flash build OK in 13.8s · flashed 1.6 MB $ esp-harness manifest --json { toolkit_commands: [...17 cmds...], device: {...} }
§ Three onboarding paths

Pick the path
that matches
your goal.

▸ Use the library

For your own ESP-IDF + LVGL project

Scaffold a self-contained project with aurora-harness vendored in. Your code, your peripherals, our scaffolding.

esp-harness new my-thing
cd my-thing
esp-harness build
esp-harness flash
Read the component README →
▸ Run the demo

The Aurora reference firmware

20 scenes exercising every peripheral of the Waveshare ESP32-S3-Touch-AMOLED-2.16. The worked example.

cd examples/aurora/
esp-harness build && flash
esp-harness monitor --seconds 8
See the demo →
▸ Run the simulator

No hardware? Use the host build

5-second UI iterations on your laptop via SDL2 + LVGL. Visual regression on every PR.

cd examples/aurora/sim/
cmake -B build
cmake --build build
esp-harness sim diff
Try the sim →
§ Architecture

Three layers,
one discovery
surface.

Layer 1 — Toolkit (host Python CLI). Drives the device. Knows nothing firmware-specific; learns everything via the manifest at runtime.

Layer 2 — aurora-harness component (device C library). Console protocol + scene framework + UI overlays. Reusable, board-agnostic.

Layer 3 — Application (your firmware). Owns app_main, scenes, peripherals, business logic. Uses Layer 2 as scaffolding.

A single command — esp-harness manifest --json — flattens what every layer offers. If it's not in the manifest, it doesn't exist for the AI.

Full architecture doc →

Layer 1 · Toolkit tools/esp-harness/ (Python CLI) build · flash · monitor · sim · bench · doctor subprocess + JSON + serial Layer 2 · aurora-harness components/aurora-harness/ (reusable C component) console protocol · scene framework · toast / progress default ?stat / scene / tap / swipe / ?dump bsp_iface (lock/unlock only) consumer = your app Layer 3 · Application examples/<your-thing>/ (your firmware) app_main · scenes · peripherals · console cmds ← esp-harness manifest --json
§ Where we sit

What each tool
gives you, vs
what we add.

Stack Solves Doesn't solve
Raw ESP-IDF Build / flash / monitor. Mature, official, the substrate. AI dev loop, manifest, sim, structured console, bench, scene framework.
PlatformIO Build / flash / monitor with cross-platform abstraction. VS Code integration. Same as above — PIO is a fancier build wrapper, not an AI dev loop.
Arduino IDE One-button build / upload. Easy first touch. Mostly everything — Arduino abstracts the layer below where our value lives.
LVGL official sim Host LVGL build template, generic. The bridge from your firmware code to the sim. The scene framework. The harness.
esp-harness (this repo) All of the above's value-add, plus the AI dev loop. Targeted at ESP-IDF + LVGL specifically. Other build systems (PIO, Bazel, …). Non-LVGL UI frameworks. Other MCU families (yet).