ESP-Brookesia is a full-stack development platform for AIoT and HMI products. It organizes hardware abstraction, service framework, runtimes, GUI, system framework, app components, and AI capabilities as ESP-IDF components so products can compose and reuse platform capabilities as needed.
Note
Brookesia is a genus of chameleons known for small form factors and strong adaptability. ESP-Brookesia uses this image to emphasize that the framework can adapt to different hardware forms, interaction surfaces, and product systems.
- Hardware Abstraction: hides platform and hardware differences, unifies device access, and supports ESP devices and PC simulation.
- Service Framework: unifies service registration, function calls, event publish/subscribe, and MCP / Agent capability connections.
- Runtime and GUI: supports multi-runtime apps and the JSON UI-driven GUI model.
- System Framework: provides the product-level system framework that integrates GUI, Runtime, services, and app lifecycle.
- App Ecosystem: covers third-party app supply, upload and publish, device-side distribution, and installation.
- Hardware Decoupling: HAL and PC simulation reduce the impact of hardware differences on upper-layer apps and systems.
- App Development Efficiency: service-based design, multi-runtime support, and declarative GUI improve app development and validation efficiency.
- Productization and Ecosystem: the system and app frameworks combine with the app-store mechanism to support scalable product delivery.
- AI-Assisted Development Loop: AI Workflow and PC Validation form a development validation loop. Developers review, tune, and supplement the result to generate a publishable app.
- Publishing and Distribution Flow: apps can move through Upload & Publish, App Store, and Device Runtime to complete publishing, discovery, download, installation, and execution.
From v0.7, ESP-Brookesia is componentized. Projects are recommended to obtain required components through the component registry. The conventions are:
- Components evolve independently but share the same
major.minor version and depend on the same ESP-IDF release.
- The
release branch maintains historical stable versions and only fixes bugs and security issues.
- The
master branch continuously integrates new features and may contain functionality that has not stabilized yet.
| ESP-Brookesia | ESP-IDF | Main changes | Status |
|---|
| master (v0.8) | ESP32-S31: 6.2
Others: >= 6.0, <= 6.2 | Componentized publishing expands to GUI, Runtime, System, App, and AI capabilities; adds PC simulation, JSON UI, multi-runtime support, and the standard System Super mainline | Active development |
| release/v0.7 | >= 5.5, <= 6.0 | Component manager support | Stable version, bug and security fixes only |
| release/v0.6 | >= 5.3, <= 5.5 | Preview system framework; ESP-VoCat firmware project | End of maintenance |
| Component | Description | Version |
|---|
| brookesia_lib_utils | Core utility library providing task scheduler, thread configuration, profilers, logging, state machines, plugins, and other foundational capabilities |  |
| brookesia_mcp_utils | MCP bridge library that registers Brookesia service functions or custom callbacks as MCP tools for LLM invocation |  |
| Component | Description | Version |
|---|
| brookesia_hal_interface | HAL foundation component defining the unified device/interface model, lifecycle management, and hardware interface abstractions |  |
| brookesia_hal_adaptor | ESP device board adaptation component that initializes real peripherals through esp_board_manager and registers HAL interface implementations |  |
| brookesia_hal_boards | ESP device board configuration component providing board peripheral topology, pins, driver parameters, and Kconfig defaults |  |
Note
PC simulation support is provided by hal/brookesia_hal_linux and hal/brookesia_hal_wasm in this repository for Linux host, CI, and WebAssembly/Web demo scenarios.
| Component | Description | Version |
|---|
| brookesia_service_manager | Service manager providing plugin lifecycle, function routing, event publish/subscribe, and local calls |  |
| brookesia_service_helper | Service helper library providing type-safe schemas, helper calls, and unified service access interfaces |  |
| brookesia_service_custom | Custom service extension template for product-specific capabilities based on the Brookesia service framework |  |
| Component | Description | Version |
|---|
| brookesia_service_http | HTTP service providing HTTP/HTTPS client requests, resource limits, and request lifecycle events |  |
| brookesia_service_sntp | SNTP service providing NTP server management, timezone settings, and automatic time synchronization |  |
| brookesia_service_wifi | Wi-Fi service providing state-machine management, AP scan, connection management, and SoftAP functionality |  |
| Component | Description | Version |
|---|
| brookesia_service_audio | Audio service providing playback, codec, volume control, and playback state management |  |
| brookesia_service_video | Video service supporting local capture encoding and compressed stream decoding to pixel formats |  |
| brookesia_service_display | Display service wrapping display input, gestures, and display-related system capabilities |  |
| Component | Description | Version |
|---|
| brookesia_emulation_nes | NES emulation service integrating display, audio, storage, and gamepad control |  |
| Component | Description | Version |
|---|
| brookesia_gui_interface | GUI interface layer defining JSON UI document model, runtime resources, action binding, and backend contracts |  |
| brookesia_gui_lvgl | LVGL backend mapping resolved GUI documents to LVGL objects and handling events, animations, and image resources |  |
| Component | Description | Version |
|---|
| brookesia_system_core | System core framework orchestrating app lifecycle, GUI, Runtime, services, storage, and permission boundaries |  |
| brookesia_system_super | Standard system for rectangular touch devices with Shell, launcher, overlay, status bar, and built-in resource flow |  |
| brookesia_app_files | Files app providing a device-side file browser entry |  |
| brookesia_app_settings | Settings app providing device and system configuration entry |  |
| brookesia_app_store | App Store component providing local and remote app package entries |  |
If you would like to contribute to ESP-Brookesia or build on the examples in this repository, you can get the master branch with the following command:
git clone https://github.com/espressif/esp-brookesia
We currently welcome contributions in the following areas:
For new component ideas, we recommend starting a discussion in GitHub Issues first so we can align on the use case, interface boundaries, and overall roadmap together. Once there is agreement on the direction, the follow-up contribution process is usually much smoother.
