xiaozhi-esp32 移植实战：LCD Wiki ES3C35P 3.5 寸 ESP32-S3 开发板适配指南

xiaozhi-esp32 移植实战：LCD Wiki ES3C35P 3.5 寸 ESP32-S3 开发板适配指南

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

ES3C35P 是一款集成 3.5 寸 IPS 触控屏（ST77922 QSPI）、ES8311 音频编解码与 MEMS 麦克风的 ESP32-S3 智能显示模块，是构建小智 AI 聊天机器人（xiaozhi-esp32）的理想载体。本文以 main/boards/lcdwiki-es3c35p/README.md 为核心，结合 板级初始化源码 与 引脚配置，完整讲解该板的硬件规格、引脚分配、编译烧录流程以及 QSPI 显示 / I2C 触摸 / I2S 音频三路外设的底层驱动原理，帮助你快速完成该板卡的固件适配与二次开发。

一、硬件规格概览

ES3C35P 属于 LCD Wiki 出品的 3.5 寸 ESP32-S3 智能显示模块，官方资料指向其产品页（SKU 分为带喇叭的 ES3C35P 与无喇叭的 ES3C35P-NS）。下表汇总了核心规格：

显示屏

ST77922 是"触显一体"（TDDI，Touch and Display Driver Integration）控制器，即显示驱动与电容触摸控制器集成在同一颗芯片内，因此触摸功能不需要额外挂载独立的触摸 IC。板上 I2C 总线同时服务 ES8311 音频芯片与 ST77922 触摸部分，地址分别为 ES8311 默认地址与0x55。

音频

与 config.h 中AUDIO_INPUT_SAMPLE_RATE 24000、AUDIO_OUTPUT_SAMPLE_RATE 24000的定义完全对应——小智固件的音频链路（AFE 唤醒 + 对话）正是运行在 24kHz 双工采样率之上。

外设

二、完整引脚分配

引脚定义可在 config.h 中逐一核对，与板级源码一一对应：

注意 IO0 的复用逻辑：启动阶段按住进入下载模式，运行阶段单击则通过 InitializeButtons() 注册的OnClick回调切换对话状态（启动过程中按下则进入 WiFi 配网模式），这是小智设备"一键交互"的典型入口。

显示 QSPI 引脚组

CS = IO10 D0 = IO11 CLK = IO12 D1 = IO13 D2 = IO14 D3 = IO9

对应源码 InitializeQspiBus()：QSPI 使用 SPI2 主机，data0~data3四线数据 +sclk+ 片选，max_transfer_sz由DISPLAY_BUFFER_SIZE * sizeof(uint16_t)计算得出（即 320×80×2 = 51200 字节，约 51KB），并启用SPI_DMA_CH_AUTO自动分配 DMA 通道。

I2C 设备地址

两设备挂在同一条 I2C0 总线上（IO38/IO39，配置为I2C_NUM_0且开启内部上拉enable_internal_pullup = 1，见 InitializeI2c()）。

三、编译与烧录

方式一：一键编译打包（推荐）

python scripts/build.py lcdwiki-es3c35p --zip

scripts/build.py 会读取 config.json 中的目标信息（target: esp32s3、16MB Flash 配置），自动完成设置目标、编译、合并分区并打包固件。

方式二：手动编译

idf.py set-target esp32s3 idf.py menuconfig # Xiaozhi Assistant -> Board Type -> LCD Wiki ES3C35P (3.5寸 ESP32-S3) idf.py build flash monitor

菜单项对应 main/Kconfig.projbuild 中的BOARD_TYPE_LCDWIKI_ES3C35P（仅对IDF_TARGET_ESP32S3生效），选中后 main/CMakeLists.txt 会将BOARD_DIR指向lcdwiki-es3c35p，并把该目录下的所有.cc/.c文件纳入编译。ST77922 驱动通过组件依赖引入，见 main/idf_component.yml 中的espressif/esp_lcd_st77922: ^2.0.2。

四、关键配置说明与源码级原理

4.1 显示：ST77922 QSPI

这些配置的落地位置非常清晰：

