HAL Board Support

Component Registry: espressif/brookesia_hal_boards

Overview

brookesia_hal_boards is the board configuration collection for ESP-Brookesia. It uses YAML files to describe the peripheral topology and device parameters for each supported board, allowing HAL Adaptor to initialize hardware at runtime without any board-specific hardcoding.

Supported Boards

Espressif Boards

Directory Structure

Each board has its own subdirectory under boards/<vendor>/<board-name>/ containing the following files:

boards/
└── <vendor>/
    └── <board>/
       ├── board_info.yaml          # Board metadata (name, chip, version, manufacturer, etc.)
       ├── board_devices.yaml       # Logical device configurations (audio codec, LCD, touch, storage, etc.)
       ├── board_peripherals.yaml   # Low-level peripheral configurations (I2C/I2S/SPI buses, GPIO, LEDC, etc.)
       ├── sdkconfig.defaults.board # Board-specific Kconfig defaults (Flash, PSRAM, etc.)
       └── setup_device.c           # Board-specific device factory callbacks (for custom driver initialization)

Note

For the complete board configuration format reference, see the esp_board_manager component documentation.

Device Types

board_devices.yaml describes the logical functional modules on the board. Common device types include:

Device Type	Description
`audio_codec`	Audio codec chip (DAC playback / ADC recording); supports ES8311, ES7210, internal ADC, and more
`display_lcd`	LCD display; supports SPI (ST77916, ILI9341), DSI (EK79007), and other interfaces
`lcd_touch`	Touch panel; supports CST816S, GT911, and other I2C touch controllers
`ledc_ctrl`	PWM backlight control via LEDC
`fs_fat` / `fs_spiffs`	File system storage; supports SD cards (SDMMC/SPI) and SPIFFS
`camera`	Camera (CSI interface)
`power_ctrl`	GPIO-based power control (audio power, LCD/SD card power, and more)
`gpio_ctrl`	General-purpose GPIO control (LEDs, buttons, and more)

Peripheral Configuration

board_peripherals.yaml describes the pin assignments and parameters for low-level hardware resources:

I2C: SDA/SCL pins and port number
I2S: MCLK/BCLK/WS/DOUT/DIN pins, sample rate, and bit depth
SPI: MOSI/MISO/CLK/CS pins, SPI host number, and transfer size
LEDC: Backlight GPIO, PWM frequency, and resolution
GPIO: Standalone pin configurations such as power control, amplifier enable, and LEDs

sdkconfig.defaults.board contains Kconfig defaults tightly coupled to the board hardware, such as Flash size, PSRAM mode and frequency, CPU clock frequency, and audio recording format parameters for brookesia_hal_adaptor.

If a driver requires a custom initialization flow, such as passing a vendor-specific register sequence to an LCD driver, it is implemented through factory callbacks in setup_device.c.

Usage

Select a Board

See How to Use Example Projects.

Add a Custom Board

Create a new board subdirectory under boards/<vendor>/ and add the following files in order:

board_info.yaml: Fill in the board name, chip model, version, and description.
board_peripherals.yaml: Configure peripheral parameters based on the actual pins and buses.
board_devices.yaml: Describe on-board devices with their types and configurations.
sdkconfig.defaults.board: Add board-specific Kconfig defaults.
setup_device.c (optional): Implement factory functions if the driver requires extra initialization steps.

Once done, run idf.py gen-bmgr-config -b <new_board> to use the new board.