Getting Started

[中文]

This guide explains how to obtain and use ESP-Brookesia components and how to build and run example projects.

ESP-Brookesia versioning

From v0.7, ESP-Brookesia is componentized. Obtain components via the component registry as follows:

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 major versions; master integrates new features.

Version support:

ESP-Brookesia version support

ESP-Brookesia	ESP-IDF	Main changes	Status
master (v0.7)	>= v5.5, < 6.0	Component manager support	Active development
release/v0.6	>= v5.3, <= 5.5	Preview system framework; ESP-VoCat firmware project	End of maintenance

Development environment

ESP-IDF is Espressif’s framework for ESP series chips:

• Libraries and headers provide core building blocks for ESP SoC software.

• Tools for build, flash, debug, and measurement are included for development and production.

Note

• Follow the ESP-IDF Programming Guide to set up the ESP-IDF environment.

• It is not recommended to install the ESP-IDF environment using the VSCode extension, as this may cause build failures for some examples that depend on the esp_board_manager component.

Hardware

ESP SoCs typically provide:

• Wi-Fi (2.4 GHz / 5 GHz dual band where applicable)

• Bluetooth 5.x (BLE / Mesh)

• High-performance multi-core CPUs (up to ~400 MHz)

• Ultra-low-power coprocessor and deep sleep

• Rich peripherals:

  • General-purpose: GPIO, UART, I2C, I2S, SPI, SDIO, USB OTG, etc.

  • Dedicated: LCD, camera, Ethernet, CAN, touch, LED PWM, temperature sensors, and more

• Memory:

  • Up to ~768 KB internal RAM

  • Optional external PSRAM

  • Optional external Flash

• Security:

  • Hardware crypto engine

  • Secure boot

  • Flash encryption

  • Digital signature

ESP SoCs use advanced process technology and offer leading RF performance, low power, and reliability for IoT, industrial, smart home, wearables, and similar applications.

Note

• Refer to the ESP Product Selector for per-series details.

• Refer to ESP-Brookesia HAL Boards for supported boards.

• ESP-Brookesia requires a Flash capacity of at least 8 MB and a PSRAM capacity of at least 4 MB.

Obtaining and using components

Use the ESP Component Registry to add ESP-Brookesia components.

Example: add brookesia_service_wifi:

1. Command line

   From your project directory:

   idf.py add-dependency "espressif/brookesia_service_wifi"
   

2. Manifest

   Create or edit idf_component.yml:

   dependencies:
      espressif/brookesia_service_wifi: "*"
   

See ESP Registry Docs for more.

Using example projects

ESP-Brookesia ships multiple examples. Typical workflow:

1. Complete ESP-IDF setup first.

2. Select target chip or board (depends on peripherals):

   • Chip only:

     For examples/service/wifi, only Wi-Fi is required, so select a chip target (e.g. esp32s3):

     idf.py set-target <target>
     

   • Board:

     For examples/service/console, audio peripherals matter, so select a board (e.g. esp_vocat_board_v1_2):

     idf.py gen-bmgr-config -b <board>
     idf.py set-target <target>
     

3. Optional configuration:

   idf.py menuconfig
   

4. Build and flash:

   idf.py build
   idf.py -p <PORT> flash
   

5. Monitor serial output:

   idf.py -p <PORT> monitor
   

More examples live under examples/; see each README for details.