• config.h 定义DISPLAY_WIDTH 320、DISPLAY_HEIGHT 480、DISPLAY_RGB_ORDER LCD_RGB_ELEMENT_ORDER_BGR、DISPLAY_BUFFER_LINES 80（缓冲行数）与DISPLAY_SWAP_XY false；
• InitializeLcdDisplay() 以 80MHz 像素时钟、32 位命令宽度、quad_mode 方式创建 QSPI panel IO，并注册 ST77922 驱动；st77922_vendor_config_t传入use_qspi_interface = 1；
• LVGL 显示配置中buff_dma = 1、buff_spiram = 0、swap_bytes = 1，缓冲完全位于内部 SRAM，避免 PSRAM 中转带来的延迟与带宽损耗。

x 坐标 4 对齐是 ST77922 的硬性要求：源码中 st77922_rounder_cb 通过LV_EVENT_INVALIDATE_AREA事件回调，将每次刷新的 x 范围强制对齐到 4 的倍数（x1 = (x1 >> 2) << 2，x2 = ((x2 >> 2) << 2) + 3），否则会出现花屏。由于该控制器不支持 X/Y 轴交换，源码开头还有一行编译期断言static_assert(!DISPLAY_SWAP_XY, ...)来兜底。

此外，lcdwiki-es3c35p.cc 内置了长达 70+ 条的 ST77922 初始化命令表（lcd_init_cmds），涵盖电源时序、Gamma 校正、背光、扫描方向等寄存器序列，并在末尾按序执行 0x11（Sleep Out，延时 120ms）与 0x29（Display On），确保屏幕一次点亮。

4.2 触摸：ST77922 内置电容触摸

源码中触摸控制器以TOUCH_I2C_ADDR 0x55注册，寄存器按 16 位地址访问（touch_i2c_read先发送高字节再发低字节）。关键实现细节：

• 上电后先对TOUCH_RST_PIN（IO48）做 10ms 低电平复位、100ms 高电平恢复，见 InitializeTouch()；
• 读取TOUCH_REG_MAX_TOUCHES（0x0009）动态获取最大触摸点数（1~5），用于确定后续读取长度；
• 轮询读取信息寄存器TOUCH_REG_INFO（0x0010），当 bit3 置位表示有触摸事件时，一次性读取7 × max_points字节的坐标缓冲区并解析每个点（x/y 均为 12 位拼接格式）；
• 代码还内置了小于 4px 的抖动过滤（dx > 3 || dx < -3 || dy > -3），避免轻触时误触发滚动。

4.3 音频：ES8311 + FM8002E

GetAudioCodec() 中创建Es8311AudioCodec时，将 PA 引脚设为AUDIO_CODEC_PA_PIN（IO1）并传入pa_inverted=true——与文档"低电平使能功放"一致，也对应 Es8311AudioCodec 构造签名中的pa_inverted参数。I2S 使用 MCLK（IO17）、BCLK（IO18）、WS（IO21）、DOUT（IO15）、DIN（IO16）五线全双工接法，MEMS 麦克风拾音与喇叭放音同时工作。

五、已知限制与设计权衡

1. ST77922 不支持swap_xy— 只能使用原生 320×480 竖屏，横屏需求需自行旋转 UI 而非硬件交换坐标；
2. ST77922 要求 x 坐标 4 对齐— 已通过rounder_cb自动处理，二次开发时不要绕过该回调；
3. 触摸无 DMA/中断— 使用轮询方式读取，约 30fps，对语音交互场景足够，但不适合高频游戏类交互；
4. LVGL 缓冲在 SRAM— 占用约 51KB，剩余约 180KB 供其他模块使用，内存规划时需留意。

这些限制既是硬件特性，也反映了板级适配时的取舍：用 SRAM 换 DMA 直写性能，用轮询换引脚与驱动复杂度，属于小智固件在该硬件上的平衡方案。

六、文件结构

main/boards/lcdwiki-es3c35p/ config.h — 引脚/硬件配置宏 config.json — 构建目标 (esp32s3, 16MB Flash) lcdwiki-es3c35p.cc — 板级初始化 (QSPI 显示 + I2C 触摸 + ES8311 音频 + LED) README.md — 本文档

其中 lcdwiki-es3c35p.cc 继承WifiBoard（网络能力来自 boards/common/wifi_board.h），通过DECLARE_BOARD(LCDWikiES3C35P_Board)注册为可被固件识别的板卡，并覆写了GetAudioCodec、GetDisplay、GetBacklight（IO41 PWM 背光）、GetLed（IO40 WS2812B 单灯）四个接口，构成完整的小智设备抽象。若有self.system.reconfigure_wifi等 MCP 工具调用，也会在 InitializeTools() 中注册，与云端能力打通。

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