xiaozhi-esp32 接入 Waveshare ESP32-S3-Touch-LCD-4B86 盒形态的 MCP 聊天机器人板级适配指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文基于 xiaozhi-esp32 开源仓库讲解如何将 Waveshare ESP32-S3-Touch-LCD-4B基于 ESP32-S3 的 86 智能面板开发板接入小智 AI 聊天机器人固件。文章以该开发板的官方适配文档为核心骨架结合 板级源码、引脚配置 与 构建配置 展开完整覆盖 menuconfig 选择流程、硬件资源初始化、显示/触摸/音频/电源管理链路与按键交互逻辑读者可据此自行编译固件并完成该开发板的部署与二次开发。一、开发板概况一款带 480×480 电容触摸屏的智能 86 盒Waveshare微雪电子设计的 ESP32-S3-Touch-LCD-4B 是一款以 ESP32-S3 模组为核心的智能 86 盒86 box即标准 86 型墙壁开关面板尺寸的嵌入式设备形态核心硬件特征为480×480 IPS 电容触摸屏采用 ST7701 驱动 ICRGB 接口16 位数据总线输出触摸部分使用 GT911 触控 IC通过 I2C 与主控通信搭载 AXP2101 电源管理芯片PMIC负责电池充放电管理与系统上下电音频通路采用 ES8311音频编解码 ES7210ADC组合支持回声消除参考输入配备 TCA9554 IO 扩展器用于驱动 LCD 控制信号线与按键检测。该板在 xiaozhi-esp32 中属于WifiBoard家族的成员即依靠 WiFi 联网、无 4G 蜂窝模块的典型交互设备形态适合作为桌面/墙装形态的语音对话终端。其仓库适配文件位于 main/boards/waveshare/esp32-s3-touch-lcd-4b/包含四个文件文件作用README.md官方板级适配说明即本文所依据的关联文档esp32-s3-touch-lcd-4b.cc板级实现声明并注册WaveshareEsp32s3TouchLCD4b板类config.h引脚定义与屏幕/音频参数宏config.json固件构建元数据目标芯片、sdkconfig 附加项二、启用该开发板menuconfig 配置步骤官方文档给出的启用方式非常简洁——在 ESP-IDF 的menuconfig中完成板型选择执行idf.py menuconfig打开配置界面依次进入Xiaozhi Assistant -- Board Type在板型列表中勾选Waveshare ESP32-S3-Touch-LCD-4B保存退出后正常编译烧录即可。该选项在源码中的真实存在可由 main/Kconfig.projbuild 印证config BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_4B bool Waveshare ESP32-S3-Touch-LCD-4B depends on IDF_TARGET_ESP32S3注意其depends on IDF_TARGET_ESP32S3条件该板型仅支持 ESP32-S3 目标芯片因此在编译前需先通过idf.py set-target esp32s3或首次构建时指定将目标芯片设置为 esp32s3。选中该配置后main/CMakeLists.txt 会将BOARD_DIR指向waveshare/esp32-s3-touch-lcd-4b目录并启用对应字体资源elseif(CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_4B) set(BOARD_DIR waveshare/esp32-s3-touch-lcd-4b) set(BUILTIN_TEXT_FONT font_noto_sans_basic_30_4) set(BUILTIN_ICON_FONT font_material_symbols_30_4) set(DEFAULT_EMOJI_COLLECTION noto-color-emoji_64)从该片段可以推断4B 板型使用了font_noto_sans_basic_30_4基础字体、font_material_symbols_30_4图标字体以及 64px 的彩色 Emoji 资源与同尺寸的 480×480 屏幕板型保持一致。构建元数据方面config.json 声明了该板型的固件构建配置{ manufacturer: waveshare, type: esp32-s3-touch-lcd-4b, target: esp32s3, builds: [ { name: esp32-s3-touch-lcd-4b, sdkconfig_append: [ CONFIG_USE_WECHAT_MESSAGE_STYLEn, CONFIG_USE_DEVICE_AECy ] } ] }其中两个 sdkconfig 附加项含义如下CONFIG_USE_WECHAT_MESSAGE_STYLEn关闭微信气泡消息风格 UI使用默认的对话界面样式CONFIG_USE_DEVICE_AECy启用设备端回声消除Acoustic Echo Cancellation。该选项开启后板级代码会额外编译 BOOT 按键双击切换 AEC 模式的逻辑见下文按键交互章节同时音频通路会利用 ES7210 的参考信号做回声消除提升语音对话体验。三、板级实现剖析从启动到外设初始化的完整链路板级适配的核心是 esp32-s3-touch-lcd-4b.cc 中的WaveshareEsp32s3TouchLCD4b类。该类继承自WifiBoard定义于 main/boards/common/wifi_board.h并通过文件末尾的DECLARE_BOARD(WaveshareEsp32s3TouchLCD4b)宏注册为工厂实例。DECLARE_BOARD宏定义在 main/boards/common/board.h展开后生成create_board()工厂函数供Board::GetInstance()创建单例。构造函数按以下顺序完成全部外设初始化WaveshareEsp32s3TouchLCD4b() : boot_button_(BOOT_BUTTON_GPIO) { InitializePowerSaveTimer(); InitializeCodecI2c(); InitializeTca9554(); InitializeAxp2101(); InitializeRGB(); InitializeTouch(); InitializeButtons(); InitializeTools(); InitializeKeyMonitor(); GetBacklight()-SetBrightness(100); }各步骤职责如下初始化步骤对应函数职责电源节能InitializePowerSaveTimer()创建节能定时器绑定睡眠/唤醒/关机回调音频 I2C 总线InitializeCodecI2c()创建 I2C 主总线供音频编解码器与触摸芯片使用IO 扩展器InitializeTca9554()初始化 TCA9554控制 LCD 控制信号并配置按键引脚电源管理InitializeAxp2101()初始化 AXP2101 PMIC配置输出电压与充电参数RGB 屏幕InitializeRGB()初始化 ST7701 LCD 面板RGB 接口并创建显示对象触摸屏InitializeTouch()初始化 GT911 触摸控制器并挂载到 LVGL按键InitializeButtons()注册 BOOT 按键单击/双击回调MCP 工具InitializeTools()向 MCP 服务器注册 WiFi 重配置工具按键轮询InitializeKeyMonitor()启动独立任务监听物理按键时长3.1 电源节能与 PMIC 联动InitializePowerSaveTimer()创建了一个PowerSaveTimer其接口见 main/boards/common/power_save_timer.hpower_save_timer_ new PowerSaveTimer(-1, 60, 300);三个参数依次为CPU 最大频率限制-1 表示不限制、空闲 60 秒进入睡眠模式、空闲 300 秒触发关机请求。睡眠与唤醒回调分别通过SetPowerSaveMode与背光亮度调节实现power_save_timer_-OnEnterSleepMode([this]() { GetDisplay()-SetPowerSaveMode(true); GetBacklight()-SetBrightness(70); }); power_save_timer_-OnExitSleepMode([this]() { GetDisplay()-SetPowerSaveMode(false); GetBacklight()-RestoreBrightness(); }); power_save_timer_-OnShutdownRequest([this](){ pmic_-PowerOff(); });即进入睡眠时屏幕进入省电模式且背光降为 70唤醒时恢复背光若 300 秒内未唤醒则直接调用 PMIC 的PowerOff()关机。此外GetBatteryLevel() 中还有一个细节仅在设备处于**放电未插电**状态时才启用节能定时器插电充电时禁用节能逻辑避免充电过程中设备频繁进入睡眠。SetPowerSaveLevel覆盖了基类接口处理LOW_POWER之外所有档位时先唤醒节能定时器再交回WifiBoard处理保证对话状态下设备始终处于唤醒可交互状态。3.2 AXP2101 PMIC 初始化与电池管理板级代码定义了一个继承自Axp2101的内部类Pmicmain/boards/common/axp2101.h在构造函数中通过寄存器写操作完成电源配置WriteReg(0x22, 0b110); // PWRON OFFLEVEL as POWEROFF Source enable WriteReg(0x27, 0x10); // hold 4s to power off // Disable All DCs but DC1 WriteReg(0x80, 0x01); // Disable All LDOs WriteReg(0x90, 0x00); WriteReg(0x91, 0x00); // Set DC1 to 3.3V WriteReg(0x82, (3300 - 1500) / 100); // Set ALDO1 to 3.3V WriteReg(0x92, (3300 - 500) / 100); // Enable ALDO1(MIC) WriteReg(0x90, 0x01); WriteReg(0x64, 0x02); // CV charger voltage setting to 4.1V WriteReg(0x61, 0x02); // set Main battery precharge current to 50mA WriteReg(0x62, 0x08); // set Main battery charger current to 400mA WriteReg(0x63, 0x01); // set Main battery term charge current to 25mA关键配置解读电源按键行为PWRON OFFLEVEL作为关机触发源长按 4 秒关机DC/DC 输出仅保留 DC1 并设为3.3V供主系统使用其余 DC 全部关闭以降低静态功耗LDO 输出默认关闭全部 LDO随后单独使能 ALDO13.3V为MIC麦克风供电充电参数恒压充电截止电压 4.1V预充电电流 50mA主充电电流 400mA终止充电电流 25mA。源码注释还给出了寄存器 0x62 的档位映射0x08-200mA、0x09-300mA、0x0A-400mA即代码中写入 0x08 实际对应 200mA 档位如需更大充电电流可参照注释调整。初始化后InitializeAxp2101()以 I2C 地址0x34创建 PMIC 实例。电池信息通过GetBatteryLevel()对外暴露charging/discharging状态分别来自pmic_-IsCharging()与pmic_-IsDischarging()充电状态变化会实时联动节能定时器的启停。3.3 TCA9554 IO 扩展器LCD 控制信号与按键的桥梁由于 RGB 屏控制线CS/SCL/SDA与物理按键复用了 TCA9554 的 IOInitializeTca9554()按特定时序完成 LCD 上电复位esp_io_expander_new_i2c_tca9554(i2c_bus_, I2C_ADDRESS, io_expander); esp_io_expander_set_dir(io_expander, IO_EXPANDER_PIN_NUM_3|IO_EXPANDER_PIN_NUM_5 | IO_EXPANDER_PIN_NUM_6 , IO_EXPANDER_OUTPUT); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_3, 1); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_6, 0); vTaskDelay(pdMS_TO_TICKS(200)); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_5, 0); vTaskDelay(pdMS_TO_TICKS(200)); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_5, 1); vTaskDelay(pdMS_TO_TICKS(200)); esp_io_expander_set_dir(io_expander, IO_EXPANDER_PIN_NUM_4|IO_EXPANDER_PIN_NUM_6, IO_EXPANDER_INPUT);该过程完成 LCD 的电源使能、复位引脚拉低再拉高的标准复位时序随后将 PIN4 与 PIN6 切换为输入方向供按键检测使用。I2C_ADDRESS在 config.h 中定义为ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000即 TCA9554 地址选择引脚全接低电平时的默认地址。四、480×480 RGB 屏幕与 GT911 触摸显示子系统详解4.1 ST7701 初始化序列与 RGB 面板时序InitializeRGB()中LCD 的命令通道通过 3-wire SPI由 IO 扩展器提供 CS/SCL/SDA建立数据通道则使用 16 位并行 RGB 接口。ST7701 的完整初始化通过lcd_init_cmds[]命令表下发涵盖软复位与唤醒0x11Sleep Out后延时 120msVCOM/电压设置命令0xC0/0xC1/0xC2配置源极/GVDD 电压档位Gamma 校正0xB0/0xB1以及0xE5~0xE8系列命令写入面板厂调校的 Gamma 曲线显示模式0x36Address Control设为 0x00 即不旋转、0x3A像素格式 0x66 即 RGB666显示开启0x21Inversion On后延时 120ms最后0x29Display On。RGB 面板时序参数来自源码 esp32-s3-touch-lcd-4b.cc参数值说明像素时钟pclk_hz16 MHzRGB 接口数据时钟分辨率480×480与 config.h 中DISPLAY_WIDTH/HEIGHT一致行同步 HSYNC脉宽 10 / 后沿 10 / 前沿 20行消隐参数场同步 VSYNC脉宽 10 / 后沿 10 / 前沿 10帧消隐参数数据位宽data_width16RGB565 输入输出帧缓冲num_fbs2双缓冲且fb_in_psram 1帧缓冲位于 PSRAM抖动缓冲bounce_buffer_size_px480×20行级抖动缓冲值得注意的两个细节其一data_width 16而面板像素格式为 RGB66618bit这是 ESP32-S3 RGB LCD 控制器常见的16 位总线承载 6-6-6 数据做法由panel_config.bits_per_pixel 18与rgb_ele_order LCD_RGB_ELEMENT_ORDER_RGB配合完成其二屏幕挂在 16 根 GPIO 上DATA0~DATA15具体引脚映射见 config.h。显示对象最终创建为RgbLcdDisplay类定义见 main/display/lcd_display.hDISPLAY_SWAP_XY、DISPLAY_MIRROR_X/Y均为false偏移为 0即 480×480 方屏按原方向全屏显示。GetDisplay()返回该显示对象由上层 LVGL 界面驱动。4.2 GT911 触摸接入 LVGLInitializeTouch()通过 I2C400kHz挂载 GT911 触摸芯片esp_lcd_panel_io_i2c_config_t tp_io_config { .dev_addr ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS, ... }; tp_io_config.scl_speed_hz 400 * 1000; ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(i2c_bus_, tp_io_config, tp_io_handle)); ESP_ERROR_CHECK(esp_lcd_touch_new_i2c_gt911(tp_io_handle, tp_cfg, tp)); const lvgl_port_touch_cfg_t touch_cfg { .disp lv_display_get_default(), .handle tp, }; lvgl_port_add_touch(touch_cfg);触摸坐标范围按 480×480 设置x_max/y_max DISPLAY_WIDTH - 1等swap_xy、mirror_x/y均为 0 与屏幕方向一致复位与中断引脚均未占用GPIO_NUM_NC。最终通过lvgl_port_add_touch将触摸句柄挂入 LVGL 输入设备实现屏幕点按、滑动等交互例如唤醒设备、切换对话状态等。五、音频通路ES8311 ES7210 双芯片设计GetAudioCodec()返回BoxAudioCodec实现见 main/audio/codecs/box_audio_codec.cc接口见 box_audio_codec.hstatic BoxAudioCodec audio_codec( i2c_bus_, AUDIO_INPUT_SAMPLE_RATE, // 24000 AUDIO_OUTPUT_SAMPLE_RATE, // 24000 AUDIO_I2S_GPIO_MCLK, // GPIO5 AUDIO_I2S_GPIO_BCLK, // GPIO16 AUDIO_I2S_GPIO_WS, // GPIO7 AUDIO_I2S_GPIO_DOUT, // GPIO6 AUDIO_I2S_GPIO_DIN, // GPIO15 AUDIO_CODEC_PA_PIN, // GPIO_NC AUDIO_CODEC_ES8311_ADDR, // ES8311 默认地址 AUDIO_CODEC_ES7210_ADDR, // ES7210 默认地址 AUDIO_INPUT_REFERENCE); // true启用参考输入音频参数来自 config.h输入/输出采样率均为24kHzI2S 使用 MCLK(5)/BCLK(16)/WS(7)/DIN(15)/DOUT(6) 五根信号线。关键设计是AUDIO_INPUT_REFERENCE true——BoxAudioCodec在 ES8311播放与 ES7210录音双芯片基础上叠加参考信号通路为设备端 AEC 提供回声参考这正是config.json中CONFIG_USE_DEVICE_AECy的硬件基础。BoxAudioCodec构造函数还支持input_gain默认 30dB、reference_gain_channel、reference_gain等可调参数本板均使用默认值。六、按键交互单击对话、双击切 AEC、按键回厂6.1 BOOT 按键单击与双击InitializeButtons()为 BOOT 按键GPIO_NUM_0见 config.h注册了回调boot_button_.OnClick([this]() { auto app Application::GetInstance(); if (app.GetDeviceState() kDeviceStateStarting) { EnterWifiConfigMode(); return; } app.ToggleChatState(); }); #if CONFIG_USE_DEVICE_AEC boot_button_.OnDoubleClick([this]() { auto app Application::GetInstance(); if (app.GetDeviceState() kDeviceStateIdle) { app.SetAecMode(app.GetAecMode() kAecOff ? kAecOnDeviceSide : kAecOff); } }); #endif单击设备处于启动状态时进入 WiFi 配置模式配网否则切换对话状态开始/结束对话双击仅当CONFIG_USE_DEVICE_AECy编译生效空闲状态下在设备端 AEC 关闭与设备端 AEC 开启之间切换方便现场对比回声消除效果。6.2 物理按键轮询短按回滚出厂分区除 BOOT 按键外板载另一颗物理按键通过 TCA9554 的 PIN4 读取。InitializeKeyMonitor()创建一个固定运行在 Core 0、优先级 5 的任务key_monitor_task每 20ms 调用一次CheckKeyState()检测电平变化并计时短按1000ms查找ESP_PARTITION_SUBTYPE_APP_FACTORY出厂分区若存在则调用esp_ota_set_boot_partition(factory_partition)将其设为启动分区并esp_restart()重启实现一键回滚到出厂固件的恢复机制长按≥1000ms记录时长但不执行动作。从源码结构看该轮询逻辑独立于Button框架使用原始 GPIO 电平 时间戳判断说明这颗按键被设计为仅用于紧急恢复场景避免与正常交互逻辑耦合。七、MCP 工具注册语音侧的可编程能力InitializeTools()展示了 xiaozhi-esp32 的 MCP 能力如何与板级功能结合auto mcp_server McpServer::GetInstance(); mcp_server.AddTool(self.system.reconfigure_wifi, End this conversation and enter WiFi configuration mode.\n **CAUTION** You must ask the user to confirm this action., PropertyList(), this { EnterWifiConfigMode(); return true; });该板向 MCP 服务器注册了self.system.reconfigure_wifi工具使大模型在对话中经用户确认后可以主动调用它来结束当前会话并进入 WiFi 配网模式。这体现了本项目MCP-based chatbot的定位——main/mcp_server.cc 提供 MCP 服务端实现板级代码通过McpServer::GetInstance()注入自定义工具扩展设备的语音可控能力。关于 MCP 协议与用法可进一步参考 docs/mcp-protocol.md 与 docs/mcp-usage.md。八、编译、烧录与部署要点将上述板级适配落到实际固件推荐步骤如下准备环境安装 ESP-IDF建议使用仓库要求的版本可参考仓库根目录 README.md克隆 xiaozhi-esp32 仓库并进入main目录设定目标芯片执行idf.py set-target esp32s34B 板型在 Kconfig 中强制依赖 esp32s3选择板型执行idf.py menuconfig进入Xiaozhi Assistant -- Board Type勾选Waveshare ESP32-S3-Touch-LCD-4B可选配置确认确认CONFIG_USE_DEVICE_AECy与CONFIG_USE_WECHAT_MESSAGE_STYLEn生效默认已由 config.json 的sdkconfig_append注入编译烧录执行idf.py build flash monitor完成构建、烧录与串口日志观察。首次上电后设备会进入配网流程BOOT 按键或 MCP 工具均可触发 WiFi 配置模式连接网络后即可与后端服务建立 WebSocket/MQTT 会话开始语音对话。分区分案可参考仓库 partitions/ 目录下的 CSV 文件480×480 屏幕 Emoji 资源对 Flash 占用较大建议使用 8MB 及以上的分区方案。九、小结Waveshare ESP32-S3-Touch-LCD-4B 的适配展示了 xiaozhi-esp32 板级抽象层的完整用法继承WifiBoard、用DECLARE_BOARD注册、在构造函数中按序初始化 PMIC/IO 扩展/RGB 屏/触摸/音频/按键并通过虚函数GetAudioCodec、GetDisplay、GetBacklight、GetBatteryLevel、SetPowerSaveLevel接入固件核心框架。本文涉及的关键源码路径汇总如下供进一步研读板级实现main/boards/waveshare/esp32-s3-touch-lcd-4b/esp32-s3-touch-lcd-4b.cc引脚与参数定义main/boards/waveshare/esp32-s3-touch-lcd-4b/config.h构建元数据main/boards/waveshare/esp32-s3-touch-lcd-4b/config.jsonKconfig 板型注册main/Kconfig.projbuildCMake 板型映射与字体资源main/CMakeLists.txt板基类与工厂宏main/boards/common/board.h节能定时器main/boards/common/power_save_timer.h显示抽象与 RGB 显示类main/display/lcd_display.h音频编解码封装main/audio/codecs/box_audio_codec.h【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaozhi-esp32 接入 Waveshare ESP32-S3-Touch-LCD-4B：86 盒形态的 MCP 聊天机器人板级适配指南
xiaozhi-esp32 接入 Waveshare ESP32-S3-Touch-LCD-4B86 盒形态的 MCP 聊天机器人板级适配指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文基于 xiaozhi-esp32 开源仓库讲解如何将 Waveshare ESP32-S3-Touch-LCD-4B基于 ESP32-S3 的 86 智能面板开发板接入小智 AI 聊天机器人固件。文章以该开发板的官方适配文档为核心骨架结合 板级源码、引脚配置 与 构建配置 展开完整覆盖 menuconfig 选择流程、硬件资源初始化、显示/触摸/音频/电源管理链路与按键交互逻辑读者可据此自行编译固件并完成该开发板的部署与二次开发。一、开发板概况一款带 480×480 电容触摸屏的智能 86 盒Waveshare微雪电子设计的 ESP32-S3-Touch-LCD-4B 是一款以 ESP32-S3 模组为核心的智能 86 盒86 box即标准 86 型墙壁开关面板尺寸的嵌入式设备形态核心硬件特征为480×480 IPS 电容触摸屏采用 ST7701 驱动 ICRGB 接口16 位数据总线输出触摸部分使用 GT911 触控 IC通过 I2C 与主控通信搭载 AXP2101 电源管理芯片PMIC负责电池充放电管理与系统上下电音频通路采用 ES8311音频编解码 ES7210ADC组合支持回声消除参考输入配备 TCA9554 IO 扩展器用于驱动 LCD 控制信号线与按键检测。该板在 xiaozhi-esp32 中属于WifiBoard家族的成员即依靠 WiFi 联网、无 4G 蜂窝模块的典型交互设备形态适合作为桌面/墙装形态的语音对话终端。其仓库适配文件位于 main/boards/waveshare/esp32-s3-touch-lcd-4b/包含四个文件文件作用README.md官方板级适配说明即本文所依据的关联文档esp32-s3-touch-lcd-4b.cc板级实现声明并注册WaveshareEsp32s3TouchLCD4b板类config.h引脚定义与屏幕/音频参数宏config.json固件构建元数据目标芯片、sdkconfig 附加项二、启用该开发板menuconfig 配置步骤官方文档给出的启用方式非常简洁——在 ESP-IDF 的menuconfig中完成板型选择执行idf.py menuconfig打开配置界面依次进入Xiaozhi Assistant -- Board Type在板型列表中勾选Waveshare ESP32-S3-Touch-LCD-4B保存退出后正常编译烧录即可。该选项在源码中的真实存在可由 main/Kconfig.projbuild 印证config BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_4B bool Waveshare ESP32-S3-Touch-LCD-4B depends on IDF_TARGET_ESP32S3注意其depends on IDF_TARGET_ESP32S3条件该板型仅支持 ESP32-S3 目标芯片因此在编译前需先通过idf.py set-target esp32s3或首次构建时指定将目标芯片设置为 esp32s3。选中该配置后main/CMakeLists.txt 会将BOARD_DIR指向waveshare/esp32-s3-touch-lcd-4b目录并启用对应字体资源elseif(CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_4B) set(BOARD_DIR waveshare/esp32-s3-touch-lcd-4b) set(BUILTIN_TEXT_FONT font_noto_sans_basic_30_4) set(BUILTIN_ICON_FONT font_material_symbols_30_4) set(DEFAULT_EMOJI_COLLECTION noto-color-emoji_64)从该片段可以推断4B 板型使用了font_noto_sans_basic_30_4基础字体、font_material_symbols_30_4图标字体以及 64px 的彩色 Emoji 资源与同尺寸的 480×480 屏幕板型保持一致。构建元数据方面config.json 声明了该板型的固件构建配置{ manufacturer: waveshare, type: esp32-s3-touch-lcd-4b, target: esp32s3, builds: [ { name: esp32-s3-touch-lcd-4b, sdkconfig_append: [ CONFIG_USE_WECHAT_MESSAGE_STYLEn, CONFIG_USE_DEVICE_AECy ] } ] }其中两个 sdkconfig 附加项含义如下CONFIG_USE_WECHAT_MESSAGE_STYLEn关闭微信气泡消息风格 UI使用默认的对话界面样式CONFIG_USE_DEVICE_AECy启用设备端回声消除Acoustic Echo Cancellation。该选项开启后板级代码会额外编译 BOOT 按键双击切换 AEC 模式的逻辑见下文按键交互章节同时音频通路会利用 ES7210 的参考信号做回声消除提升语音对话体验。三、板级实现剖析从启动到外设初始化的完整链路板级适配的核心是 esp32-s3-touch-lcd-4b.cc 中的WaveshareEsp32s3TouchLCD4b类。该类继承自WifiBoard定义于 main/boards/common/wifi_board.h并通过文件末尾的DECLARE_BOARD(WaveshareEsp32s3TouchLCD4b)宏注册为工厂实例。DECLARE_BOARD宏定义在 main/boards/common/board.h展开后生成create_board()工厂函数供Board::GetInstance()创建单例。构造函数按以下顺序完成全部外设初始化WaveshareEsp32s3TouchLCD4b() : boot_button_(BOOT_BUTTON_GPIO) { InitializePowerSaveTimer(); InitializeCodecI2c(); InitializeTca9554(); InitializeAxp2101(); InitializeRGB(); InitializeTouch(); InitializeButtons(); InitializeTools(); InitializeKeyMonitor(); GetBacklight()-SetBrightness(100); }各步骤职责如下初始化步骤对应函数职责电源节能InitializePowerSaveTimer()创建节能定时器绑定睡眠/唤醒/关机回调音频 I2C 总线InitializeCodecI2c()创建 I2C 主总线供音频编解码器与触摸芯片使用IO 扩展器InitializeTca9554()初始化 TCA9554控制 LCD 控制信号并配置按键引脚电源管理InitializeAxp2101()初始化 AXP2101 PMIC配置输出电压与充电参数RGB 屏幕InitializeRGB()初始化 ST7701 LCD 面板RGB 接口并创建显示对象触摸屏InitializeTouch()初始化 GT911 触摸控制器并挂载到 LVGL按键InitializeButtons()注册 BOOT 按键单击/双击回调MCP 工具InitializeTools()向 MCP 服务器注册 WiFi 重配置工具按键轮询InitializeKeyMonitor()启动独立任务监听物理按键时长3.1 电源节能与 PMIC 联动InitializePowerSaveTimer()创建了一个PowerSaveTimer其接口见 main/boards/common/power_save_timer.hpower_save_timer_ new PowerSaveTimer(-1, 60, 300);三个参数依次为CPU 最大频率限制-1 表示不限制、空闲 60 秒进入睡眠模式、空闲 300 秒触发关机请求。睡眠与唤醒回调分别通过SetPowerSaveMode与背光亮度调节实现power_save_timer_-OnEnterSleepMode([this]() { GetDisplay()-SetPowerSaveMode(true); GetBacklight()-SetBrightness(70); }); power_save_timer_-OnExitSleepMode([this]() { GetDisplay()-SetPowerSaveMode(false); GetBacklight()-RestoreBrightness(); }); power_save_timer_-OnShutdownRequest([this](){ pmic_-PowerOff(); });即进入睡眠时屏幕进入省电模式且背光降为 70唤醒时恢复背光若 300 秒内未唤醒则直接调用 PMIC 的PowerOff()关机。此外GetBatteryLevel() 中还有一个细节仅在设备处于**放电未插电**状态时才启用节能定时器插电充电时禁用节能逻辑避免充电过程中设备频繁进入睡眠。SetPowerSaveLevel覆盖了基类接口处理LOW_POWER之外所有档位时先唤醒节能定时器再交回WifiBoard处理保证对话状态下设备始终处于唤醒可交互状态。3.2 AXP2101 PMIC 初始化与电池管理板级代码定义了一个继承自Axp2101的内部类Pmicmain/boards/common/axp2101.h在构造函数中通过寄存器写操作完成电源配置WriteReg(0x22, 0b110); // PWRON OFFLEVEL as POWEROFF Source enable WriteReg(0x27, 0x10); // hold 4s to power off // Disable All DCs but DC1 WriteReg(0x80, 0x01); // Disable All LDOs WriteReg(0x90, 0x00); WriteReg(0x91, 0x00); // Set DC1 to 3.3V WriteReg(0x82, (3300 - 1500) / 100); // Set ALDO1 to 3.3V WriteReg(0x92, (3300 - 500) / 100); // Enable ALDO1(MIC) WriteReg(0x90, 0x01); WriteReg(0x64, 0x02); // CV charger voltage setting to 4.1V WriteReg(0x61, 0x02); // set Main battery precharge current to 50mA WriteReg(0x62, 0x08); // set Main battery charger current to 400mA WriteReg(0x63, 0x01); // set Main battery term charge current to 25mA关键配置解读电源按键行为PWRON OFFLEVEL作为关机触发源长按 4 秒关机DC/DC 输出仅保留 DC1 并设为3.3V供主系统使用其余 DC 全部关闭以降低静态功耗LDO 输出默认关闭全部 LDO随后单独使能 ALDO13.3V为MIC麦克风供电充电参数恒压充电截止电压 4.1V预充电电流 50mA主充电电流 400mA终止充电电流 25mA。源码注释还给出了寄存器 0x62 的档位映射0x08-200mA、0x09-300mA、0x0A-400mA即代码中写入 0x08 实际对应 200mA 档位如需更大充电电流可参照注释调整。初始化后InitializeAxp2101()以 I2C 地址0x34创建 PMIC 实例。电池信息通过GetBatteryLevel()对外暴露charging/discharging状态分别来自pmic_-IsCharging()与pmic_-IsDischarging()充电状态变化会实时联动节能定时器的启停。3.3 TCA9554 IO 扩展器LCD 控制信号与按键的桥梁由于 RGB 屏控制线CS/SCL/SDA与物理按键复用了 TCA9554 的 IOInitializeTca9554()按特定时序完成 LCD 上电复位esp_io_expander_new_i2c_tca9554(i2c_bus_, I2C_ADDRESS, io_expander); esp_io_expander_set_dir(io_expander, IO_EXPANDER_PIN_NUM_3|IO_EXPANDER_PIN_NUM_5 | IO_EXPANDER_PIN_NUM_6 , IO_EXPANDER_OUTPUT); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_3, 1); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_6, 0); vTaskDelay(pdMS_TO_TICKS(200)); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_5, 0); vTaskDelay(pdMS_TO_TICKS(200)); esp_io_expander_set_level(io_expander, IO_EXPANDER_PIN_NUM_5, 1); vTaskDelay(pdMS_TO_TICKS(200)); esp_io_expander_set_dir(io_expander, IO_EXPANDER_PIN_NUM_4|IO_EXPANDER_PIN_NUM_6, IO_EXPANDER_INPUT);该过程完成 LCD 的电源使能、复位引脚拉低再拉高的标准复位时序随后将 PIN4 与 PIN6 切换为输入方向供按键检测使用。I2C_ADDRESS在 config.h 中定义为ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000即 TCA9554 地址选择引脚全接低电平时的默认地址。四、480×480 RGB 屏幕与 GT911 触摸显示子系统详解4.1 ST7701 初始化序列与 RGB 面板时序InitializeRGB()中LCD 的命令通道通过 3-wire SPI由 IO 扩展器提供 CS/SCL/SDA建立数据通道则使用 16 位并行 RGB 接口。ST7701 的完整初始化通过lcd_init_cmds[]命令表下发涵盖软复位与唤醒0x11Sleep Out后延时 120msVCOM/电压设置命令0xC0/0xC1/0xC2配置源极/GVDD 电压档位Gamma 校正0xB0/0xB1以及0xE5~0xE8系列命令写入面板厂调校的 Gamma 曲线显示模式0x36Address Control设为 0x00 即不旋转、0x3A像素格式 0x66 即 RGB666显示开启0x21Inversion On后延时 120ms最后0x29Display On。RGB 面板时序参数来自源码 esp32-s3-touch-lcd-4b.cc参数值说明像素时钟pclk_hz16 MHzRGB 接口数据时钟分辨率480×480与 config.h 中DISPLAY_WIDTH/HEIGHT一致行同步 HSYNC脉宽 10 / 后沿 10 / 前沿 20行消隐参数场同步 VSYNC脉宽 10 / 后沿 10 / 前沿 10帧消隐参数数据位宽data_width16RGB565 输入输出帧缓冲num_fbs2双缓冲且fb_in_psram 1帧缓冲位于 PSRAM抖动缓冲bounce_buffer_size_px480×20行级抖动缓冲值得注意的两个细节其一data_width 16而面板像素格式为 RGB66618bit这是 ESP32-S3 RGB LCD 控制器常见的16 位总线承载 6-6-6 数据做法由panel_config.bits_per_pixel 18与rgb_ele_order LCD_RGB_ELEMENT_ORDER_RGB配合完成其二屏幕挂在 16 根 GPIO 上DATA0~DATA15具体引脚映射见 config.h。显示对象最终创建为RgbLcdDisplay类定义见 main/display/lcd_display.hDISPLAY_SWAP_XY、DISPLAY_MIRROR_X/Y均为false偏移为 0即 480×480 方屏按原方向全屏显示。GetDisplay()返回该显示对象由上层 LVGL 界面驱动。4.2 GT911 触摸接入 LVGLInitializeTouch()通过 I2C400kHz挂载 GT911 触摸芯片esp_lcd_panel_io_i2c_config_t tp_io_config { .dev_addr ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS, ... }; tp_io_config.scl_speed_hz 400 * 1000; ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(i2c_bus_, tp_io_config, tp_io_handle)); ESP_ERROR_CHECK(esp_lcd_touch_new_i2c_gt911(tp_io_handle, tp_cfg, tp)); const lvgl_port_touch_cfg_t touch_cfg { .disp lv_display_get_default(), .handle tp, }; lvgl_port_add_touch(touch_cfg);触摸坐标范围按 480×480 设置x_max/y_max DISPLAY_WIDTH - 1等swap_xy、mirror_x/y均为 0 与屏幕方向一致复位与中断引脚均未占用GPIO_NUM_NC。最终通过lvgl_port_add_touch将触摸句柄挂入 LVGL 输入设备实现屏幕点按、滑动等交互例如唤醒设备、切换对话状态等。五、音频通路ES8311 ES7210 双芯片设计GetAudioCodec()返回BoxAudioCodec实现见 main/audio/codecs/box_audio_codec.cc接口见 box_audio_codec.hstatic BoxAudioCodec audio_codec( i2c_bus_, AUDIO_INPUT_SAMPLE_RATE, // 24000 AUDIO_OUTPUT_SAMPLE_RATE, // 24000 AUDIO_I2S_GPIO_MCLK, // GPIO5 AUDIO_I2S_GPIO_BCLK, // GPIO16 AUDIO_I2S_GPIO_WS, // GPIO7 AUDIO_I2S_GPIO_DOUT, // GPIO6 AUDIO_I2S_GPIO_DIN, // GPIO15 AUDIO_CODEC_PA_PIN, // GPIO_NC AUDIO_CODEC_ES8311_ADDR, // ES8311 默认地址 AUDIO_CODEC_ES7210_ADDR, // ES7210 默认地址 AUDIO_INPUT_REFERENCE); // true启用参考输入音频参数来自 config.h输入/输出采样率均为24kHzI2S 使用 MCLK(5)/BCLK(16)/WS(7)/DIN(15)/DOUT(6) 五根信号线。关键设计是AUDIO_INPUT_REFERENCE true——BoxAudioCodec在 ES8311播放与 ES7210录音双芯片基础上叠加参考信号通路为设备端 AEC 提供回声参考这正是config.json中CONFIG_USE_DEVICE_AECy的硬件基础。BoxAudioCodec构造函数还支持input_gain默认 30dB、reference_gain_channel、reference_gain等可调参数本板均使用默认值。六、按键交互单击对话、双击切 AEC、按键回厂6.1 BOOT 按键单击与双击InitializeButtons()为 BOOT 按键GPIO_NUM_0见 config.h注册了回调boot_button_.OnClick([this]() { auto app Application::GetInstance(); if (app.GetDeviceState() kDeviceStateStarting) { EnterWifiConfigMode(); return; } app.ToggleChatState(); }); #if CONFIG_USE_DEVICE_AEC boot_button_.OnDoubleClick([this]() { auto app Application::GetInstance(); if (app.GetDeviceState() kDeviceStateIdle) { app.SetAecMode(app.GetAecMode() kAecOff ? kAecOnDeviceSide : kAecOff); } }); #endif单击设备处于启动状态时进入 WiFi 配置模式配网否则切换对话状态开始/结束对话双击仅当CONFIG_USE_DEVICE_AECy编译生效空闲状态下在设备端 AEC 关闭与设备端 AEC 开启之间切换方便现场对比回声消除效果。6.2 物理按键轮询短按回滚出厂分区除 BOOT 按键外板载另一颗物理按键通过 TCA9554 的 PIN4 读取。InitializeKeyMonitor()创建一个固定运行在 Core 0、优先级 5 的任务key_monitor_task每 20ms 调用一次CheckKeyState()检测电平变化并计时短按1000ms查找ESP_PARTITION_SUBTYPE_APP_FACTORY出厂分区若存在则调用esp_ota_set_boot_partition(factory_partition)将其设为启动分区并esp_restart()重启实现一键回滚到出厂固件的恢复机制长按≥1000ms记录时长但不执行动作。从源码结构看该轮询逻辑独立于Button框架使用原始 GPIO 电平 时间戳判断说明这颗按键被设计为仅用于紧急恢复场景避免与正常交互逻辑耦合。七、MCP 工具注册语音侧的可编程能力InitializeTools()展示了 xiaozhi-esp32 的 MCP 能力如何与板级功能结合auto mcp_server McpServer::GetInstance(); mcp_server.AddTool(self.system.reconfigure_wifi, End this conversation and enter WiFi configuration mode.\n **CAUTION** You must ask the user to confirm this action., PropertyList(), this { EnterWifiConfigMode(); return true; });该板向 MCP 服务器注册了self.system.reconfigure_wifi工具使大模型在对话中经用户确认后可以主动调用它来结束当前会话并进入 WiFi 配网模式。这体现了本项目MCP-based chatbot的定位——main/mcp_server.cc 提供 MCP 服务端实现板级代码通过McpServer::GetInstance()注入自定义工具扩展设备的语音可控能力。关于 MCP 协议与用法可进一步参考 docs/mcp-protocol.md 与 docs/mcp-usage.md。八、编译、烧录与部署要点将上述板级适配落到实际固件推荐步骤如下准备环境安装 ESP-IDF建议使用仓库要求的版本可参考仓库根目录 README.md克隆 xiaozhi-esp32 仓库并进入main目录设定目标芯片执行idf.py set-target esp32s34B 板型在 Kconfig 中强制依赖 esp32s3选择板型执行idf.py menuconfig进入Xiaozhi Assistant -- Board Type勾选Waveshare ESP32-S3-Touch-LCD-4B可选配置确认确认CONFIG_USE_DEVICE_AECy与CONFIG_USE_WECHAT_MESSAGE_STYLEn生效默认已由 config.json 的sdkconfig_append注入编译烧录执行idf.py build flash monitor完成构建、烧录与串口日志观察。首次上电后设备会进入配网流程BOOT 按键或 MCP 工具均可触发 WiFi 配置模式连接网络后即可与后端服务建立 WebSocket/MQTT 会话开始语音对话。分区分案可参考仓库 partitions/ 目录下的 CSV 文件480×480 屏幕 Emoji 资源对 Flash 占用较大建议使用 8MB 及以上的分区方案。九、小结Waveshare ESP32-S3-Touch-LCD-4B 的适配展示了 xiaozhi-esp32 板级抽象层的完整用法继承WifiBoard、用DECLARE_BOARD注册、在构造函数中按序初始化 PMIC/IO 扩展/RGB 屏/触摸/音频/按键并通过虚函数GetAudioCodec、GetDisplay、GetBacklight、GetBatteryLevel、SetPowerSaveLevel接入固件核心框架。本文涉及的关键源码路径汇总如下供进一步研读板级实现main/boards/waveshare/esp32-s3-touch-lcd-4b/esp32-s3-touch-lcd-4b.cc引脚与参数定义main/boards/waveshare/esp32-s3-touch-lcd-4b/config.h构建元数据main/boards/waveshare/esp32-s3-touch-lcd-4b/config.jsonKconfig 板型注册main/Kconfig.projbuildCMake 板型映射与字体资源main/CMakeLists.txt板基类与工厂宏main/boards/common/board.h节能定时器main/boards/common/power_save_timer.h显示抽象与 RGB 显示类main/display/lcd_display.h音频编解码封装main/audio/codecs/box_audio_codec.h【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考