ESP-Brookesia 编程指南 Choose version... 快速开始 工具组件 硬件抽象组件 服务组件 AI 智能体组件 AI 表达组件 ESP-Brookesia 编程指南 » ESP-Brookesia 编程指南 在 GitHub 上修改 ESP-Brookesia 编程指南 [English] 快速开始 工具组件 硬件抽象组件 服务组件 AI智能体组件 AI表达组件 概述 ESP-Brookesia 是一个面向 AIoT 设备的人机交互开发框架，旨在简化应用程序开发和 AI 能力集成的流程。它以 ESP-IDF 为基础，通过组件化架构为开发者提供从硬件抽象、系统服务到 AI 智能体的全栈支持，加速 HMI 与 AI 应用产品的开发与上市。 备注 "Brookesia" 是一种变色龙属的物种，擅长于伪装和适应环境，这与 ESP-Brookesia 的目标紧密相关。该框架旨在提供一种灵活、可扩展的解决方案，能够适应各种不同的硬件设备和应用需求，就像 Brookesia 变色龙那样，具有高度的适应性和灵活性。 ESP-Brookesia 的主要特性包括： 原生 ESP-IDF 支持：基于 C/C++ 开发，深度集成 ESP-IDF 开发体系与 ESP Registry 组件注册表，充分利用乐鑫开源组件生态。 可扩展的硬件抽象：定义统一的硬件接口（音频、显示、触摸、存储等），并提供板级适配层，便于快速移植到不同硬件平台。 丰富的系统服务：提供 Wi-Fi 连接、音视频处理等开箱即用的系统级服务，采用 Manager + Helper 架构实现解耦与扩展，为 Agent CLI 提供支持。 多 LLM 后端集成：内置对 OpenAI、Coze、小智等主流 AI 平台的适配，提供统一的智能体管理与生命周期控制。 MCP 协议支持：通过 Function Calling / MCP 协议将设备服务能力暴露给大语言模型，实现 LLM 与系统服务的统一通信。 AI 表达能力：支持表情集、动画集等可视化 AI 表达，为拟人化交互提供丰富的视觉反馈。 功能架构 ESP-Brookesia 采用分层架构设计，自底向上由 环境与依赖、服务与框架 以及 应用层 三个层级组成，如下图所示： 环境与依赖 框架的运行基础。ESP-IDF 开发环境提供编译工具链、实时操作系统及外设驱动等底层支撑；ESP Registry 组件注册表统一管理框架各组件及其第三方依赖的分发与版本迭代。 服务与框架 框架的核心层，向下对接环境与依赖，向上为应用程序和 AI 智能体提供标准化的服务接口，涵盖基础工具、硬件抽象、系统服务、AI 智能体及表达等模块。 Utils 工具集：为上层模块提供通用基础能力。其中 General Utils 包含日志系统、错误检查、状态机、任务调度器、插件管理、内存/线程/时间分析器等核心工具； MCP Utils 作为 ESP-Brookesia 服务体系与 MCP 引擎之间的桥梁，将已注册的服务函数暴露为标准 MCP 工具，实现大语言模型对设备能力的调用。 HAL 硬件抽象：定义统一的硬件访问接口并提供板级适配实现。其中 Interface 定义音频播放/录制、显示面板/触摸、状态 LED、存储文件系统等标准化硬件接口； Adaptor 针对具体开发板提供接口实现，完成硬件资源的初始化与映射。 Boards 提供板级 YAML 配置，描述各开发板的外设拓扑、引脚与驱动参数。 General Service 通用服务：提供系统级基础服务，包括 Wi-Fi 连接管理、Audio 音频采集与播放、Video 视频编解码、NVS 非易失性存储、SNTP 网络时间同步，以及 Custom 自定义服务扩展机制。所有服务均基于 Manager + Helper 架构，支持本地调用与 RPC 远程通信。 AI Agent 智能体框架：提供 AI 智能体的统一管理框架，内置对 Coze、OpenAI、小智 等主流 AI 平台的适配。通过 Function Calling / MCP 协议实现大语言模型与系统服务的双向通信，使 LLM 能够感知和调用设备的各项能力。 AI Expression 智能体表达：提供 AI 交互场景下的可视化表达能力，包括 Emote 表情集与动画控制，为拟人化交互提供丰富的视觉反馈。 System 系统框架 (规划中)：面向不同产品形态（移动设备、音箱、机器人等）提供 GUI、系统管理与应用框架支持。 Runtime 运行时 (规划中)：提供 WebAssembly、Python、Lua 等脚本运行时支持，实现应用的动态加载与执行。 应用层 基于上述各层构建的最终产品与工程： General Projects 通用工程：面向产品的通用工程模板，集成框架各组件，可直接用于产品开发。 System Apps 系统应用 (规划中)：面向产品的系统级应用集合，包括设置、AI 助手、应用商店等，可按需裁剪和集成。 下一页 © 版权所有 2026, 乐鑫信息科技（上海）股份有限公司. 利用 Sphinx 构建，使用了 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-Brookesia 编程指南 Choose version... 快速开始 工具组件 硬件抽象组件 HAL 接口定义 概述 功能特性 API 参考 设备 & 接口基类 设备基类 接口基类 API 参考 音频接口类 显示接口类 通用接口类 电源接口类 存储接口类 HAL 接口适配 HAL 开发板支持 服务组件 AI 智能体组件 AI 表达组件 ESP-Brookesia 编程指南 » 硬件抽象组件 » HAL 接口 » 接口基类 在 GitHub 上修改 接口基类 [English] 公共头文件： #include "brookesia/hal_interface/interface.hpp" API 参考 Header File hal/brookesia_hal_interface/include/brookesia/hal_interface/interface.hpp Classes class Interface Base class for all HAL interfaces exposed by a device. Each concrete interface derives from this type and provides a stable interface name for runtime lookup via the plugin registry. Subclassed by esp_brookesia::hal::AudioCodecPlayerIface, esp_brookesia::hal::AudioCodecRecorderIface, esp_brookesia::hal::BoardInfoIface, esp_brookesia::hal::DisplayBacklightIface, esp_brookesia::hal::DisplayPanelIface, esp_brookesia::hal::DisplayTouchIface, esp_brookesia::hal::PowerBatteryIface, esp_brookesia::hal::StorageFsIface Public Functions inline explicit Interface(std::string_view name) Construct an interface object with a runtime name. 参数 name -- [in] Interface name used by the registry. virtual ~Interface() = default Virtual destructor for polymorphic interface usage. inline std::string_view get_name() const noexcept Get the registered interface name. 返回 Interface name. 上一页 下一页 © 版权所有 2026, 乐鑫信息科技（上海）股份有限公司. 利用 Sphinx 构建，使用了 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-Brookesia 编程指南 Choose version... 快速开始 工具组件 硬件抽象组件 HAL 接口定义 HAL 接口适配 HAL 开发板支持 服务组件 AI 智能体组件 AI 表达组件 ESP-Brookesia 编程指南 » 硬件抽象组件 在 GitHub 上修改 硬件抽象组件 [English] ESP-Brookesia HAL 框架由三个组件分层协作，共同完成从开发板硬件到上层业务的抽象： flowchart TD A["上层业务 / 服务 / 示例"] B["**brookesia_hal_interface**
· 设备 / 接口抽象基类
· 音频、显示、存储等 HAL 接口定义
· 全局接口注册表"] C["**brookesia_hal_adaptor**
· AudioDevice / DisplayDevice / StorageDevice 板级实现
· 通过 esp_board_manager 初始化外设
· 将接口实例注册到全局表"] D["**brookesia_hal_boards**
· 各开发板的外设拓扑（引脚、总线）
· 逻辑设备配置（音频编解码、LCD、触摸等）
· 板级 Kconfig 默认值与驱动工厂回调"] A -->|"按接口名称发现 & 调用"| B B -->|"实现抽象接口"| C C -->|"提供 YAML 配置"| D brookesia_hal_interface： 定义抽象接口，上层业务只依赖此层，与具体硬件解耦 brookesia_hal_adaptor： 实现抽象接口，通过 esp_board_manager 读取板级配置并初始化真实外设 brookesia_hal_boards： 提供板级 YAML 配置，描述各开发板的外设拓扑、引脚与驱动参数 备注 自定义开发板可通过以下两种方式接入 ESP-Brookesia HAL 框架： 方式一（推荐）：在 brookesia_hal_boards 的 boards/<厂商>/ 目录下，按照 esp_board_manager 规范新建开发板子目录并补充配置文件，无需修改适配层代码。详见 添加自定义开发板。 方式二（完全自定义）：移除对 brookesia_hal_adaptor 和 brookesia_hal_boards 的依赖，直接基于 brookesia_hal_interface 的抽象接口编写板级初始化代码。适用于无法使用 esp_board_manager 的场景，但需自行维护与接口规范的兼容性。 HAL 接口定义 HAL 接口适配 HAL 开发板支持 上一页 下一页 © 版权所有 2026, 乐鑫信息科技（上海）股份有限公司. 利用 Sphinx 构建，使用了 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-Brookesia 编程指南 Choose version... 快速开始 工具组件 硬件抽象组件 服务组件 服务框架 服务管理器 服务辅助 通用服务 NVS SNTP Wi-Fi 音频 设备控制 视频 自定义 开发指南 应用开发指南 AI 智能体组件 AI 表达组件 ESP-Brookesia 编程指南 » 服务组件 在 GitHub 上修改 服务组件 [English] 本分类包含 ESP-Brookesia 服务框架组件的说明内容。ESP-Brookesia 服务框架由服务框架层和通用服务层组成，各组件的层级关系如下： flowchart TD App["App / 用户代码"] Helper["**brookesia_service_helper**
· CRTP 类型安全辅助基类
· 函数 / 事件 Schema 定义
· call_function / subscribe_event"] Manager["**brookesia_service_manager**
· 服务插件生命周期管理
· 本地线程安全调用 & TCP RPC 远程调用
· 函数注册表 & 事件注册表"] Services["**通用服务（基于 service_helper 实现）**
NVS · SNTP · Wi-Fi · 音频 · 设备控制 · 视频 · 自定义"] App -->|"调用函数 / 订阅事件"| Helper Helper -->|"构建在"| Manager Services -->|"注册为插件"| Manager brookesia_service_manager：服务框架核心，负责服务插件注册、本地/RPC 两种通信模式下的函数路由与事件分发 brookesia_service_helper：基于 CRTP 的类型安全辅助层，简化服务的函数/事件定义与调用方式 通用服务：基于 service_helper 实现的具体业务服务，注册到 service_manager 后可被上层按名称发现和调用 服务框架 服务管理器 服务辅助 通用服务 NVS SNTP Wi-Fi 音频 设备控制 视频 自定义 开发指南 应用开发指南 上一页 下一页 © 版权所有 2026, 乐鑫信息科技（上海）股份有限公司. 利用 Sphinx 构建，使用了 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-Brookesia 编程指南 Choose version... 快速开始 工具组件 硬件抽象组件 HAL 接口定义 HAL 接口适配 概述 功能特性 内置设备 配置与参数 API 参考 Header File Classes Header File Classes Header File Classes Header File Classes Header File Classes HAL 开发板支持 服务组件 AI 智能体组件 AI 表达组件 ESP-Brookesia 编程指南 » 硬件抽象组件 » HAL 适配 在 GitHub 上修改 HAL 适配 [English] 组件注册表： espressif/brookesia_hal_adaptor 公共头文件： #include "brookesia/hal_adaptor.hpp" 概述 brookesia_hal_adaptor 是 ESP-Brookesia 的板级 HAL 适配实现，基于 HAL 接口 的设备/接口模型，通过 esp_board_manager 初始化真实外设，并将 通用信息、 音频、 显示、 存储、 电源 等能力注册到全局 HAL 表，供上层按名称发现和使用。 功能特性 内置设备 本组件提供多台板级设备，每台设备以单例形式注册，初始化后将对应的接口发布到全局表： 设备类（逻辑名） 注册的接口实现 说明 GeneralDevice ("General") BoardInfoIface (BOARD_INFO_IMPL_NAME) 从板级配置读取开发板名称、芯片、版本、描述和制造商等静态信息，供上层做设备识别与信息展示。 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") StorageFsIface (GENERAL_FS_IMPL_NAME) 通用文件系统实现，支持 SPIFFS（依赖 ESP_BOARD_DEV_FS_SPIFFS_SUPPORT）与 SD 卡（FATFS，依赖 ESP_BOARD_DEV_FS_FAT_SUPPORT），按 Kconfig 启用。 PowerDevice ("Power") PowerBatteryIface (BATTERY_IMPL_NAME) 电池与充电器能力实现，支持 ADC 电压估算或 AXP2101 电源管理芯片实现；可查询电量、电压、电源来源、充电状态，并在底层支持时控制充电配置。 配置与参数 各设备与子接口可在 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/general/device.hpp Classes class GeneralDevice : public esp_brookesia::hal::Device Board-backed metadata device: publishes a board information HAL interface. Obtained via get_instance(). Not copyable or movable. Public Static Functions static inline GeneralDevice &get_instance() Returns the process-wide singleton board device. 返回 Reference to the unique GeneralDevice instance. Public Static Attributes static constexpr const char *DEVICE_NAME = "General" Logical device name passed to the base Device constructor. static constexpr const char *BOARD_INFO_IMPL_NAME = "General:BoardInfo" Registry key for the board information HAL interface ("General:BoardInfo"). 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_re