xiaozhi-esp32 适配 Waveshare ESP32-S3-Touch-LCD-1.83：从硬件配置到固件构建实战指南-开发者社区

xiaozhi-esp32 适配 Waveshare ESP32-S3-Touch-LCD-1.83：从硬件配置到固件构建实战指南

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

导读

本文基于 xiaozhi-esp32 开源项目中的 Waveshare 开发板适配目录（main/boards/waveshare/esp32-s3-touch-lcd-1.83），完整讲解这块 1.83 英寸电容触摸屏开发板在项目中的硬件资源配置、板级驱动实现（电源管理、音频编解码、SPI LCD、触摸屏、按键交互）以及固件编译烧录流程。读完本文，你将掌握如何为 xiaozhi-esp32 添加一块触摸屏板卡、理解其板级代码的初始化调用链，并能独立完成该板固件的构建与烧录。

一、开发板概述与项目适配背景

Waveshare ESP32-S3-Touch-LCD-1.83 是微雪（Waveshare）设计的一款高性能、高度集成化的微控制器开发板：板载尺寸紧凑，配备1.83 英寸电容触摸 LCD 屏、高度集成的电源管理芯片、六轴传感器（三轴加速度计 + 三轴陀螺仪）、RTC 以及低功耗音频编解码芯片等，便于开发调试，也易于嵌入到产品中（原文描述见 README.md）。

在 xiaozhi-esp32 项目中，该板卡拥有完整的板级适配，包含四个文件：

文件	作用
README.md	板卡简介与硬件介绍
config.h	板级硬件引脚与显示参数宏定义
config.json	板卡构建元信息（厂商、类型、目标芯片、SDK 配置追加项）
esp32-s3-touch-lcd-1.83.cc	板级驱动实现（继承`WifiBoard`的完整初始化逻辑）

项目的构建系统通过 main/CMakeLists.txt 将该板卡纳入编译：当选择CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_1_83时，设置BOARD_DIR为waveshare/esp32-s3-touch-lcd-1.83，并选用适合小尺寸屏的内置字体font_noto_sans_basic_16_4与图标字体font_material_symbols_16_4，表情符号集合使用noto-color-emoji_64。

二、构建元信息与默认配置（config.json）

config.json 声明了该板卡的构建方式：

{ "manufacturer": "waveshare", "type": "esp32-s3-touch-lcd-1.83", "target": "esp32s3", "builds": [ { "name": "esp32-s3-touch-lcd-1.83", "sdkconfig_append": [ "CONFIG_USE_WECHAT_MESSAGE_STYLE=n", "CONFIG_USE_DEVICE_AEC=y" ] } ] }

关键字段说明：

target：esp32s3—— 该板卡必须以 ESP32-S3 为目标芯片构建。对应 Kconfig.projbuild 中的BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_1_83选项，其depends on IDF_TARGET_ESP32S3，即在 menuconfig 中该板卡仅在目标芯片为 ESP32-S3 时可选。
sdkconfig_append：构建时自动追加的两条 SDK 配置：
- CONFIG_USE_WECHAT_MESSAGE_STYLE=n：关闭「微信消息样式」。该选项属于 Kconfig.projbuild 中的DISPLAY_STYLE选择组（可选USE_DEFAULT_MESSAGE_STYLE、USE_WECHAT_MESSAGE_STYLE、USE_EMOTE_MESSAGE_STYLE），这里显式指定使用默认消息样式而非微信气泡样式。
- CONFIG_USE_DEVICE_AEC=y：启用设备端回声消除（AEC）。该选项依赖USE_AUDIO_PROCESSOR，且板卡类型需在 Kconfig.projbuild 的白名单内——BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_LCD_1_83正在其中。配置说明指出：设备端 AEC 正常工作需要扬声器信号具有干净的输出参考通路，且麦克风与扬声器之间具备物理声学隔离。

三、硬件资源与引脚映射（config.h）

config.h 集中定义了该板卡的硬件资源，是理解板级代码的入口。

3.1 音频通路

#define AUDIO_INPUT_SAMPLE_RATE 24000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 #define AUDIO_INPUT_REFERENCE true #define AUDIO_I2S_GPIO_MCLK GPIO_NUM_16 #define AUDIO_I2S_GPIO_WS GPIO_NUM_45 #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_9 #define AUDIO_I2S_GPIO_DIN GPIO_NUM_10 #define AUDIO_I2S_GPIO_DOUT GPIO_NUM_8 #define AUDIO_CODEC_PA_PIN GPIO_NUM_46 #define AUDIO_CODEC_I2C_SDA_PIN GPIO_NUM_15 #define AUDIO_CODEC_I2C_SCL_PIN GPIO_NUM_14 #define AUDIO_CODEC_ES8311_ADDR ES8311_CODEC_DEFAULT_ADDR #define AUDIO_CODEC_ES7210_ADDR ES7210_CODEC_DEFAULT_ADDR

