Hardware Components

[中文]

ESP-Brookesia HAL consists of three components that work together in layers, bridging the gap between board-level hardware and upper-layer business logic:

flowchart TD
    A["Upper-layer business / services / examples"]
    B["**brookesia_hal_interface**<br/>- Device and interface abstraction base classes<br/>- HAL interface definitions for audio, display, storage, etc.<br/>- Global interface registry"]
    C["**brookesia_hal_adaptor**<br/>- Board-level AudioDevice / DisplayDevice / StorageDevice implementations<br/>- Initializes peripherals through esp_board_manager<br/>- Registers interface instances globally"]
    D["**brookesia_hal_boards**<br/>- Peripheral topology for each board<br/>- Logical device configuration for codec, LCD, touch, etc.<br/>- Board Kconfig defaults and driver factory callbacks"]

    A -->|"Discover and call by interface name"| B
    B -->|"Implements abstract interfaces"| C
    C -->|"Provides YAML configuration"| D

  • brookesia_hal_interface: Defines abstract interfaces; upper-layer code depends only on this layer and remains decoupled from hardware details.

  • brookesia_hal_adaptor: Implements the abstract interfaces by reading board configuration via esp_board_manager and initializing real peripherals.

  • brookesia_hal_boards: Provides board-level YAML configuration describing the peripheral topology, pin assignments, and driver parameters for each supported board.

Note

Custom boards can be integrated into the ESP-Brookesia HAL framework in two ways:

  • Option 1 (Recommended): Create a new board subdirectory under brookesia_hal_boards/boards/<vendor>/ following the esp_board_manager specification and add the required configuration files. No changes to the adaptor layer are needed. See Add a Custom Board.

  • Option 2 (Fully Custom): Remove the dependencies on brookesia_hal_adaptor and brookesia_hal_boards, and implement board-level initialization directly against the abstract interfaces in brookesia_hal_interface. This is suitable for cases where esp_board_manager cannot be used, but requires maintaining compatibility with the interface specification manually.