# ESP-Brookesia: a componentised AIoT platform for building touch products > ESP-Brookesia is Espressif's full-stack development platform for AIoT and human machine interface products, organised as ESP-IDF components for hardware, services, runtimes, GUI, system and app distribution. Since v0.7 it is delivered through the component registry rather than as a single library. **espressif/esp-brookesia** — ESP-Brookesia is a human-machine interaction development framework designed for AIoT devices. - Repository: https://github.com/espressif/esp-brookesia - Stars: 823 · Forks: 217 - Language: C++ - License: Apache-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/espressif-esp-brookesia ## A platform for AIoT products, not a widget library ESP-Brookesia is described as a full-stack development platform for AIoT and HMI products, and the word full-stack is doing real work in that sentence. It is not a UI toolkit you drop onto a screen, and it is not a driver. It is a set of layers that a product team assembles: hardware abstraction, a service framework, runtimes, a GUI, a system framework, app components, and AI capabilities. The problem it addresses is the one that hits anyone shipping a connected device with a screen. A display is the easy part. The hard parts are that the same app has to run on two different boards, that services need to be discoverable by other parts of the firmware, that third-party apps have to be installed and updated on a device in the field, and that an assistant on the device has to be able to call into those services. Each of those is a framework, and a product that needs several of them ends up writing several of them. Espressif packages all of it as ESP-IDF components, so a product composes the platform capabilities it needs rather than forking a monolithic SDK. The code is C++, the licence is Apache-2.0, and the source tree in the repository is organised along the same lines as the architecture, with app, gui, hal, runtime, service, system, tools and utils directories at the top level. ## Five layers, and what each one owns The architecture section of the documentation names the layers and what each is responsible for, which is the fastest way to understand the design. The hardware abstraction layer hides platform and hardware differences, unifies device access, and supports both ESP devices and PC simulation. Below it sits the service framework, which unifies service registration, function calls, event publish and subscribe, and the connections for MCP and Agent capabilities. The runtime and GUI layer supports multi-runtime apps and the JSON UI-driven GUI model, where the interface is described as data rather than as hand-written widget code. The system framework is the product-level piece that integrates GUI, runtime, services and app lifecycle into one system. And the app ecosystem layer covers third-party app supply, upload and publish, device-side distribution, and installation. That ordering is the interesting part. Services sit above the hardware and below everything else, so an app talks to services rather than to drivers, which is what makes the hardware decoupling and the AI integration possible at the same time. The JSON UI model is the other structural choice: a declarative interface description that a runtime renders, which is what lets the same app run on a different display or in a PC simulation without a rewrite. ## The component registry changed the versioning contract From v0.7, ESP-Brookesia is componentised, and the project recommends obtaining the components you need through the component registry. The versioning conventions that go with it are stated explicitly, and they are the part to read carefully before you pin anything. Components evolve independently but share the same major.minor version, and they depend on the same ESP-IDF release. That is a strong constraint: it means you cannot take a newer GUI component and pair it with an older service component, and it means a whole platform upgrade is a coordinated event rather than a per-component one. The branches divide along those lines too. The release branch keeps historical stable versions and only receives bug and security fixes, while the master branch continuously integrates new features and may contain functionality that has not stabilised yet. The documentation is blunt about the consequence: master is a moving target, and release is where production work belongs. For a team already building on ESP-IDF components, this is a familiar model. For a team that expected to vendor a single library, it is a change in how upgrades work, and one that has to be planned rather than absorbed. ## The branches are split by ESP-IDF version, not by feature The version table in the documentation is the practical part of the decision, because it maps branches to ESP-IDF releases. The master branch, which is at v0.8, covers ESP-IDF 6.2 for the ESP32-S31 and anything from 6.0 up to 6.2 for other targets. Its listed changes are the expansion of componentised publishing across GUI, runtime, system, app and AI capabilities, together with PC simulation, JSON UI, multi-runtime support, and the standard System Super mainline. Its status is listed as active development. The release/v0.7 branch covers ESP-IDF from 5.5 up to 6.0, and its listed change is component manager support, with the status described as a stable version receiving bug and security fixes only. The release/v0.6 branch covers 5.3 up to 5.5, introduced the preview system framework and the ESP-VoCat firmware project, and is marked as end of maintenance. So the choice of branch is a choice of ESP-IDF generation. A product on ESP-IDF 5.3 to 5.5 is looking at a branch the project itself marks as finished. A product on 5.5 to 6.0 sits on release/v0.7. A product able to move to 6.0 or later can work on master and accept that the framework under it is still moving. There is a wrinkle worth knowing. The GitHub releases for the repository are v0.4.0, v0.4.1 and v0.4.2, the last of them from 2024-12-23, while the branch structure has moved well past that line. The versioned releases and the componentised distribution are two different delivery mechanisms, and the component registry is the current one. ## PC simulation through hal_linux and hal_wasm The most useful practical feature in the tree is the PC simulation support, provided by hal/brookesia_hal_linux and hal/brookesia_hal_wasm in the repository, and the documentation states the scope plainly: Linux host, CI, and WebAssembly or web demo scenarios. This matters because of how the platform is developed. The architecture section describes an AI-assisted development loop in which AI Workflow and PC Validation form a development validation loop, where a developer reviews, tunes and supplements the result to generate a publishable app. Validating on a Linux host or in a browser is what makes that loop fast, because the iteration does not require flashing hardware. The WebAssembly target goes further and puts a demo in a browser tab, with the wasm component sitting behind the same HAL interface as the real device. The hardware components behind this are brookesia_hal_interface, which defines the unified device and interface model along with lifecycle management and hardware interface abstractions, brookesia_hal_adaptor, which initialises real ESP peripherals through esp_board_manager and registers the HAL implementations, and brookesia_hal_boards, which supplies board peripheral topology, pins, driver parameters and Kconfig defaults. The cost of that layering is the usual one: a board bring-up is a Kconfig and configuration exercise rather than a driver written from scratch, and you accept the abstraction to get the simulation in return. ## Services exposed as MCP tools, and an app store on the device The AI story in this platform is concrete rather than a wrapper around a model. brookesia_mcp_utils is a bridge library that registers Brookesia service functions or custom callbacks as MCP tools for LLM invocation. In other words, the service framework is the same surface an on-device assistant calls into, and the service layer already has registration, function calls and event publish and subscribe. The distribution story is the other half. The architecture features list a publishing and distribution flow in which apps move through Upload and Publish, the App Store, and the Device Runtime, covering publishing, discovery, download, installation and execution. The app ecosystem layer adds third-party app supply, upload and publish, device-side distribution and installation, and the productisation feature combines the system and app frameworks with that app store mechanism for scalable delivery. The repository backs this with a foundation library, brookesia_lib_utils, which provides the task scheduler, thread configuration, profilers, logging, state machines, plugins and other shared capabilities, and with examples organised by concern: an examples/agent directory, an examples/service directory and an examples/system directory, alongside an app directory in the tree itself. What is not visible in the repository is the server side of the app store. The publication flow is described from the device's point of view, and the documentation is hosted on the Espressif documentation site rather than in the repository, so the pieces you would need for a production deployment live outside this source tree. ## What the repository settles and what it does not The limitations of ESP-Brookesia are structural, and they are worth stating before anyone plans a product around it. The first is the ESP-IDF window. Master supports 6.0 to 6.2 only, release/v0.7 covers 5.5 to 6.0, and release/v0.6 covers 5.3 to 5.5 and is marked end of maintenance. A product that must ship on an older IDF is constrained to a branch that will receive bug and security fixes only, and the newest GUI, JSON UI, multi-runtime and AI work is not available to it. The second is the master branch itself, which the documentation warns may contain functionality that has not stabilised. Development on master is development on moving ground, and a product team that wants a stable base has to choose release/v0.7 and accept an older feature set. The third is the component coordination rule. Components evolve independently but share a major.minor version and the same ESP-IDF release, which keeps the platform consistent at the cost of making a platform upgrade a coordinated operation across every component you use. The alternative to all of this is to build the same layers yourself: a display abstraction, a service registry, an app installation mechanism and an assistant bridge, each of which you would own and each of which you would have to maintain for the life of the product. ESP-Brookesia trades that freedom for a framework that already agrees with Espressif's own toolchain, and the repository carries its own quality gates in the form of a pre-commit configuration, a flake8 setup, a codespell configuration, a copyright check configuration, pytest configuration, and both GitHub and GitLab CI definitions. ## Conclusion ESP-Brookesia fits a team building a touch product on ESP hardware that needs a display, an app store and an AI facing service layer rather than a single widget library, and it is the wrong choice for a project on ESP-IDF 5.x that wants the newest GUI and runtime work, because master only supports ESP-IDF 6.0 to 6.2 and release/v0.7 is the branch that covers 5.5 to 6.0. Verify first which ESP-IDF release your product targets against the version table, then confirm that the components you need are published on the component registry, since from v0.7 that registry is the documented way to obtain them. ## FAQ ### What is ESP-Brookesia and who is it for? It is Espressif's full-stack development platform for AIoT and human machine interface products, written in C++ and licensed under Apache-2.0. It is aimed at product teams building connected devices with a screen, an app distribution mechanism and a service layer an on-device assistant can call. ### How do I get the ESP-Brookesia components? From v0.7 the project is componentised and the recommendation is to obtain the required components through the ESP-IDF component registry. The components live under the espressif organisation, with names such as brookesia_lib_utils, brookesia_mcp_utils, brookesia_hal_interface, brookesia_hal_adaptor and brookesia_hal_boards. ### Which ESP-IDF version does ESP-Brookesia master support? The version table lists master at v0.8 supporting ESP-IDF 6.2 for the ESP32-S31 and versions from 6.0 up to 6.2 for other targets. release/v0.7 covers 5.5 up to 6.0, and release/v0.6 covers 5.3 up to 5.5 and is marked as end of maintenance. ### Can I develop ESP-Brookesia apps without hardware? Yes. PC simulation is provided by hal/brookesia_hal_linux and hal/brookesia_hal_wasm in the repository, for Linux host, CI and WebAssembly or web demo scenarios, which supports the PC Validation part of the development loop the documentation describes. ### How does ESP-Brookesia expose services to an LLM? The brookesia_mcp_utils component is a bridge library that registers Brookesia service functions or custom callbacks as MCP tools for LLM invocation, so the same service framework used by apps can be called by an on-device assistant. ## Sources - [espressif/esp-brookesia on GitHub](https://github.com/espressif/esp-brookesia) - [Issues](https://github.com/espressif/esp-brookesia/issues) - [License: Apache-2.0](https://github.com/espressif/esp-brookesia/blob/master/LICENSE) - [README](https://github.com/espressif/esp-brookesia/blob/master/README.md) - [Releases](https://github.com/espressif/esp-brookesia/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/espressif-esp-brookesia