采样率统一为24 kHz，AUDIO_INPUT_REFERENCE为true，表示麦克风输入携带参考通路，用于回声消除。这一点与 box_audio_codec.h 的构造语义一致：input_reference为真时输入通道数变为 2（参见 box_audio_codec.cc 中的input_channels_ = input_reference_ ? 2 : 1）。
音频编解码采用ES8311（DAC 输出）+ ES7210（ADC 输入）双芯片方案，通过 I2C 控制（SDA=15，SCL=14），I2S 负责音频数据传输，PA 功放使能脚为 GPIO 46。

3.2 按键

#define BOOT_BUTTON_GPIO GPIO_NUM_0 #define PWR_BUTTON_GPIO GPIO_NUM_41

BOOT 按键（GPIO 0）：用于交互控制（详见下文按键逻辑）。
PWR 按键（GPIO 41）：电源键，配合 AXP2101 电源管理芯片实现开机/关机。

3.3 显示屏与背光

#define DISPLAY_SPI_MODE 3 #define DISPLAY_CS_PIN GPIO_NUM_5 #define DISPLAY_MOSI_PIN GPIO_NUM_7 #define DISPLAY_MISO_PIN GPIO_NUM_NC #define DISPLAY_CLK_PIN GPIO_NUM_6 #define DISPLAY_DC_PIN GPIO_NUM_4 #define DISPLAY_RST_PIN GPIO_NUM_38 #define DISPLAY_WIDTH 240 #define DISPLAY_HEIGHT 284 #define DISPLAY_MIRROR_X false #define DISPLAY_MIRROR_Y false #define DISPLAY_SWAP_XY false #define DISPLAY_OFFSET_X 0 #define DISPLAY_OFFSET_Y 0 #define DISPLAY_BACKLIGHT_PIN GPIO_NUM_40 #define DISPLAY_BACKLIGHT_OUTPUT_INVERT false

屏幕为240×284分辨率的 SPI 电容触摸屏，SPI 时钟/数据引脚为 CLK=6、MOSI=7、CS=5，DC=4，复位=38，MISO 未使用（GPIO_NUM_NC）。
未启用镜像（MIRROR_X/Y、SWAP_XY均为false），偏移量为 0。
背光为 PWM 控制（GPIO 40），输出极性不反相。

四、板级驱动实现源码剖析

板级实现位于 esp32-s3-touch-lcd-1.83.cc，核心类WaveshareEsp32s3TouchLCD1inch83继承自WifiBoard（WiFi 开发板基类，定义于 main/boards/common/wifi_board.h），通过DECLARE_BOARD宏注册。构造函数依次完成如下初始化：

InitializePowerSaveTimer → InitializeCodecI2c → InitializeAxp2101 → InitializeSpi → InitializeDisplay → InitializeTouch → InitializeButtons → InitializeTools

4.1 电源管理：AXP2101 定制初始化

板卡通过 I2C 总线（SDA=15、SCL=14，内部上拉，参见InitializeCodecI2c）连接AXP2101电源管理芯片（I2C 地址0x34）。源码中定义了Pmic子类，在构造时写入寄存器完成关键配置：

0x22 = 0b110：使能 PWRON 按键关机源；
0x27 = 0x10：长按 4 秒关机；
0x80 = 0x01：除 DC1 外禁用所有 DC-DC；
0x90/0x91 = 0x00：禁用所有 LDO，随后仅使能 ALDO1（麦克风供电）；
0x82：DC1 输出电压设为3.3V（(3300 - 1500) / 100）；
0x92：ALDO1 输出设为3.3V；
0x64 = 0x02：充电 CV 电压设为4.1V；
0x61/0x62/0x63：预充电电流 50mA、主充电电流 400mA（0x0A）、终止充电电流 25mA。

运行时通过Axp2101的公开接口（见 main/boards/common/axp2101.h）查询IsCharging()、IsDischarging()、GetBatteryLevel()并调用PowerOff()关机。

4.2 电源节省策略：PowerSaveTimer

InitializePowerSaveTimer创建了PowerSaveTimer(-1, 60, 300)（见 main/boards/common/power_save_timer.h，构造参数为 CPU 最大频率、休眠秒数、关机秒数）：

60 秒无操作进入休眠：屏幕开启SetPowerSaveMode(true)，背光降为亮度 20；
唤醒时恢复屏幕与背光；
300 秒触发关机请求，调用pmic_->PowerOff()真正断电；
定时器仅在电池放电状态下启用：GetBatteryLevel()中监测放电状态变化，放电时才SetEnabled(true)（见 esp32-s3-touch-lcd-1.83.cc 的GetBatteryLevel重写），充电状态下不会自动休眠/关机。

4.3 音频编解码：BoxAudioCodec

GetAudioCodec()返回BoxAudioCodec实例，参数来自config.h的音频定义。BoxAudioCodec（main/audio/codecs/box_audio_codec.h）使用 ESP-IDF 的esp_codec_dev框架：

输出通路：ES8311 以 DAC 模式工作（ESP_CODEC_DEV_WORK_MODE_DAC），启用 MCLK，PA 引脚为 GPIO 46，PA 电压 5.0V、DAC 电压 3.3V；
输入通路：ES7210 承担 ADC 采集，配合input_reference=true实现双通道参考输入，为设备端 AEC 提供回声参考信号；
I2S 采用 TDM 双工通道（CreateDuplexChannels），与「全双工对话」能力对应。

