小智 AI 助手 Waveshare ESP32-S3-Touch-AMOLED-1.75 开发板适配指南：从硬件引脚到固件源码解析

小智 AI 助手 Waveshare ESP32-S3-Touch-AMOLED-1.75 开发板适配指南：从硬件引脚到固件源码解析

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

本篇技术指南以 xiaozhi-esp32（小智 AI 聊天机器人）仓库中 Waveshare ESP32-S3-Touch-AMOLED-1.75 开发板的板级支持文档为主线，结合main/boards/waveshare/esp32-s3-touch-amoled-1.75/目录下的config.h、config.json与板级源码，系统讲解该开发板在项目中的硬件特性、引脚分配、双构建变体差异、显示/触摸/音频/电源管理的源码级实现，以及如何编译烧录。读完本文，你将掌握在 xiaozhi-esp32 工程中适配一块带 AMOLED 触屏、麦克风阵列与回声消除电路的 ESP32-S3 开发板所需的完整知识链路。

一、开发板硬件概览

根据板级支持文档 README.md 的介绍，Waveshare ESP32-S3-Touch-AMOLED-1.75 是一款由 Waveshare 设计的高性能、高度集成的微控制器开发板，其核心特征如下：

• 主控：ESP32-S3，支持 Wi-Fi / BLE，适合作为语音助手设备的主控；
• 显示：1.75 英寸电容式 HD AMOLED 屏幕，小尺寸形态下仍提供高画质显示；
• 电源管理：板载高度集成的电源管理芯片（源码中为 AXP2101）；
• 传感：六轴传感器（三轴加速度计 + 三轴陀螺仪）；
• 实时时钟：板载 RTC；
• 音频：低功耗音频编解码芯片与回声消除（AEC）电路。

该开发板的小尺寸与高集成度设计，使其适合直接嵌入到产品中作为语音交互终端。在 xiaozhi-esp32 项目中，这一板级支持位于 esp32-s3-touch-amoled-1.75 目录，由三个核心文件构成：

二、构建变体：1.75 与 1.75C 的区别

config.json中声明了esp32s3目标芯片，并提供了两个构建变体，它们共用同一份源码，仅通过不同的 sdkconfig 宏切换引脚定义：

{ "manufacturer": "waveshare", "type": "esp32-s3-touch-amoled-1.75", "target": "esp32s3", "builds": [ { "name": "esp32-s3-touch-amoled-1.75", "sdkconfig_append": [ "CONFIG_USE_WECHAT_MESSAGE_STYLE=n", "CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75=y", "CONFIG_USE_DEVICE_AEC=y" ] }, { "name": "esp32-s3-touch-amoled-1.75c", "sdkconfig_append": [ "CONFIG_USE_WECHAT_MESSAGE_STYLE=n", "CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75C=y", "CONFIG_USE_DEVICE_AEC=y" ] } ] }

两个变体对应的 Kconfig 选项定义于 main/Kconfig.projbuild（BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75与BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75C，均依赖IDF_TARGET_ESP32S3）。编译时二者都会被CONFIG_USE_DEVICE_AEC=y开启设备端回声消除，并关闭微信消息样式。

在config.h中，两个变体通过#if/#elif CONFIG_BOARD_TYPE_...分支切换引脚：

从源码结构看，两版硬件的主要差异集中在音频时钟引脚与复位引脚，其余外设（显示数据线、触摸、按键、音频编解码 I2C 等）保持一致。

三、引脚定义与硬件常量解析（config.h）

config.h 定义了完整的板级硬件参数，可分为五组：

1. 音频参数

#define AUDIO_INPUT_SAMPLE_RATE 24000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 #define AUDIO_INPUT_REFERENCE true

输入与输出采样率均为 24 kHz；AUDIO_INPUT_REFERENCE true表示录音通路带参考信号输入，配合CONFIG_USE_DEVICE_AEC构建设备端回声消除（详见下文音频小节）。

2. 音频编解码 I2C 与功放

#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 #define I2C_ADDRESS ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000

编解码器通过 I2C0 总线（SDA=15，SCL=14）控制，功放使能脚为 GPIO 46。这里同时定义了ES8311（DAC/放音）与ES7210（ADC/录音）两颗芯片的默认 I2C 地址，以及 TCA9554 IO 扩展器的 I2C 地址（仅 1.75 变体使用）。

