ESP 设备板级适配

组件注册表： espressif/brookesia_hal_adaptor
公共头文件： #include "brookesia/hal_adaptor.hpp"

概述

brookesia_hal_adaptor 是 ESP-Brookesia 的板级 HAL 适配实现，基于 HAL 接口的设备/接口模型，通过 esp_board_manager 与 ESP-IDF 驱动初始化真实外设，并将系统、网络、音频、显示、存储、电源、视频、 Wi-Fi 等能力注册到全局 HAL 表，供上层按名称发现和使用。

功能特性

内置设备

本组件提供多台板级设备，每台设备以单例形式注册，初始化后将对应的接口发布到全局表：

设备类（逻辑名）	注册的接口实现	说明
`SystemDevice` (`"System"`)	`BoardInfoIface` (`BOARD_INFO_IMPL_NAME`)	读取静态开发板元信息，并发布系统级板级信息接口。
`NetworkDevice` (`"Network"`)	`SntpClientIface` (`SNTP_CLIENT_IFACE_NAME`)、`HttpClientIface` (`HTTP_CLIENT_IFACE_NAME`)	为 Service 提供平台 SNTP 与 HTTP/HTTPS 客户端能力。
`AudioDevice` (`"Audio"`)	`AudioCodecPlayerIface` (`CODEC_PLAYER_IMPL_NAME`)、`AudioCodecRecorderIface` (`CODEC_RECORDER_IMPL_NAME`)	播放经板级 Audio DAC；录音经 Audio ADC。子实现可在 Kconfig 中独立关闭，并依赖板级能力符号 `ESP_BOARD_DEV_AUDIO_CODEC_SUPPORT`。
`DisplayDevice` (`"Display"`)	`DisplayBacklightIface` (`LEDC_BACKLIGHT_IMPL_NAME`)、`DisplayPanelIface` (`LCD_PANEL_IMPL_NAME`)、`DisplayTouchIface` (`LCD_TOUCH_IMPL_NAME`)	LEDC 背光、LCD 面板、I2C 触摸可分别开关；分别依赖 `ESP_BOARD_DEV_LEDC_CTRL_SUPPORT`、`ESP_BOARD_DEV_DISPLAY_LCD_SUPPORT`、`ESP_BOARD_DEV_LCD_TOUCH_I2C_SUPPORT`。
`StorageDevice` (`"Storage"`)	`FileSystemIface` (`GENERAL_FS_IMPL_NAME`)、`KeyValueIface` (`KV_IMPL_NAME`)	通用文件系统实现支持 LittleFS、可选 SPIFFS、Flash FATFS 与 SD 卡 FATFS；KV 实现基于 ESP-IDF NVS。文件系统后端按 Kconfig 启用，其中 LittleFS 与 Flash FATFS 由 adaptor 直接挂载。
`PowerDevice` (`"Power"`)	`PowerBatteryIface` (`BATTERY_IMPL_NAME`)	电池与充电器能力实现，支持 ADC 电压估算或 AXP2101 电源管理芯片实现；可查询电量、电压、电源来源、充电状态，并在底层支持时控制充电配置。
`VideoDevice` (`"Video"`)	`CameraIface` 与视频处理接口	当所选开发板暴露对应能力时，发布摄像头与视频处理接口。
`WifiDevice` (`"WiFi"`)	`BasicIface` (`BASIC_IMPL_NAME`)、`StationIface` (`STA_IMPL_NAME`)、`SoftApIface` (`SOFTAP_IMPL_NAME`)	基于 ESP-IDF 的 Wi-Fi 后端，负责单次生命周期、STA、扫描、SoftAP 与配网动作。重试、fallback 与自动连接策略由 `brookesia_service_wifi` 负责。

配置与参数

各设备与子接口可在 menuconfig 的 ESP-Brookesia: Hal Adaptor Configurations 中独立开启或关闭；默认能力参数（音量范围、录音格式、背光亮度范围、电池低电量阈值、ADC 电压换算参数等）也可在 menuconfig 中调整，由 macro_configs.h 映射为编译宏供实现使用。

若需在初始化前覆盖默认能力参数，可在对应设备单例上调用 set_codec_player_info、set_codec_recorder_info 或 set_ledc_backlight_info。初始化完成后再调用通常不会生效。

API 参考

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.

返回: 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.

参数: info -- [in] Codec recorder capability descriptor (format, channels, gains, etc.).
返回: 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.

参数: config -- [in] Complete processor configuration.
返回: 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.

返回: 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.

返回: 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.

返回: 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 