ESP Device Board Adaptation

[中文]

• Component registry: espressif/brookesia_hal_adaptor

• Public header: #include "brookesia/hal_adaptor.hpp"

Overview

brookesia_hal_adaptor is the board-level HAL adaptor of ESP-Brookesia. Based on the device/interface model in HAL Interface, it initialises real peripherals via esp_board_manager and ESP-IDF drivers, then registers system, network, audio, display, storage, power, video, and Wi-Fi capabilities into the global HAL table for upper layers to discover by name.

Features

Built-In Devices

The component ships multiple board-level devices, each registered as a singleton; after initialisation they publish their interfaces into the global table:

Device class (logical name)	Registered interface implementations	Notes
SystemDevice ("System")	BoardInfoIface (BOARD_INFO_IMPL_NAME)	Reads static board metadata and publishes system-level board information.
NetworkDevice ("Network")	SntpClientIface (SNTP_CLIENT_IFACE_NAME), HttpClientIface (HTTP_CLIENT_IFACE_NAME)	Provides platform SNTP and HTTP/HTTPS client capabilities for services.
AudioDevice ("Audio")	AudioCodecPlayerIface (CODEC_PLAYER_IMPL_NAME), AudioCodecRecorderIface (CODEC_RECORDER_IMPL_NAME)	Playback via board Audio DAC; recording via Audio ADC. Each sub-implementation can be disabled in Kconfig; requires board capability ESP_BOARD_DEV_AUDIO_CODEC_SUPPORT.
DisplayDevice ("Display")	DisplayBacklightIface (LEDC_BACKLIGHT_IMPL_NAME), DisplayPanelIface (LCD_PANEL_IMPL_NAME), DisplayTouchIface (LCD_TOUCH_IMPL_NAME)	LEDC backlight, LCD panel, and I2C touch can each be disabled; require ESP_BOARD_DEV_LEDC_CTRL_SUPPORT, ESP_BOARD_DEV_DISPLAY_LCD_SUPPORT, ESP_BOARD_DEV_LCD_TOUCH_I2C_SUPPORT respectively.
StorageDevice ("Storage")	FileSystemIface (GENERAL_FS_IMPL_NAME), KeyValueIface (KV_IMPL_NAME)	General filesystem implementation for LittleFS, optional SPIFFS, flash FATFS, and SD card / FATFS; KV implementation backed by ESP-IDF NVS. Filesystem backends are enabled per Kconfig, and LittleFS / flash FATFS are mounted directly by the adaptor.
PowerDevice ("Power")	PowerBatteryIface (BATTERY_IMPL_NAME)	Battery and charger capability implementation. Supports ADC voltage estimation or AXP2101 power-management-chip backends; can query level, voltage, power source, and charge state, and control charger configuration when supported by the underlying hardware.
VideoDevice ("Video")	CameraIface and video processor interfaces	Publishes camera and video processing interfaces when the selected board exposes them.
WifiDevice ("WiFi")	BasicIface (BASIC_IMPL_NAME), StationIface (STA_IMPL_NAME), SoftApIface (SOFTAP_IMPL_NAME)	ESP-IDF Wi-Fi backend for single-shot lifecycle, STA, scan, SoftAP, and provisioning actions. Retry, fallback, and auto-connect policy are owned by brookesia_service_wifi.

Configuration

Each device and sub-interface can be enabled or disabled individually under ESP-Brookesia: Hal Adaptor Configurations in menuconfig; default capability parameters (volume range, recording format, backlight range, battery low-level thresholds, ADC voltage conversion parameters, etc.) are also adjustable there, and are mapped to compile-time macros by macro_configs.h.

To override default capability parameters before initialisation, call set_codec_player_info, set_codec_recorder_info, or set_ledc_backlight_info on the corresponding device singleton. Calls after initialisation typically have no effect.

API Reference

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/system/device.hpp

Classes

class SystemDevice : public esp_brookesia::hal::Device

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/network/device.hpp

Classes

class NetworkDevice : public esp_brookesia::hal::Device

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/display/device.hpp

Classes

class DisplayDevice : public esp_brookesia::hal::Device

Board-backed display device: registers panel, touch, and backlight HAL interfaces after board bring-up.