3. 显示与触摸引脚

#define EXAMPLE_PIN_NUM_LCD_CS GPIO_NUM_12 #define EXAMPLE_PIN_NUM_LCD_PCLK GPIO_NUM_38 #define EXAMPLE_PIN_NUM_LCD_DATA0 GPIO_NUM_4 #define EXAMPLE_PIN_NUM_LCD_DATA1 GPIO_NUM_5 #define EXAMPLE_PIN_NUM_LCD_DATA2 GPIO_NUM_6 #define EXAMPLE_PIN_NUM_LCD_DATA3 GPIO_NUM_7

LCD 采用4 线 QSPI 接口（CS=12、PCLK=38、DATA0~3 = 4/5/6/7），这是该板 AMOLED 高带宽显示的关键。

4. 显示参数

#define DISPLAY_WIDTH 466 #define DISPLAY_HEIGHT 466 #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_NC #define DISPLAY_BACKLIGHT_OUTPUT_INVERT false

屏幕为 466×466 正方形分辨率，无需镜像或坐标交换；背光引脚为GPIO_NUM_NC（未占用 GPIO），因为该板背光不是通过 GPIO 电平而是通过 LCD 命令寄存器控制（见下文自定义背光实现）。

5. 按键

#define BOOT_BUTTON_GPIO GPIO_NUM_0

仅使用 GPIO 0 作为唯一实体按键（Boot 键），单击与双击承担不同功能。

四、板级源码实现深度解析（.cc）

板级实现文件 esp32-s3-touch-amoled-1.75.cc 以DECLARE_BOARD(WaveshareEsp32s3TouchAMOLED1inch75)导出板级工厂，类继承自 WifiBoard，构造函数按序完成各外设初始化。

4.1 电源管理：AXP2101 PMIC 定制

Pmic类继承Axp2101，在构造时通过寄存器直写完成电源策略配置，各寄存器含义与取值如下：

WriteReg(0x22, 0b110); // PWRON > OFFLEVEL 作为关机源使能 WriteReg(0x27, 0x10); // 长按 4 秒关机 WriteReg(0x80, 0x01); // 除 DC1 外关闭所有 DC 输出 WriteReg(0x90, 0x00); // 先关闭所有 LDO WriteReg(0x91, 0x00); WriteReg(0x82, (3300 - 1500) / 100); // DC1 输出 3.3V WriteReg(0x92, (3300 - 500) / 100); // ALDO1 输出 3.3V WriteReg(0x90, 0x01); // 使能 ALDO1（给 MIC 供电） WriteReg(0x64, 0x02); // CV 充电电压 4.1V WriteReg(0x61, 0x02); // 主电池预充电电流 50mA WriteReg(0x62, 0x08); // 主电池充电电流 400mA（0x08=200mA, 0x09=300mA, 0x0A=400mA） WriteReg(0x63, 0x01); // 主电池截止充电电流 25mA

从源码可见：除 DC1 与 ALDO1 外其余电源轨全部关闭，DC1/ALDO1 均配置为 3.3V，其中 ALDO1 专用于麦克风供电；充电策略为 4.1V 恒压、400mA 恒流。PMIC 通过 I2C 地址0x34挂载（InitializeAxp2101()中new Pmic(i2c_bus_, 0x34)），而 I2C 总线由InitializeCodecI2c()以I2C_NUM_0+ 内部上拉建立。

4.2 QSPI AMOLED 显示：CO5300 驱动与初始化序列

显示初始化分为两步：

1. SPI 总线初始化（InitializeSpi()）：使用SPI2_HOST、SPICOMMON_BUSFLAG_QUAD四线模式，max_transfer_sz按一帧 466×466×2 字节计算；
2. 面板 IO 与驱动初始化（InitializeDisplay()）：CS=GPIO12、DC 为GPIO_NUM_NC（QSPI 无 DC 线）、PCLK 40 MHz、lcd_cmd_bits=32（32 位命令字携带命令/读写标志）、lcd_param_bits=8、开启quad_mode。

LCD 驱动芯片为CO5300，其厂商初始化序列在vendor_specific_init数组中显式给出（片段摘录）：