4.4 显示与触摸：ST7789 + CST816S

显示初始化（InitializeDisplay）：使用 SPI3 主机（SPI3_HOST），SPI 时钟 24 MHz，8 位命令/参数位，驱动芯片为ST7789（esp_lcd_new_panel_st7789），16 位 RGB 像素、LCD_RGB_ELEMENT_ORDER_RGB，初始化后调用esp_lcd_panel_invert_color(panel, true)反色并点亮。随后创建SpiLcdDisplay（定义于 main/display/lcd_display.h），将 240×284 分辨率与偏移/镜像参数传入 LVGL 显示层。

触摸初始化（InitializeTouch）：触摸控制芯片为CST816S（esp_lcd_touch_new_i2c_cst816s），通过 I2C 通信（地址ESP_LCD_TOUCH_IO_I2C_CST816S_ADDRESS，400 kHz），复位脚 GPIO 39、中断脚 GPIO 13；触摸坐标范围按屏幕尺寸配置（x 0~239、y 0~283），随后通过lvgl_port_add_touch注册到 LVGL，实现电容触摸交互。

4.5 按键交互逻辑

boot_button_（GPIO 0，见 main/boards/common/button.h 的Button类）注册了：

单击：若设备处于kDeviceStateStarting（启动中），进入 WiFi 配网模式EnterWifiConfigMode()；否则切换对话状态ToggleChatState()（开始/结束对话）。
双击（在CONFIG_USE_DEVICE_AEC启用时编译）：当设备处于空闲态kDeviceStateIdle时，切换设备端 AEC 模式（kAecOnDeviceSide与kAecOff之间）。这正是 config.json 中启用CONFIG_USE_DEVICE_AEC=y的配套交互：用户可通过双击 BOOT 键快捷开关设备端回声消除。

4.6 MCP 工具注册

InitializeTools通过项目内置的 MCP 服务器（McpServer，见 main/mcp_server.h）注册了self.system.reconfigure_wifi工具：当 AI 对话需要重新配置 WiFi 时，可调用该工具结束当前对话并进入 WiFi 配网模式，且工具描述明确要求 AI 先向用户确认后再执行。

五、构建与烧录

该板卡的构建方式与项目中其他板卡一致，前提是已安装 ESP-IDF 开发环境（目标版本esp32s3）。

方式一：idf.py 手动构建

设置目标芯片：
```
idf.py set-target esp32s3
```
清理旧配置（切换目标后建议执行）：
```
idf.py fullclean
```
打开配置菜单选择板卡：
```
idf.py menuconfig
```
进入Xiaozhi Assistant -> Board Type，选择Waveshare ESP32-S3-Touch-LCD-1.83。该选项依赖IDF_TARGET_ESP32S3，确保第一步的 target 正确（参考 Kconfig.projbuild）。
编译并烧录运行：
```
idf.py build idf.py flash monitor
```
（完整流程可参考 docs/custom-board.md 的 Build and Flash 章节。）

方式二：build.py 自动构建

由于板卡目录包含config.json，也可以使用项目提供的自动构建脚本（scripts/build.py）：

python scripts/build.py esp32-s3-touch-lcd-1.83

脚本会读取config.json中的target（esp32s3）与sdkconfig_append（关闭微信消息样式、启用设备端 AEC），自动完成配置并编译；还可附加语言与唤醒词参数：

python scripts/build.py esp32-s3-touch-lcd-1.83 --language zh-CN --wake-word nihaoxiaozhi

--language接受 main/assets/locales 下列出的区域；--wake-word接受 ESP-SR 模型名或nihaoxiaozhi/disabled。ESP32-S3 目标会默认启用 AFE 唤醒词引擎（需要 PSRAM，见 Kconfig.projbuild）。

六、适配要点与注意事项

AEC 依赖物理声学隔离：设备端 AEC 依赖干净的参考信号通路，且麦克风与扬声器之间需要物理隔离才能达到理想效果（Kconfig.projbuild 的帮助文本明确说明）。因此本板卡出厂即启用CONFIG_USE_DEVICE_AEC=y。
唤醒词与内存：ESP32-S3 使用 AFE 唤醒词（Wakenet + AEC + VAD 共享上行通路）需要 PSRAM 支持，构建时应确保sdkconfig中 SPIRAM 已启用（参见 Kconfig.projbuild 中USE_AUDIO_PROCESSOR的依赖条件）。
小屏字体：240×284 属于小尺寸屏幕，构建系统自动为其选用 16px 级字体（font_noto_sans_basic_16_4/font_material_symbols_16_4），表情集合为 64px 版本，保证界面在紧凑屏幕上清晰可读（main/CMakeLists.txt）。
电源管理行为：仅在电池放电时启用休眠/关机定时器，插电充电状态下设备不会因长时间无操作自动关机，符合桌面供电使用场景。