xiaozhi-esp32 适配 Freenove ESP32-S3 Display 2.8 寸电容触屏板引脚配置、触摸交互与固件构建全解析【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本指南以 freenove-esp32s3-display-2.8-lcd 板卡目录为核心系统讲解小智 AI 语音助手xiaozhi-esp32对该开发板的完整适配从硬件识别、引脚映射、LCD/触摸/音频驱动初始化到构建系统接入与固件烧录流程。读完本文你将掌握这块板卡的驱动架构、触控手势逻辑并能独立完成固件配置、编译与问题排查。板卡概览一块带触摸屏的 ESP32-S3 语音终端Freenove ESP32-S3 Display 2.8型号 FNK0104是一块集成 2.8 英寸 240×320 分辨率 IPS 电容触摸屏的 ESP32-S3 开发板同时板载 WiFi 与蓝牙能力是典型的带屏语音交互终端形态。该板卡在 xiaozhi-esp32 仓库中以独立板卡类型freenove-esp32s3-display-2.8-lcd提供完整支持被列为官方适配目标之一并在 docs/esp-idf-6-migration.md 的 IDF 6.0.1 迁移验证矩阵中标注为通过完整构建。板卡目录结构main/boards/freenove-esp32s3-display-2.8-lcd/遵循仓库标准的一板一目录规范文件作用ReadMe.md板卡简介与硬件信息来源config.h引脚分配与硬件参数宏定义config.json板卡类型声明与构建配置freenove-esp32s3-display-2.8-lcd.cc板级初始化与驱动粘合代码官方说明指出该板卡与 LCD wiki 的 ES3C28P/ES3N28P 很可能采用相同的硬件设计这意味着本文的驱动分析对同系板卡同样具有参考价值。引脚映射config.h 全量解读config.h 是板卡的硬件身份证定义了音频、按键、显示三大子系统所需的全部引脚与参数。音频子系统ES8311 编解码器#define AUDIO_INPUT_SAMPLE_RATE 24000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 //音频iis部分 #define AUDIO_I2S_GPIO_MCLK GPIO_NUM_4 //MCLK #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_5 //SCK #define AUDIO_I2S_GPIO_DIN GPIO_NUM_6 //DIN #define AUDIO_I2S_GPIO_WS GPIO_NUM_7 //LRC #define AUDIO_I2S_GPIO_DOUT GPIO_NUM_8 //DOUT #define AUDIO_CODEC_PA_PIN GPIO_NUM_1 //PA //音频iic部分 #define AUDIO_CODEC_I2C_NUM I2C_NUM_0 #define AUDIO_CODEC_I2C_SCL_PIN GPIO_NUM_15 #define AUDIO_CODEC_I2C_SDA_PIN GPIO_NUM_16 #define AUDIO_CODEC_ES8311_ADDR ES8311_CODEC_DEFAULT_ADDR输入/输出采样率统一为 24 kHz这是小智语音链路的标准采样率由 audio/codecs/es8311_audio_codec.cc 中的Es8311AudioCodec驱动支持。音频走 I2S 总线MCLK(4)、BCLK(5)、WS(7)、DOUT(8) 输出、DIN(6) 输入PA 功放使能引脚为 GPIO1。编解码器控制走 I2C0SCL15、SDA16地址使用 ES8311 默认地址ES8311_CODEC_DEFAULT_ADDR即 0x18。按键与指示灯#define BOOT_BUTTON_GPIO GPIO_NUM_0 #define BUILTIN_LED_GPIO GPIO_NUM_42启动按键接 GPIO0ESP32 系通用 BOOT 键板级代码中将其注册为Button交互源。板载 LED 接 GPIO42由SingleLed驱动见下文GetLed()。显示子系统ILI9341 串行 SPI#define DISPLAY_BACKLIGHT_PIN GPIO_NUM_45 #define DISPLAY_RST_PIN GPIO_NUM_NC #define DISPLAY_SCK_PIN GPIO_NUM_12 #define DISPLAY_DC_PIN GPIO_NUM_46 #define DISPLAY_CS_PIN GPIO_NUM_10 #define DISPLAY_MOSI_PIN GPIO_NUM_11 #define DISPLAY_MIS0_PIN GPIO_NUM_13 #define DISPLAY_SPI_SCLK_HZ (20 * 1000 * 1000) #define LCD_SPI_HOST SPI3_HOST #define LCD_TYPE_ILI9341_SERIAL #define DISPLAY_WIDTH 320 #define DISPLAY_HEIGHT 240 #define DISPLAY_MIRROR_X false #define DISPLAY_MIRROR_Y false #define DISPLAY_SWAP_XY true #define DISPLAY_INVERT_COLOR true #define DISPLAY_RGB_ORDER LCD_RGB_ELEMENT_ORDER_BGR #define DISPLAY_OFFSET_X 0 #define DISPLAY_OFFSET_Y 0 #define DISPLAY_BACKLIGHT_OUTPUT_INVERT false #define DISPLAY_SPI_MODE 0几个关键点的工程含义分辨率与方向DISPLAY_WIDTH320、DISPLAY_HEIGHT240即物理横屏 320×240DISPLAY_SWAP_XYtrue使逻辑坐标与面板方向匹配DISPLAY_INVERT_COLORtrue表明该面板需要颜色反相ILI9341 常见配置RGB 顺序为 BGR。SPI 总线使用SPI3_HOST时钟 20 MHzSPI Mode 0MISO 引脚GPIO13仍被定义InitializeSpi()中同样配置了miso_io_num说明该板 SPI 为全双工接线。背光GPIO45 输出 PWM 背光DISPLAY_BACKLIGHT_OUTPUT_INVERTfalse表示高电平点亮DISPLAY_RST_PINGPIO_NUM_NC表示复位脚未单独引出由面板自身管理复位。板级驱动实现从 I2C 到触控的完整初始化链freenove-esp32s3-display-2.8-lcd.cc 定义了FreenoveESP32S3Display类继承自WifiBoard构造顺序即外设初始化顺序InitializeI2c() → InitializeBatteryMonitor() → InitializeSpi() → InitializeLcdDisplay() → InitializeTouch() → InitializeButtons() → InitializeTools()I2C 总线与触控芯片InitializeI2c()通过 ESP-IDF 新的i2c_master驱动创建 I2C0 总线i2c_new_master_bus并启用内部上拉。该总线被音频编解码器与触控芯片共用。TouchDriver封装了电容触控芯片的读取协议bool Read(bool touched, uint16_t x, uint16_t y) { uint8_t reg 0x02; uint8_t buf[5]; i2c_master_transmit_receive(dev_, reg, 1, buf, 5, 50); uint8_t points buf[0] 0x0F; ... x ((buf[1] 0x0F) 8) | buf[2]; y ((buf[3] 0x0F) 8) | buf[4]; }从源码结构看InitializeTouch()以 I2C 地址0x38挂载触控芯片读取寄存器0x02获得触点数量低 4 位及 12 位精度的 X/Y 坐标坐标寄存器同样只有高 12 位有效每次轮询超时 50ms——这符合常见电容触控控制器如 FT 系列的协议形态。触控数据由独立 FreeRTOS 任务TouchTask栈 4096优先级 5固定运行在核心 0每 50ms 轮询一次。触控手势单击、双击与长按TouchTask是这块板卡交互的核心它把原始触摸事件翻译成三个语音助手手势手势判定条件动作单击按下时长 ≤ 3000ms且与上一次单击间隔 ≥ 250msapp.ToggleChatState()切换聊天状态双击两次单击间隔 250msapp.StartListening()开始聆听长按按下时长 3000msEnterWifiConfigMode()进入 WiFi 配网模式其判定流程为检测按下瞬间记录down_start抬起时计算press now - down_start先判断是否超过 3000ms 长按进入配网否则再判断距上次单击是否小于 250ms 以识别双击双击会立即清空last_tap防止三连击误判。这套逻辑直接映射到 application.cc 的ToggleChatState/StartListening接口实现了不依赖实体按键的纯触控人机交互。LCDILI9341 面板初始化InitializeLcdDisplay()完整展示了 ESP-IDFesp_lcd驱动框架的接入方式配置esp_lcd_panel_io_spi_config_tCSGPIO10、DCGPIO46、spi_mode0、pclk_hz20MHz、命令/参数位宽 8 位通过esp_lcd_new_panel_io_spi注册到SPI3_HOST配置esp_lcd_panel_dev_config_t16 位色深、reset_gpio_numGPIO_NUM_NC、RGB 顺序 BGR调用esp_lcd_new_panel_ili9341创建 ILI9341 面板依次执行esp_lcd_panel_reset→esp_lcd_panel_init→invert_color(true)→swap_xy(true)→mirror(false, false)封装为SpiLcdDisplay并赋值给display_后续由 main/display/lcd_display.cc 统一对接 LVGL 渲染。音频与电量两个虚函数覆写virtual AudioCodec* GetAudioCodec() override { static Es8311AudioCodec audio_codec(codec_i2c_bus_, AUDIO_CODEC_I2C_NUM, AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE, 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, true, true); return audio_codec; }GetAudioCodec()返回以 ES8311 为编解码器的实例开启输入输出双通道GetBacklight()返回 GPIO45 的PwmBacklightGetLed()返回 GPIO42 的SingleLed。GetBatteryLevel()通过AdcBatteryMonitor实现InitializeBatteryMonitor()中使用ADC_UNIT_1、ADC_CHANNEL_8上下分压电阻均按 200kΩ 配置参考电压引脚为GPIO_NUM_NC使用内部参考。这是仓库 main/boards/common/adc_battery_monitor.cc 提供的通用 ADC 电量监测方案。实体按键的补充逻辑InitializeButtons()给 BOOT 键GPIO0注册了点击回调若设备仍处于kDeviceStateStarting启动中则先进入 WiFi 配网模式否则切换聊天状态——与触摸手势形成双通道交互冗余。构建系统接入Kconfig 与 CMake 的注册点该板卡不是孤立目录而是被完整接入了仓库构建体系Kconfig 注册main/Kconfig.projbuildconfig BOARD_TYPE_Freenove_ESP32S3_DISPLAY_2_8_LCD bool Freenove ESP32-S3 Display 2.8-inch LCD depends on IDF_TARGET_ESP32S3通过depends on IDF_TARGET_ESP32S3限定目标芯片为 ESP32-S3。CMake 分支main/CMakeLists.txtelseif(CONFIG_BOARD_TYPE_Freenove_ESP32S3_DISPLAY_2_8_LCD) set(BOARD_DIR freenove-esp32s3-display-2.8-lcd) set(BUILTIN_TEXT_FONT font_noto_sans_basic_20_4) set(BUILTIN_ICON_FONT font_material_symbols_20_4) set(DEFAULT_EMOJI_COLLECTION noto-color-emoji_64)为 240×320 分辨率选择了 20px 级字体与 64px Emoji 集合符合 docs/custom-board.md 中中屏240×320配*_20_4字体的选型建议。类型声明config.json{ type: freenove-esp32s3-display-2.8-lcd, target: esp32s3, builds: [ { name: freenove-esp32s3-display-2.8-lcd } ] }type与name一致均满足小写字母/数字/连字符的命名约束且未在板级强制语言与唤醒词保持用户构建选项的灵活性。固件构建与烧录推荐使用仓库提供的build.py脚本用法详见 docs/custom-board.md 的构建章节# 方式一自动脚本推荐自动读取 config.json 的 target python scripts/build.py freenove-esp32s3-display-2.8-lcd # 指定语言与唤醒词用户构建选项 python scripts/build.py freenove-esp32s3-display-2.8-lcd \ --language zh-CN \ --wake-word nihaoxiaozhi # 查看可选值 python scripts/build.py --list-languages python scripts/build.py --list-wake-words也可以走传统 ESP-IDF 流程idf.py set-target esp32s3 idf.py menuconfig # Xiaozhi Assistant - Board Type - Freenove ESP32-S3 Display 2.8-inch LCD idf.py build idf.py flash monitor构建产物默认为build/merged-binary.bin可通过--zip打包为 release 压缩包。固件烧录后设备将通过蓝牙/WiFi 完成配网长按屏幕或启动时按 BOOT 键均可进入配网模式随后即可在屏幕上看到小智的 LVGL 界面并通过触摸手势进行对话交互。与其他板卡的关联与排查要点同系硬件ReadMe 指出该板与 LCD wiki ES3C28P/ES3N28P 硬件设计很可能一致。仓库中另有 lcdwiki-es3c35p3.5 寸版可作为对照参考两者共用 ILI9341 SPI 驱动模式有助于理解同族面板的移植差异。排查建议结合 docs/custom-board.md 的 Troubleshooting显示异常花屏/反色/方向错核对DISPLAY_INVERT_COLOR、DISPLAY_SWAP_XY、DISPLAY_RGB_ORDER与 SPI Mode/时钟无声音检查 I2S 五根线、PA 使能脚GPIO1与 ES8311 的 I2C 地址0x18是否与硬件一致触摸无响应确认触控芯片 I2C 地址 0x38 是否挂载成功并观察串口日志中touch_task是否有数据更新。小结Freenove ESP32-S3 Display 2.8 在 xiaozhi-esp32 中是一块小而完整的参考实现它同时涵盖了 ILI9341 SPI 显示、ES8311 音频编解码、电容触摸手势单击/双击/长按、ADC 电量监测与实体按键交互五大子系统。通过阅读 config.h 与 freenove-esp32s3-display-2.8-lcd.cc开发者不仅可以为手头这块板卡完成固件构建也能以此为模板快速把其他带触摸屏的 ESP32-S3 开发板接入小智语音生态。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaozhi-esp32 适配 Freenove ESP32-S3 Display 2.8 寸电容触屏板：引脚配置、触摸交互与固件构建全解析
xiaozhi-esp32 适配 Freenove ESP32-S3 Display 2.8 寸电容触屏板引脚配置、触摸交互与固件构建全解析【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本指南以 freenove-esp32s3-display-2.8-lcd 板卡目录为核心系统讲解小智 AI 语音助手xiaozhi-esp32对该开发板的完整适配从硬件识别、引脚映射、LCD/触摸/音频驱动初始化到构建系统接入与固件烧录流程。读完本文你将掌握这块板卡的驱动架构、触控手势逻辑并能独立完成固件配置、编译与问题排查。板卡概览一块带触摸屏的 ESP32-S3 语音终端Freenove ESP32-S3 Display 2.8型号 FNK0104是一块集成 2.8 英寸 240×320 分辨率 IPS 电容触摸屏的 ESP32-S3 开发板同时板载 WiFi 与蓝牙能力是典型的带屏语音交互终端形态。该板卡在 xiaozhi-esp32 仓库中以独立板卡类型freenove-esp32s3-display-2.8-lcd提供完整支持被列为官方适配目标之一并在 docs/esp-idf-6-migration.md 的 IDF 6.0.1 迁移验证矩阵中标注为通过完整构建。板卡目录结构main/boards/freenove-esp32s3-display-2.8-lcd/遵循仓库标准的一板一目录规范文件作用ReadMe.md板卡简介与硬件信息来源config.h引脚分配与硬件参数宏定义config.json板卡类型声明与构建配置freenove-esp32s3-display-2.8-lcd.cc板级初始化与驱动粘合代码官方说明指出该板卡与 LCD wiki 的 ES3C28P/ES3N28P 很可能采用相同的硬件设计这意味着本文的驱动分析对同系板卡同样具有参考价值。引脚映射config.h 全量解读config.h 是板卡的硬件身份证定义了音频、按键、显示三大子系统所需的全部引脚与参数。音频子系统ES8311 编解码器#define AUDIO_INPUT_SAMPLE_RATE 24000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 //音频iis部分 #define AUDIO_I2S_GPIO_MCLK GPIO_NUM_4 //MCLK #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_5 //SCK #define AUDIO_I2S_GPIO_DIN GPIO_NUM_6 //DIN #define AUDIO_I2S_GPIO_WS GPIO_NUM_7 //LRC #define AUDIO_I2S_GPIO_DOUT GPIO_NUM_8 //DOUT #define AUDIO_CODEC_PA_PIN GPIO_NUM_1 //PA //音频iic部分 #define AUDIO_CODEC_I2C_NUM I2C_NUM_0 #define AUDIO_CODEC_I2C_SCL_PIN GPIO_NUM_15 #define AUDIO_CODEC_I2C_SDA_PIN GPIO_NUM_16 #define AUDIO_CODEC_ES8311_ADDR ES8311_CODEC_DEFAULT_ADDR输入/输出采样率统一为 24 kHz这是小智语音链路的标准采样率由 audio/codecs/es8311_audio_codec.cc 中的Es8311AudioCodec驱动支持。音频走 I2S 总线MCLK(4)、BCLK(5)、WS(7)、DOUT(8) 输出、DIN(6) 输入PA 功放使能引脚为 GPIO1。编解码器控制走 I2C0SCL15、SDA16地址使用 ES8311 默认地址ES8311_CODEC_DEFAULT_ADDR即 0x18。按键与指示灯#define BOOT_BUTTON_GPIO GPIO_NUM_0 #define BUILTIN_LED_GPIO GPIO_NUM_42启动按键接 GPIO0ESP32 系通用 BOOT 键板级代码中将其注册为Button交互源。板载 LED 接 GPIO42由SingleLed驱动见下文GetLed()。显示子系统ILI9341 串行 SPI#define DISPLAY_BACKLIGHT_PIN GPIO_NUM_45 #define DISPLAY_RST_PIN GPIO_NUM_NC #define DISPLAY_SCK_PIN GPIO_NUM_12 #define DISPLAY_DC_PIN GPIO_NUM_46 #define DISPLAY_CS_PIN GPIO_NUM_10 #define DISPLAY_MOSI_PIN GPIO_NUM_11 #define DISPLAY_MIS0_PIN GPIO_NUM_13 #define DISPLAY_SPI_SCLK_HZ (20 * 1000 * 1000) #define LCD_SPI_HOST SPI3_HOST #define LCD_TYPE_ILI9341_SERIAL #define DISPLAY_WIDTH 320 #define DISPLAY_HEIGHT 240 #define DISPLAY_MIRROR_X false #define DISPLAY_MIRROR_Y false #define DISPLAY_SWAP_XY true #define DISPLAY_INVERT_COLOR true #define DISPLAY_RGB_ORDER LCD_RGB_ELEMENT_ORDER_BGR #define DISPLAY_OFFSET_X 0 #define DISPLAY_OFFSET_Y 0 #define DISPLAY_BACKLIGHT_OUTPUT_INVERT false #define DISPLAY_SPI_MODE 0几个关键点的工程含义分辨率与方向DISPLAY_WIDTH320、DISPLAY_HEIGHT240即物理横屏 320×240DISPLAY_SWAP_XYtrue使逻辑坐标与面板方向匹配DISPLAY_INVERT_COLORtrue表明该面板需要颜色反相ILI9341 常见配置RGB 顺序为 BGR。SPI 总线使用SPI3_HOST时钟 20 MHzSPI Mode 0MISO 引脚GPIO13仍被定义InitializeSpi()中同样配置了miso_io_num说明该板 SPI 为全双工接线。背光GPIO45 输出 PWM 背光DISPLAY_BACKLIGHT_OUTPUT_INVERTfalse表示高电平点亮DISPLAY_RST_PINGPIO_NUM_NC表示复位脚未单独引出由面板自身管理复位。板级驱动实现从 I2C 到触控的完整初始化链freenove-esp32s3-display-2.8-lcd.cc 定义了FreenoveESP32S3Display类继承自WifiBoard构造顺序即外设初始化顺序InitializeI2c() → InitializeBatteryMonitor() → InitializeSpi() → InitializeLcdDisplay() → InitializeTouch() → InitializeButtons() → InitializeTools()I2C 总线与触控芯片InitializeI2c()通过 ESP-IDF 新的i2c_master驱动创建 I2C0 总线i2c_new_master_bus并启用内部上拉。该总线被音频编解码器与触控芯片共用。TouchDriver封装了电容触控芯片的读取协议bool Read(bool touched, uint16_t x, uint16_t y) { uint8_t reg 0x02; uint8_t buf[5]; i2c_master_transmit_receive(dev_, reg, 1, buf, 5, 50); uint8_t points buf[0] 0x0F; ... x ((buf[1] 0x0F) 8) | buf[2]; y ((buf[3] 0x0F) 8) | buf[4]; }从源码结构看InitializeTouch()以 I2C 地址0x38挂载触控芯片读取寄存器0x02获得触点数量低 4 位及 12 位精度的 X/Y 坐标坐标寄存器同样只有高 12 位有效每次轮询超时 50ms——这符合常见电容触控控制器如 FT 系列的协议形态。触控数据由独立 FreeRTOS 任务TouchTask栈 4096优先级 5固定运行在核心 0每 50ms 轮询一次。触控手势单击、双击与长按TouchTask是这块板卡交互的核心它把原始触摸事件翻译成三个语音助手手势手势判定条件动作单击按下时长 ≤ 3000ms且与上一次单击间隔 ≥ 250msapp.ToggleChatState()切换聊天状态双击两次单击间隔 250msapp.StartListening()开始聆听长按按下时长 3000msEnterWifiConfigMode()进入 WiFi 配网模式其判定流程为检测按下瞬间记录down_start抬起时计算press now - down_start先判断是否超过 3000ms 长按进入配网否则再判断距上次单击是否小于 250ms 以识别双击双击会立即清空last_tap防止三连击误判。这套逻辑直接映射到 application.cc 的ToggleChatState/StartListening接口实现了不依赖实体按键的纯触控人机交互。LCDILI9341 面板初始化InitializeLcdDisplay()完整展示了 ESP-IDFesp_lcd驱动框架的接入方式配置esp_lcd_panel_io_spi_config_tCSGPIO10、DCGPIO46、spi_mode0、pclk_hz20MHz、命令/参数位宽 8 位通过esp_lcd_new_panel_io_spi注册到SPI3_HOST配置esp_lcd_panel_dev_config_t16 位色深、reset_gpio_numGPIO_NUM_NC、RGB 顺序 BGR调用esp_lcd_new_panel_ili9341创建 ILI9341 面板依次执行esp_lcd_panel_reset→esp_lcd_panel_init→invert_color(true)→swap_xy(true)→mirror(false, false)封装为SpiLcdDisplay并赋值给display_后续由 main/display/lcd_display.cc 统一对接 LVGL 渲染。音频与电量两个虚函数覆写virtual AudioCodec* GetAudioCodec() override { static Es8311AudioCodec audio_codec(codec_i2c_bus_, AUDIO_CODEC_I2C_NUM, AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE, 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, true, true); return audio_codec; }GetAudioCodec()返回以 ES8311 为编解码器的实例开启输入输出双通道GetBacklight()返回 GPIO45 的PwmBacklightGetLed()返回 GPIO42 的SingleLed。GetBatteryLevel()通过AdcBatteryMonitor实现InitializeBatteryMonitor()中使用ADC_UNIT_1、ADC_CHANNEL_8上下分压电阻均按 200kΩ 配置参考电压引脚为GPIO_NUM_NC使用内部参考。这是仓库 main/boards/common/adc_battery_monitor.cc 提供的通用 ADC 电量监测方案。实体按键的补充逻辑InitializeButtons()给 BOOT 键GPIO0注册了点击回调若设备仍处于kDeviceStateStarting启动中则先进入 WiFi 配网模式否则切换聊天状态——与触摸手势形成双通道交互冗余。构建系统接入Kconfig 与 CMake 的注册点该板卡不是孤立目录而是被完整接入了仓库构建体系Kconfig 注册main/Kconfig.projbuildconfig BOARD_TYPE_Freenove_ESP32S3_DISPLAY_2_8_LCD bool Freenove ESP32-S3 Display 2.8-inch LCD depends on IDF_TARGET_ESP32S3通过depends on IDF_TARGET_ESP32S3限定目标芯片为 ESP32-S3。CMake 分支main/CMakeLists.txtelseif(CONFIG_BOARD_TYPE_Freenove_ESP32S3_DISPLAY_2_8_LCD) set(BOARD_DIR freenove-esp32s3-display-2.8-lcd) set(BUILTIN_TEXT_FONT font_noto_sans_basic_20_4) set(BUILTIN_ICON_FONT font_material_symbols_20_4) set(DEFAULT_EMOJI_COLLECTION noto-color-emoji_64)为 240×320 分辨率选择了 20px 级字体与 64px Emoji 集合符合 docs/custom-board.md 中中屏240×320配*_20_4字体的选型建议。类型声明config.json{ type: freenove-esp32s3-display-2.8-lcd, target: esp32s3, builds: [ { name: freenove-esp32s3-display-2.8-lcd } ] }type与name一致均满足小写字母/数字/连字符的命名约束且未在板级强制语言与唤醒词保持用户构建选项的灵活性。固件构建与烧录推荐使用仓库提供的build.py脚本用法详见 docs/custom-board.md 的构建章节# 方式一自动脚本推荐自动读取 config.json 的 target python scripts/build.py freenove-esp32s3-display-2.8-lcd # 指定语言与唤醒词用户构建选项 python scripts/build.py freenove-esp32s3-display-2.8-lcd \ --language zh-CN \ --wake-word nihaoxiaozhi # 查看可选值 python scripts/build.py --list-languages python scripts/build.py --list-wake-words也可以走传统 ESP-IDF 流程idf.py set-target esp32s3 idf.py menuconfig # Xiaozhi Assistant - Board Type - Freenove ESP32-S3 Display 2.8-inch LCD idf.py build idf.py flash monitor构建产物默认为build/merged-binary.bin可通过--zip打包为 release 压缩包。固件烧录后设备将通过蓝牙/WiFi 完成配网长按屏幕或启动时按 BOOT 键均可进入配网模式随后即可在屏幕上看到小智的 LVGL 界面并通过触摸手势进行对话交互。与其他板卡的关联与排查要点同系硬件ReadMe 指出该板与 LCD wiki ES3C28P/ES3N28P 硬件设计很可能一致。仓库中另有 lcdwiki-es3c35p3.5 寸版可作为对照参考两者共用 ILI9341 SPI 驱动模式有助于理解同族面板的移植差异。排查建议结合 docs/custom-board.md 的 Troubleshooting显示异常花屏/反色/方向错核对DISPLAY_INVERT_COLOR、DISPLAY_SWAP_XY、DISPLAY_RGB_ORDER与 SPI Mode/时钟无声音检查 I2S 五根线、PA 使能脚GPIO1与 ES8311 的 I2C 地址0x18是否与硬件一致触摸无响应确认触控芯片 I2C 地址 0x38 是否挂载成功并观察串口日志中touch_task是否有数据更新。小结Freenove ESP32-S3 Display 2.8 在 xiaozhi-esp32 中是一块小而完整的参考实现它同时涵盖了 ILI9341 SPI 显示、ES8311 音频编解码、电容触摸手势单击/双击/长按、ADC 电量监测与实体按键交互五大子系统。通过阅读 config.h 与 freenove-esp32s3-display-2.8-lcd.cc开发者不仅可以为手头这块板卡完成固件构建也能以此为模板快速把其他带触摸屏的 ESP32-S3 开发板接入小智语音生态。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考