{0xFE, (uint8_t[]){0x20}, 1, 0}, // 切到 QSPI 模式寄存器页 {0x3A, (uint8_t[]){0x55}, 1, 0}, // 像素格式 RGB565 (0x55) {0x2A, (uint8_t[]){0x00, 0x06, 0x01, 0xD7}, 4, 0}, // 列地址 {0x2B, (uint8_t[]){0x00, 0x00, 0x01, 0xD1}, 4, 600},// 行地址 + 600ms 延时 {0x11, NULL, 0, 600}, // Sleep Out {0x29, NULL, 0, 0}, // Display On

初始化后调用esp_lcd_panel_set_gap(panel, 0x06, 0)设置面板 GAP、invert_color(false)、按DISPLAY_MIRROR_*镜像并点亮屏幕。驱动组件依赖声明于 main/idf_component.yml：espressif/esp_lcd_co5300: ^2.0.3。

4.3 圆角屏适配：自定义显示类与 LVGL 区域取整

由于 466×466 的 AMOLED 屏幕四角为圆角，普通矩形刷新会留下鬼影，源码通过CustomLcdDisplay解决：

• 注册 LVGLLV_EVENT_INVALIDATE_AREA事件回调rounder_event_cb，把待刷新区域的起点坐标向下取整到偶数、终点坐标向上取整到奇数（x1 = (x1 >> 1) << 1; x2 = ((x2 >> 1) << 1) + 1;），保证每次刷新的矩形覆盖完整的 2×2 像素块，避免像素残影；
• 在SetupUI()中重写状态栏左右内边距为LV_HOR_RES * 0.1，适配屏幕四角的圆弧裁切。

4.4 命令式背光：通过 LCD 寄存器调光

板载背光未接 GPIO，CustomBacklight通过 SPI 向 CO5300 发送0x51 亮度命令实现调光：

uint8_t data[1] = {((uint8_t)((255 * brightness) / 100))}; int lcd_cmd = 0x51; lcd_cmd <<= 8; lcd_cmd |= LCD_OPCODE_WRITE_CMD << 24; // 32 位命令字 esp_lcd_panel_io_tx_param(panel_io_, lcd_cmd, &data, sizeof(data));

即把 0~100 的亮度百分比映射为 0~255 的 8 位亮度值，通过 32 位 QSPI 命令字写入。

4.5 触摸：CST9217 电容触摸

InitializeTouch()使用CST9217触摸控制器（依赖waveshare/esp_lcd_touch_cst9217: ^1.0.3），通过 I2C（400 kHz）挂载，配置要点：

