ESP-BOX reference applications

What you’re building

Espressif’s esp-box repository is the official AIoT development framework and example collection for ESP32-S3-BOX-family hardware, including the active ESP32-S3-BOX-3. It combines board-support components with LVGL display code, audio, buttons, I2C devices, ESP-SR speech recognition, and optional RainMaker integration. Examples and factory firmware demonstrate offline wake words and commands, screen interaction, media, sensor accessories, device control, and broader HMI or smart-home prototypes. Developers use a repository-matched ESP-IDF release, clone recursively, select the board where required, then build and flash an example such as image_display or factory_demo over USB. The expected result is a working reference application that can become a custom voice-and-display product prototype. Compatibility is branch-specific: master requires ESP-IDF release/v5.1 at the documented commit and only partial support for older BOX models. Sensor Monitor also requires the BOX-3-SENSOR accessory, and dock accessories should not be hot-plugged during operation.

Key steps

1. Identify the exact BOX model and consult the repository’s version table; for master, install the specified ESP-IDF release/v5.1 commit and export its environment.
2. Clone esp-box recursively so its components and submodules are available.
3. Choose a compatible example such as examples/image_display or examples/factory_demo and select the intended board through menuconfig when the branch requires it.
4. Run idf.py build in the example directory, connect the BOX over USB, then use idf.py -p PORT flash monitor.
5. Verify the example’s display, audio, voice, or accessory behavior; power down before changing docks, and use the BOX-3-SENSOR only for Sensor Monitor features that require it.