# System Super Example
[中文版本](./README_CN.md)
This example demonstrates how to start a complete ESP-Brookesia System Super product shell. The default build integrates HAL, Display/Audio/Wi-Fi/HTTP/Storage/SNTP/Video/Device services, NES emulation, Coze and Xiaozhi agents, the GUI LVGL backend, the JavaScript runtime, and the built-in Settings, App Store, and Files apps.
## 📑 Table of Contents
- [System Super Example](#system-super-example)
- [📑 Table of Contents](#-table-of-contents)
- [✨ Features](#-features)
- [🚩 Getting Started](#-getting-started)
- [Hardware Requirements](#hardware-requirements)
- [Development Environment](#development-environment)
- [🔨 How to Use](#-how-to-use)
- [⚡ Build Performance](#-build-performance)
- [📊 Build Analysis](#-build-analysis)
- [🚀 Quick Start](#-quick-start)
- [🔍 Troubleshooting](#-troubleshooting)
- [💬 Technical Support and Feedback](#-technical-support-and-feedback)
## ✨ Features
- 🧭 **System shell experience**: Starts the System Super Shell with desktop background, status bar, App Launcher, and system overlay
- 📦 **Built-in app integration**: Preinstalls Settings, App Store, and Files to validate native app install, launch, and restore flows
- 🧩 **Framework integration**: Combines Service Manager, GUI LVGL, Runtime Manager, System Core/Super, and HAL board resources
- 🗂️ **Resource packaging**: Stages System Super resources, fonts, images, and the LittleFS partition through the build flow
## 🚩 Getting Started
### Hardware Requirements
This example provides configurations for the following development boards:
- `esp32_p4_function_ev` (P4 chip revision <3, including v1.3)
- `esp32_p4x_function_ev` (P4 chip revision ≥3)
- `esp32_s31_korvo1`
- `esp_mosaico_v1_0`
- `esp_mosaico_v1_2` (initial adaptation; partially validated, see the guide below)
Hardware resources are managed through the [brookesia_hal_boards](https://components.espressif.com/components/espressif/brookesia_hal_boards) component.
On ESP-Mosaico, expansion modules are optional and are not required to start System Super. Select the configuration matching the CoreBoard revision. See the [V1.0 adaptation guide](https://docs.espressif.com/projects/esp-brookesia/en/latest/hal/boards/espressif.html#hal-boards-espressif-mosaico) or [V1.2 adaptation guide](https://docs.espressif.com/projects/esp-brookesia/en/latest/hal/boards/espressif.html#hal-boards-espressif-mosaico-v1-2) for module support and limitations. V1.2 CDC console interaction has been verified, but automatic download disconnected the current sample without USB re-enumeration. The defaults set `CONFIG_BSP_USB_AUTO_DOWNLOAD=n` and `CONFIG_ESPTOOLPY_BEFORE_NORESET=y`; update both in an existing `sdkconfig`, and enter ROM download mode manually with BOOT before flashing. V1.2 startup reached `=== System Example Completed ===`; desktop display, basic touch interaction, and brightness-slider dragging were manually confirmed on the current sample. My Device information and nearby Wi-Fi access-point scanning were also confirmed; runtime logs show successful network time synchronization. The guide also records verified device initialization, NAND file operations and remounting, and 50 SC101IOT start/stop and frame-capture cycles. Audio quality, actual camera frame rate and image quality, and NAND file persistence across power loss remain pending. NAND FATFS is integrated through HAL/Storage Service; it is not yet selectable as an application installation location.
V1.2 defaults configure the mbedTLS/PSA SHA/AES used by HTTP/TLS to run in software (`CONFIG_MBEDTLS_HARDWARE_SHA=n`, `CONFIG_MBEDTLS_HARDWARE_AES=n`) for LCD, NAND, camera, and HTTPS coexistence; existing V1.2 `sdkconfig` files must also disable both options. Hardware tracing showed that App Store HTTPS activity retained the remaining AXI GDMA RX channel and prevented Camera from reopening. TLS and signature verification remain enabled, with potentially more CPU work. Direct hardware crypto calls remain possible; encrypted-media coexistence is unverified. The user manually confirmed normal Camera preview with the fixed firmware. A repeat after an actual application download and installation has not been separately recorded.
> [!TIP]
> On boards equipped with an SD Card slot, this example supports using the card as an external storage volume. Please insert the SD Card before powering on the board.
> When using the SD Card, "App Store" and other apps will default to scanning it for storage or specific file directories, so it is recommended to use it to expand the system storage space.
### Development Environment
Please refer to the following documentation:
- [ESP-Brookesia Programming Guide - Versioning](https://docs.espressif.com/projects/esp-brookesia/en/latest/getting_started.html#getting-started-versioning)
- [ESP-Brookesia Programming Guide - Development Environment Setup](https://docs.espressif.com/projects/esp-brookesia/en/latest/getting_started.html#getting-started-dev-environment)
## 🔨 How to Use
<a href="https://espressif.github.io/esp-brookesia/index.html">
<img alt="Try it with ESP Launchpad" src="https://dl.espressif.com/AE/esp-dev-kits/new_launchpad.png" width="400">
</a>
Please refer to [ESP-Brookesia Programming Guide - How to Use Example Projects](https://docs.espressif.com/projects/esp-brookesia/en/latest/getting_started.html#getting-started-example-projects).
### Select the board and build
Activate the supported ESP-IDF environment (6.0 or later). Run commands from this example directory. For a first P4 revision <3 build, with no existing `build/` output:
```bash
idf.py gen-bmgr-config -b esp32_p4_function_ev
idf.py -D IDF_TARGET=esp32p4 -D SDKCONFIG_DEFAULTS=sdkconfig.defaults build
```
For subsequent builds of this configuration, run:
```bash
idf.py build
```
For P4 revision ≥3, use `esp32_p4x_function_ev` instead. For another board, select its name from [Hardware Requirements](#hardware-requirements) and its matching chip target. Keep existing generated inputs when they already describe the correct board.
### Independent LVGL output
Super supports LVGL only and needs no GSP compiler or GSP resources. The default output is this directory's `build/`, which owns `sdkconfig`, `dependencies.lock`, `dependencies/managed_components`, generated files, and `littlefs_stage`. A new output imports the existing project sdkconfig once unless explicit defaults or an external `SDKCONFIG` are selected. The original configuration and downloads are preserved. Use `-B <another-output-directory>` for another configuration and retain the same `-B` on later menuconfig, build, and flash commands. Do not share an output with `examples/system/gsp_app`.
Each output has a separate dependency cache, so multiple outputs use additional disk space. Board generation under `components/gen_bmgr_codes` remains shared source input. Regenerate matching inputs when switching boards or ESP-IDF versions; back up custom inputs first. Use separate source checkouts for concurrent work on different boards. Give external `SDKCONFIG` or resource-stage paths distinct locations too. The [CI output audit](../../../.gitlab/tools/README.md#build_appspy) checks the standard build-local layout.
### P4 revision <3 CPU frequency
P4 chip revision v1.3 uses `esp32_p4_function_ev`. That board profile selects revision <3 and defaults to **360 MHz**. The separate `esp32_p4x_function_ev` profile retains IDF's **400 MHz** default.
Existing sdkconfig choices take precedence over defaults. To switch from P4X or another board, regenerate the board inputs and use a new output directory with explicit defaults so it does not import the project's old sdkconfig:
```bash
idf.py gen-bmgr-config -b esp32_p4_function_ev
idf.py -B build-p4-v1 -D IDF_TARGET=esp32p4 -D SDKCONFIG_DEFAULTS=sdkconfig.defaults build
```
Check `build-p4-v1/sdkconfig` for `CONFIG_ESP_BOARD_NAME="esp32_p4_function_ev"`, `CONFIG_ESP32P4_SELECTS_REV_LESS_V3=y`, and `CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ=360`. Keep `-B build-p4-v1` on subsequent menuconfig, build, and flash commands. Changing only the revision and CPU frequency in an old output does not replace its board and peripheral selections.
For revision <3, clock initialization accepts 360, 180, or 90 MHz. If startup aborts during clock initialization before `app_main`, check the selected board and frequency, then rebuild. Do not force-flash P4X firmware requiring revision ≥3.
The full configuration includes recording, AFE/wake-word processing, playback, and video. See the [HAL audio/video compatibility notes](../../../hal/brookesia_hal_adaptor/README.md#audiovideo-dependencies-and-configuration) for the dependency combination and [additional-model registration](../../../hal/brookesia_hal_adaptor/README.md#additional-esp-dl-models) before adding `.espdl` models.
### Console and Host-Control Port Pairing
ESP-Mosaico uses a board-specific TinyUSB CDC console, with the USB service and System Core USB bridge disabled in its board defaults. The UART and USB Serial/JTAG profiles below do not provide host control over Mosaico's onboard TinyUSB CDC port.
The USB service host control (BPK install, file transfer) and the console log
output must use the same physical port, so that the host talks to the device and
reads its logs over one cable. The two settings are independent Kconfig options
and must always be switched together:
| Port | Console | USB service transport |
| --- | --- | --- |
| USB-to-UART bridge (UART0) | `CONFIG_ESP_CONSOLE_UART_DEFAULT=y` | `CONFIG_BROOKESIA_SERVICE_USB_TRANSPORT_UART=y`, `..._UART_PORT=0` |
| USB Serial/JTAG (USJ) | `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y` | `CONFIG_BROOKESIA_SERVICE_USB_TRANSPORT_SERIAL_JTAG=y` |
The per-target `sdkconfig.defaults.esp32p4` and `sdkconfig.defaults.esp32s31`
files contain both profiles; enable exactly one. The default differs per target:
- **ESP32-P4** defaults to **USB Serial/JTAG**, matching the P4 function board
defaults and the CI target-test environments. Switch to the USB-to-UART
profile when the host connects through the on-board USB-to-UART bridge.
- **ESP32-S31** (Korvo1) defaults to **USB-to-UART**, matching the board's
default UART0 console.
The ESP32-P4 exposes both ports, so the port must currently be selected at build
time; runtime auto-detection is not implemented yet.
The `brookesia-usb` host CLI auto-discovers the port, so no host change is
needed when the pairing is switched.
## ⚡ Build Performance
On P4, this example's [CMake policy](CMakeLists.txt) favors firmware size with `-Os` for C++ in System Core, the JSON GUI interface, Super Shell, Settings, App Store, Files, and Service Manager to fit the existing factory partition. LVGL, HAL, Audio/Video services, and QuickJS retain `-O2`; ESP-DL kernels retain upstream `-O3`. This policy is local to Super; gsp_app uses its own build options.
The example builds the complete dependency set by default. It enables ccache and limits simultaneous compile edges for first-party Brookesia C++ targets and `esp-boost`, whose template-heavy translation units have the highest peak compiler memory use. The same tuning is available to all first-party examples and test apps.
| CMake option | Default | Description |
| --- | --- | --- |
| `CCACHE_ENABLE` | `ON` | Reuses compiler results in repeat builds |
| `BROOKESIA_CXX_JOBS` | `6` | Ninja job-pool size for C++-bearing Brookesia and `esp-boost` targets; set to `0` to disable |
| `BROOKESIA_FAST_COMPILE` | `OFF` | Uses `-g1` for Brookesia C++ sources to reduce debug-information generation during local development |
| `BROOKESIA_COMPILE_TUNING_INCLUDE_ESP_BOOST` | `ON` | Include `esp-boost` in the shared C++ job pool when the target exists |
For a memory-constrained workstation, reduce `BROOKESIA_CXX_JOBS`, for example:
```bash
idf.py -B build -D BROOKESIA_CXX_JOBS=3 build
```
The existing GCC IPA-clone compile options remain enabled independently of the job-pool setting. The old `BROOKESIA_SUPER_CXX_JOBS` and `BROOKESIA_SUPER_FAST_COMPILE` names remain accepted as deprecated aliases.
## 📊 Build Analysis
After configuration or compilation, generate a report from the build metadata:
```bash
python3 tools/analyze_build.py build
```
The tool reads `project_description.json`, `compile_commands.json`, `.ninja_log`, and Ninja dependency metadata. It writes only `brookesia_build_analysis.json` and `brookesia_build_analysis.md` inside the selected build directory. Use `--skip-deps` when only translation-unit and Ninja timing statistics are needed.
## 🚀 Quick Start
After flashing the firmware, the device initializes general services, starts the display backend, and enters the System Super Shell. A normal boot shows the App Launcher and system status bar; tapping a built-in app icon starts that app, and a bottom-edge upward gesture returns from a foreground app to the launcher.
The following serial log indicates that system initialization and the example smoke flow have completed:
```text
=== System Example Completed ===
```
## 🔍 Troubleshooting
**Blank screen after boot**
Confirm that the LittleFS partition was flashed and that `littlefs_data.bin` was generated. System Super relies on the build flow to stage `system/super`, `system/fonts`, and `apps` resources.
**Shell or built-in app launch failure**
Confirm that `brookesia_system_super`, `brookesia_system_core`, `brookesia_gui_lvgl`, related service components, and built-in app components stay on the same release line.
**Cannot exit a foreground app with the gesture**
Confirm that the Display service has started and reports touch gestures, and that the gesture starts at the bottom edge and moves upward.
**No application logs on the USB-to-UART bridge**
The bootloader ROM always prints on UART0, but the second-stage bootloader and
the application print on the configured console. If the console is set to USB
Serial/JTAG, a monitor on the USB-to-UART bridge shows only the ROM banner and
then goes silent. This usually means the console and the host-control transport
are paired to different ports: enable the USB-to-UART profile described in
[Console and Host-Control Port Pairing](#console-and-host-control-port-pairing).
## 💬 Technical Support and Feedback
Please use the following channels for feedback:
- For technical questions, visit the [esp32.com](https://esp32.com/viewforum.php?f=52&sid=86e7d3b29eae6d591c965ec885874da6) forum
- For feature requests or bug reports, open a new [GitHub Issue](https://github.com/espressif/esp-brookesia/issues)
To create a project from this example, run:
idf.py create-project-from-example "espressif/brookesia_system_super=0.8.5:super"