xiaozhi-esp32 适配 Spotpear 小木马开发板SP-ESP32-S3-1.54-MUMA实战指南编译、硬件配置与源码实现解析【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本篇技术指南围绕 xiaozhi-esp32 开源项目中 Spotpear SP-ESP32-S3-1.54-MUMA 小木马开发板 的官方 README 展开讲解如何在 ESP-IDF 环境下完成目标芯片设置、菜单配置与固件编译并结合仓库源码深入剖析该板卡的 LCD 显示、ES8311 音频编解码、CST816D 电容触摸与电池电源管理实现。读完本文你将掌握从零编译该板卡固件的完整流程并理解其硬件引脚分配与底层驱动调用链。一、产品定位与核心功能SP-ESP32-S3-1.54-MUMA 是 Spotpear微雪生态伙伴推出的一款小木马造型的 ESP32-S3 智能语音开发板官方 README 给出的产品定位如下硬件平台ESP32-S3N16R8 版本即 16MB Flash 8MB PSRAM面向 AI 语音对话场景显示1.54 寸 ST7789 驱动 LCD分辨率 240x240功能可爱小木马外观支持天气时钟、SD 视频播放、AI 智能对话固件源码全部开源适合少儿编程学习可二次开发更多功能唤醒交互AI 小智支持语音唤醒触摸版本额外支持触摸唤醒与打断。该板卡在仓库中的完整适配代码位于 main/boards/spotpear/sp-esp32-s3-1.54-muma/共包含五个文件文件作用sp-esp32-s3-1.54-muma.cc板卡主实现继承WifiBoard初始化 LCD、音频、触摸、电源config.h板级硬件宏定义GPIO 引脚、屏幕参数、ADC 通道config.json构建描述manufacturer / type / target / buildspower_manager.h电池电量 ADC 采样、充电状态检测与低电量判断README.md官方产品说明与编译指引二、固件编译从 set-target 到 build 的完整流程官方 README 给出了一组简洁的四步编译命令适用于所有 ESP32-S3 板卡下面完整继承并补充每一步的含义。1. 配置编译目标为 ESP32S3idf.py set-target esp32s3该命令将工程目标芯片切换为 ESP32-S3。该板卡依赖此芯片目标仓库中 Kconfig.projbuild 的板卡选择项声明了depends on IDF_TARGET_ESP32S3即只有目标为 ESP32S3 时该板卡选项才会出现。2. 打开 menuconfigidf.py menuconfig进入 ESP-IDF 的图形化配置界面。3. 选择板卡Xiaozhi Assistant - Board Type - Spotpear ESP32-S3-LCD-1.54-MUMA在 menuconfig 的Xiaozhi Assistant - Board Type菜单中选中该项。它对应源码中的 Kconfig 配置BOARD_TYPE_SPOTPEAR_ESP32_S3_1_54_MUMA显示名 Spotpear ESP32-S3 1.54 MUMA选中后工程的 CMakeLists.txt 会将BOARD_DIR指向spotpear/sp-esp32-s3-1.54-muma从而把该目录下的源文件纳入编译。4. 编译idf.py build编译产物可直接通过idf.py flash monitor烧录到开发板并查看串口日志。三、硬件资源配置config.h 逐项解读config.h 集中定义了整块板卡的硬件抽象下面按功能模块拆解。音频通路ES8311 编解码器 I2S#define AUDIO_INPUT_SAMPLE_RATE 24000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 #define AUDIO_I2S_GPIO_MCLK GPIO_NUM_16 //MCLK #define AUDIO_I2S_GPIO_WS GPIO_NUM_45 //LRCK #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_9 //SCLK #define AUDIO_I2S_GPIO_DIN GPIO_NUM_10 //DOUT #define AUDIO_I2S_GPIO_DOUT GPIO_NUM_8 //DIN #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采样率统一为 24kHzxiaozhi 的音频引擎默认处理频率音频编解码芯片为 ES8311通过 I2CSDA15 / SCL14进行寄存器配置I2S 负责音频数据传输PA功放使能引脚为 GPIO46源码中GetAudioCodec()用Es8311AudioCodec组装了上述全部参数见 sp-esp32-s3-1.54-muma.cc。显示屏1.54 寸 ST7789240x240#define DISPLAY_WIDTH 240 #define DISPLAY_HEIGHT 240 #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_42 #define DISPLAY_BACKLIGHT_OUTPUT_INVERT true #define DISPLAY_SPI_SCLK_PIN GPIO_NUM_4 #define DISPLAY_SPI_MOSI_PIN GPIO_NUM_2 #define DISPLAY_SPI_CS_PIN GPIO_NUM_5 #define DISPLAY_SPI_DC_PIN GPIO_NUM_47 #define DISPLAY_SPI_RESET_PIN GPIO_NUM_38 #define DISPLAY_SPI_SCLK_HZ (40 * 1000 * 1000)屏幕通过 SPI 接口驱动SPI3_HOST 总线时钟频率最高 40MHz背光使用 PWM 控制PwmBacklight且OUTPUT_INVERT true表示背光为低电平点亮源码中InitializeSt7789Display()调用了esp_lcd_new_panel_st7789创建面板并发送 ST7789 的 0xBB 寄存器命令值 0x38做显示优化同时执行esp_lcd_panel_invert_color(panel, true)反转颜色见 sp-esp32-s3-1.54-muma.cc。电容触摸CST816D#define TP_PIN_NUM_TP_SDA (GPIO_NUM_11) #define TP_PIN_NUM_TP_SCL (GPIO_NUM_7) #define TP_PIN_NUM_TP_RST (GPIO_NUM_6) #define TP_PIN_NUM_TP_INT (GPIO_NUM_12)触摸芯片为 CST816D挂在独立于音频编解码器的第二条 I2C 总线上I2C_NUM_1器件地址 0x15。板卡构造时会先读取 INT 引脚电平判断触摸屏是否存在电平为 1 才初始化触摸见 sp-esp32-s3-1.54-muma.cc这也是 README 中触摸版本额外支持的由来——非触摸版该引脚不会拉高。按键与指示灯#define BUILTIN_LED_GPIO GPIO_NUM_48 #define BOOT_BUTTON_GPIO GPIO_NUM_0GPIO48 为板载单色 LED通过SingleLed驱动用于指示设备状态如联网中、对话中GPIO0 为 BOOT 按键短按逻辑与触摸一致设备处于启动状态kDeviceStateStarting时进入 WiFi 配网模式否则切换对话状态见 sp-esp32-s3-1.54-muma.cc。四、触摸与按键的交互实现原理小木马触摸版的核心交互由定时器轮询实现相关逻辑在 sp-esp32-s3-1.54-muma.cc创建一个10ms 周期的 esp_timer持续调用UpdateTouchPoint()读取 CST816D 的 6 字节触摸寄存器起始地址 0x02触摸坐标由寄存器 1~4 解析x ((buf[1] 0x0F) 8) | buf[2]y ((buf[3] 0x0F) 8) | buf[4]点数取buf[0] 0x0F通过记录按下与释放时刻区分短触500ms与长按≥500ms只有短触才触发交互动作短触动作同样分流设备未就绪kDeviceStateStarting时调用EnterWifiConfigMode()进入配网否则调用app.ToggleChatState()开始/结束对话实现触摸唤醒与打断。五、电源管理与低功耗策略充电检测与电池电量板卡通过 GPIO41 检测充电状态高电平为充电中并通过 ADC1 通道 0 采样电池电压。power_manager.h 内部实现了滑动平均滤波保留最近 3 次 ADC 采样值取平均抑制噪声分段线性插值按 ADC 值区间1980/2081/2163/2250/2340/2480对应 0/20/40/60/80/100% 电量区间内线性插值超出边界直接钳位低电量告警电量 ≤20% 时触发on_low_battery_status_changed回调充电检测每 100ms 定时执行一次充电状态变化时立即重新采样电池数据。休眠与关机板卡构造时初始化了PowerSaveTimer(-1, 60, 300)语义为空闲 60 秒进入休眠模式关闭显示、背光降到 1300 秒后请求关机。关机流程见 sp-esp32-s3-1.54-muma.cc将 GPIO3供电保持引脚拉低并调用rtc_gpio_hold_en保持电平切断系统供电调用esp_lcd_panel_disp_on_off(panel_, false)关闭显示最后esp_deep_sleep_start()进入深度睡眠实现真正的低功耗待机。同时GetBatteryLevel()会依据充电/放电状态动态启停省电定时器充电时禁用省电放电时启用省电避免充电过程中误进入休眠见 sp-esp32-s3-1.54-muma.cc。六、构建配置与二次开发要点板卡的构建元数据定义在 config.json{ manufacturer: spotpear, type: sp-esp32-s3-1.54-muma, target: esp32s3, builds: [ { name: sp-esp32-s3-1.54-muma, sdkconfig_append: [] } ] }target: esp32s3与 menuconfig 中的depends on IDF_TARGET_ESP32S3约束一致编译前必须idf.py set-target esp32s3sdkconfig_append为空数组表示该板卡不需要额外的 sdkconfig 片段直接复用工程根目录的 sdkconfig.defaults.esp32s3。若想基于该板卡做二次开发可重点关注以下扩展点更换唤醒词 / 音频处理仓库 main/audio 下的引擎与唤醒词组件均可复用板卡侧无需改动自定义 UI 表情显示层基于 LVGL可参考 main/display/lvgl_display 修改对话表情与界面新增外设从Spotpear_esp32_s3_lcd_1_54类继承自 WifiBoard派生的各Initialize*方法即为模板例如在InitializeSpi()基础上扩展 SD 卡README 提及的 SD 视频播放能力即可复用同一 SPI 总线。七、总结SP-ESP32-S3-1.54-MUMA 小木马开发板在 xiaozhi-esp32 中是一套**WiFi 板 ST7789 圆屏 ES8311 音频 CST816D 触摸 电源管理**的完整参考实现官方 README 提供了四步编译流程仓库源码则给出了可运行的硬件初始化与低功耗策略。对照本文的引脚表与源码调用链开发者既可以快速烧录体验天气时钟 AI 对话 语音唤醒/触摸打断的完整功能也可以在此基础上按需裁剪或扩展将其改造为适合儿童编程教育或桌面 AI 助手的个性化设备。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考