小智 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 目录由三个核心文件构成文件作用config.h定义该板的所有引脚映射、采样率、显示参数等硬件常量config.json声明板级构建元数据制造商、目标芯片、两个构建变体及 sdkconfig 追加项esp32-s3-touch-amoled-1.75.cc板级主实现继承WifiBoard完成电源、显示、触摸、音频、按键、功耗与 MCP 工具的初始化二、构建变体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_STYLEn, CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75y, CONFIG_USE_DEVICE_AECy ] }, { name: esp32-s3-touch-amoled-1.75c, sdkconfig_append: [ CONFIG_USE_WECHAT_MESSAGE_STYLEn, CONFIG_BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75Cy, CONFIG_USE_DEVICE_AECy ] } ] }两个变体对应的 Kconfig 选项定义于 main/Kconfig.projbuildBOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75与BOARD_TYPE_WAVESHARE_ESP32_S3_TOUCH_AMOLED_1_75C均依赖IDF_TARGET_ESP32S3。编译时二者都会被CONFIG_USE_DEVICE_AECy开启设备端回声消除并关闭微信消息样式。在config.h中两个变体通过#if/#elif CONFIG_BOARD_TYPE_...分支切换引脚功能1.75 变体1.75C 变体音频 I2S MCLKGPIO 42GPIO 16音频 I2S WSGPIO 45GPIO 45音频 I2S BCLKGPIO 9GPIO 9音频 I2S DIN录音GPIO 10GPIO 10音频 I2S DOUT放音GPIO 8GPIO 8LCD 复位GPIO 39GPIO 1触摸复位GPIO 40GPIO 2触摸中断GPIO 11GPIO 11从源码结构看两版硬件的主要差异集中在音频时钟引脚与复位引脚其余外设显示数据线、触摸、按键、音频编解码 I2C 等保持一致。三、引脚定义与硬件常量解析config.hconfig.h 定义了完整的板级硬件参数可分为五组1. 音频参数#define AUDIO_INPUT_SAMPLE_RATE 24000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 #define AUDIO_INPUT_REFERENCE true输入与输出采样率均为 24 kHzAUDIO_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 总线SDA15SCL14控制功放使能脚为 GPIO 46。这里同时定义了ES8311DAC/放音与ES7210ADC/录音两颗芯片的默认 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_7LCD 采用4 线 QSPI 接口CS12、PCLK38、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); // 主电池充电电流 400mA0x08200mA, 0x09300mA, 0x0A400mA 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 驱动与初始化序列显示初始化分为两步SPI 总线初始化InitializeSpi()使用SPI2_HOST、SPICOMMON_BUSFLAG_QUAD四线模式max_transfer_sz按一帧 466×466×2 字节计算面板 IO 与驱动初始化InitializeDisplay()CSGPIO12、DC 为GPIO_NUM_NCQSPI 无 DC 线、PCLK 40 MHz、lcd_cmd_bits3232 位命令字携带命令/读写标志、lcd_param_bits8、开启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.ymlespressif/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 寄存器调光板载背光未接 GPIOCustomBacklight通过 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通过 I2C400 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 与设备端 AECGetAudioCodec()返回BoxAudioCodec实例实现见 box_audio_codec.cc传入 MCLK/BCLK/WS/DOUT/DIN/PA 引脚、ES8311 与 ES7210 地址以及AUDIO_INPUT_REFERENCEtruestatic 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_AECy本板实现了设备端回声消除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_75y或_1_75Cy与CONFIG_USE_DEVICE_AECy三个关键宏与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组件用途espressif/esp_lcd_co5300: ^2.0.3CO5300 AMOLED 面板驱动espressif/esp_io_expander_tca9554: ~2.0.3TCA9554 IO 扩展器仅 1.75 变体waveshare/esp_lcd_touch_cst9217: ^1.0.3CST9217 电容触摸驱动实际调试中可重点核对以下几点1.75 与 1.75C 变体引脚不同务必确认硬件版本与所选CONFIG_BOARD_TYPE_...宏一致MCLK、LCD/触摸复位脚差异见第二节表格触摸初始化要求触摸中断/复位低电平有效levels.reset0, interrupt0若触摸失灵优先排查这两个脚的电平配置背光无 GPIO 控制调光依赖 CO5300 的 0x51 命令若背光异常应检查 QSPI 面板 IO 是否初始化成功设备端 AEC 依赖CONFIG_USE_DEVICE_AECy与AUDIO_INPUT_REFERENCEtrue同时成立回声消除效果异常时可通过双击 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考