esp_lcd_touch_config_t tp_cfg = { .x_max = DISPLAY_WIDTH - 1, // 465 .y_max = DISPLAY_HEIGHT - 1, // 465 .rst_gpio_num = PIN_NUM_TOUCH_RST, .int_gpio_num = PIN_NUM_TOUCH_INT, .levels = { .reset = 0, .interrupt = 0 }, .flags = { .swap_xy = 0, .mirror_x = 1, .mirror_y = 1 }, };

触摸坐标系在触摸控制器侧完成mirror_x/mirror_y翻转以匹配屏幕方向，随后通过lvgl_port_add_touch挂接为 LVGL 输入设备。

4.6 音频通路：ES8311 + ES7210 与设备端 AEC

GetAudioCodec()返回BoxAudioCodec实例（实现见 box_audio_codec.cc），传入 MCLK/BCLK/WS/DOUT/DIN/PA 引脚、ES8311 与 ES7210 地址以及AUDIO_INPUT_REFERENCE=true：

static BoxAudioCodec audio_codec( i2c_bus_, AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE, // 24k / 24k AUDIO_I2S_GPIO_MCLK, AUDIO_I2S_GPIO_BCLK, AUDIO_I2S_GPIO_WS, AUDIO_I2S_GPIO_DOUT, AUDIO_I2S_GPIO_DIN, AUDIO_CODEC_PA_PIN, AUDIO_CODEC_ES8311_ADDR, AUDIO_CODEC_ES7210_ADDR, AUDIO_INPUT_REFERENCE);

结合CONFIG_USE_DEVICE_AEC=y，本板实现了设备端回声消除（Device AEC）：参考信号由音频链路提供给处理引擎，从而在设备本地消除扬声器声音对麦克风的干扰。该特性还暴露了按键交互——InitializeButtons()中在开启 AEC 时注册了 Boot 键双击回调，用于在空闲状态下切换kAecOff与kAecOnDeviceSide两种 AEC 模式。

4.7 按键交互

Boot 键（GPIO 0）单击逻辑：

• 若设备处于kDeviceStateStarting（开机启动中）→ 进入 WiFi 配网模式（EnterWifiConfigMode()）；
• 否则 → 切换对话状态（app.ToggleChatState()）。

4.8 功耗管理：三级省电策略

InitializePowerSaveTimer()使用 PowerSaveTimer 实现三级省电：

power_save_timer_ = new PowerSaveTimer(-1, 60, 300); // 60 秒无操作进入休眠；300 秒（5 分钟）后请求关机

• 进入休眠：SetPowerSaveMode(true)+ 背光降至 20%；
• 退出休眠：恢复显示与背光；
• 关机请求：调用pmic_->PowerOff()真正断电。

GetBatteryLevel()持续轮询 PMIC 充放电状态，仅在放电时启用省电定时器（插入电源则暂停倒计时），SetPowerSaveLevel()收到非LOW_POWER等级时先WakeUp()再交给WifiBoard处理。

4.9 MCP 工具注册

InitializeTools()向 McpServer 注册了self.system.reconfigure_wifi工具：LLM 可在对话中调用它，在征得用户确认后结束当前对话并进入 WiFi 配网模式——这是 xiaozhi-esp32 基于 MCP 的聊天机器人在板级的一个典型落地。

五、编译与烧录

该板目标芯片为 ESP32-S3，按仓库 AGENTS.md 的规范，标准流程为：先加载 ESP-IDF 环境，再选择板级并编译：

# 1. 加载 ESP-IDF 环境 source /path/to/esp-idf/export.sh idf.py --version # 2. 设置目标芯片 idf.py set-target esp32s3 # 3. 选择板型（menuconfig 中选中 # "Waveshare ESP32-S3-Touch-AMOLED-1.75" 或 "Waveshare ESP32-S3-Touch-AMOLED-1.75C"） idf.py menuconfig # 4. 编译、烧录并查看串口日志 idf.py build flash monitor

也可以在menuconfig中直接确认CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75=y（或_1_75C=y）与CONFIG_USE_DEVICE_AEC=y三个关键宏，与config.json中的sdkconfig_append保持一致。若使用仓库的构建脚本体系，可参考config.json中声明的两个变体名（esp32-s3-touch-amoled-1.75/esp32-s3-touch-amoled-1.75c）按变体构建。

注意：根据 AGENTS.md，构建脚本会改写本地sdkconfig与构建状态，切换目标后不应假定旧的构建目录仍然有效。

六、关键依赖与排查提示

本板级实现依赖以下 ESP-IDF 组件（见 main/idf_component.yml）：

实际调试中可重点核对以下几点：

• 1.75 与 1.75C 变体引脚不同，务必确认硬件版本与所选CONFIG_BOARD_TYPE_...宏一致（MCLK、LCD/触摸复位脚差异见第二节表格）；
• 触摸初始化要求触摸中断/复位低电平有效（levels.reset=0, interrupt=0），若触摸失灵优先排查这两个脚的电平配置；
• 背光无 GPIO 控制，调光依赖 CO5300 的 0x51 命令，若背光异常应检查 QSPI 面板 IO 是否初始化成功；
• 设备端 AEC 依赖CONFIG_USE_DEVICE_AEC=y与AUDIO_INPUT_REFERENCE=true同时成立，回声消除效果异常时可通过双击 Boot 键切换 AEC 模式对比验证。

七、总结

Waveshare ESP32-S3-Touch-AMOLED-1.75 是 xiaozhi-esp32 中一款集成度较高的板级支持：466×466 QSPI AMOLED + CST9217 触摸构成完整的交互界面，AXP2101 提供 3.3V 电源轨与 4.1V/400mA 充电管理，ES8311 + ES7210 配合参考输入实现设备端 AEC 语音链路，而PowerSaveTimer三级省电策略让电池供电场景具备完整的产品化能力。通过本文的引脚表、寄存器配置与源码级解读，你可以对照 esp32-s3-touch-amoled-1.75 目录 快速完成该板固件的编译、烧录与定制，也可以以此为范本，理解 xiaozhi-esp32 中一块新开发板从config.h到DECLARE_BOARD的完整适配路径。

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