ESP-Brookesia

• 中文版本

Overview

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.

Main Architecture Layers

• 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.

Main Architecture Features

• 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.

ESP-Brookesia Versioning

From v0.7, ESP-Brookesia is componentized. Projects are recommended to obtain required components through the component registry. The conventions are:

1. Components evolve independently but share the same major.minor version and depend on the same ESP-IDF release.
2. The release branch maintains historical stable versions and only fixes bugs and security issues.
3. 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

Documentation

• 中文：https://docs.espressif.com/projects/esp-brookesia/zh_CN
• English: https://docs.espressif.com/projects/esp-brookesia/en

Quick Reference

• Getting Started
• Utils Components
• Hardware Components
• Service Components
• GUI Components
• Runtime Components
• System Components
• App Components

Component List

Utils Components

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

Hardware Components (HAL)

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.

Service Components

Service Framework

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

Network Services

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

Media Services

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

System Services

Component	Description	Version
brookesia_service_storage	Storage service providing namespace-based key-value storage management
brookesia_service_device	Device service providing app-layer access to device control, status query, and protocol interfaces

Agent and Expression Services

Component	Description	Version
brookesia_agent_manager	Agent manager providing AI agent lifecycle, state machine, and unified operation interfaces
brookesia_agent_coze	Coze agent adapter providing Coze API integration, WebSocket communication, and agent management
brookesia_agent_openai	OpenAI agent adapter providing OpenAI API integration and agent management
brookesia_agent_xiaozhi	XiaoZhi agent adapter providing XiaoZhi API integration
brookesia_expression_emote	AI emote and animation management for visual feedback in anthropomorphic interactions

Emulation Services

Component	Description	Version
brookesia_emulation_nes	NES emulation service integrating display, audio, storage, and gamepad control

GUI Components (GUI)

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

Runtime Components (Runtime)

Component	Description	Version
brookesia_runtime_manager	Runtime manager for dynamic app packages, runtime backend registration, and app context management
brookesia_runtime_elf	ELF runtime backend
brookesia_runtime_js	JavaScript runtime backend
brookesia_runtime_lua	Lua runtime backend
brookesia_runtime_wasm	WebAssembly runtime backend

System and App Components (System & App)

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

Getting the Repository

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

Contribution Guidelines

We currently welcome contributions in the following areas:

• Fixing bugs
• Adding support for new development boards to brookesia_hal_boards

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.

Additional Resources

• Latest documentation: https://docs.espressif.com/projects/esp-brookesia/en, built from the docs directory of this repository;
• ESP-IDF Programming Guide: https://docs.espressif.com/projects/esp-idf/en;
• ESP-Brookesia components can be found on ESP Component Registry;
• Visit the esp32.com forum to ask questions and explore community resources;
• If you find a bug or need a new feature, please check GitHub Issues first to avoid duplicate submissions;