Obtained via get_instance(). Not copyable or movable.

Public Static Functions

static inline DisplayDevice &get_instance()

Returns the process-wide singleton display device.

Returns

Reference to the unique DisplayDevice instance.

Public Static Attributes

static constexpr const char *DEVICE_NAME = "Display"

Logical device name passed to the base Device constructor.

static constexpr const char *LEDC_BACKLIGHT_IMPL_NAME = "Display:LedcBacklight"

Registry key for the LEDC-based backlight HAL implementation ("Display:LedcBacklight").

static constexpr const char *LCD_PANEL_IMPL_NAME = "Display:LcdPanel"

Registry key for the LCD panel HAL implementation ("Display:LcdPanel").

static constexpr const char *LCD_TOUCH_IMPL_NAME = "Display:LcdTouch"

Registry key for the LCD touch HAL implementation ("Display:LcdTouch").

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/audio/device.hpp

Classes

class AudioDevice : public esp_brookesia::hal::Device

Board-backed audio device: registers codec player and recorder HAL interfaces after board bring-up.

Obtained via get_instance(). Not copyable or movable.

Public Functions

bool set_codec_recorder_info(audio::CodecRecorderIface::Info info)

Overrides default static recording capability information used when constructing the codec recorder implementation.

Parameters

info -- [in] Codec recorder capability descriptor (format, channels, gains, etc.).

Returns

true if the value was stored; false on invalid input or if the recorder is already initialized.

bool set_processor_config(AudioProcessorConfig config)

Set the ESP audio processor backend configuration.

This must be called before the audio processor playback, encoder, or decoder HAL interfaces are initialized.

Parameters

config -- [in] Complete processor configuration.

Returns

true if the value was stored; false after processor initialization.

Public Static Functions

static inline AudioDevice &get_instance()

Returns the process-wide singleton audio device.

Returns

Reference to the unique AudioDevice instance.

Public Static Attributes

static constexpr const char *DEVICE_NAME = "Audio"

Logical device name passed to the base Device constructor.

static constexpr const char *CODEC_PLAYER_IMPL_NAME = "Audio:CodecPlayer"

Registry key for the codec player HAL implementation ("Audio:CodecPlayer").

static constexpr const char *CODEC_RECORDER_IMPL_NAME = "Audio:CodecRecorder"

Registry key for the codec recorder HAL implementation ("Audio:CodecRecorder").

static constexpr const char *PLAYBACK_IMPL_NAME = "Audio:Playback"

Registry key for the audio playback HAL implementation.

static constexpr const char *ENCODER_IMPL_NAME = "Audio:Encoder:0"

Registry key for the audio encoder HAL implementation.

static constexpr const char *DECODER_IMPL_NAME = "Audio:Decoder:0"

Registry key for the audio decoder HAL implementation.

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/storage/device.hpp

Classes

class StorageDevice : public esp_brookesia::hal::Device

Board-backed storage device: publishes filesystem and key-value HAL interfaces after bring-up.

Obtained via get_instance(). Not copyable or movable.

Public Static Functions

static inline StorageDevice &get_instance()

Returns the process-wide singleton storage device.

Returns

Reference to the unique StorageDevice instance.

Public Static Attributes

static constexpr const char *DEVICE_NAME = "Storage"

Logical device name passed to the base Device constructor.

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/power/device.hpp

Classes

class PowerDevice : public esp_brookesia::hal::Device

Power-backed metadata device: publishes a power HAL interface.

Obtained via get_instance(). Not copyable or movable.

Public Static Functions

static inline PowerDevice &get_instance()

Returns the process-wide singleton power device.

Returns

Reference to the unique PowerDevice instance.

Public Static Attributes

static constexpr const char *DEVICE_NAME = "Power"

Logical device name passed to the base Device constructor.

static constexpr const char *BATTERY_IMPL_NAME = "Power:Battery"

Registry key for the power HAL interface ("Power:Battery").

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/video/device.hpp

Classes

class VideoDevice : public esp_brookesia::hal::Device

Header File

• hal/brookesia_hal_adaptor/include/brookesia/hal_adaptor/wifi/device.hpp

Classes

class WifiDevice : public esp_brookesia::hal::Device