xiaozhi-esp32 适配实战Spotpear ESP32-S3 1.28 英寸圆屏 Box 开发板编译指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文以 xiaozhi-esp32 开源项目中的 Spotpear ESP32-S3 1.28 Box 开发板说明 为核心系统讲解如何为这款带触摸、可充电的圆形 1.28 英寸 LCD 外壳开发板配置并编译固件。读完本文你将掌握从idf.py set-target到menuconfig板型选择、再到idf.py build的完整编译流程并能结合板级源码理解其 GC9A01 圆屏、CST816D 触摸、ES8311 音频与电源管理模块的底层实现。开发板概述与硬件特性Spotpear ESP32-S3 1.28 Box 是一款以 ESP32-S3N16R8即 16MB Flash 8MB PSRAM为核心、配备 1.28 英寸圆形 LCD 的 AI 语音盒子开发板。依据其 README 的产品简介该开发板具备三项突出特性支持触摸圆屏表面集成电容触摸可直接通过触摸完成唤醒、打断、切换对话等交互支持充电板载锂电池充电管理电路可在充电状态下自动调整省电策略独特外形设计圆形屏幕配合盒体结构适合作为桌面级 AI 陪伴终端。在 xiaozhi-esp32 项目中该开发板属于spotpear厂商目录下的一个独立板型sp-esp32-s3-1.28-box拥有完整的板级配置、板级初始化源码与自动化构建描述是体验开箱即编译的典型板型之一。编译前置设置目标芯片该开发板基于 ESP32-S3 芯片因此编译的第一步是让 ESP-IDF 构建系统以 ESP32-S3 为目标生成构建配置idf.py set-target esp32s3该命令会清除并重新生成与芯片型号相关的sdkconfig配置。首次配置或更换目标芯片后必须执行此步骤且后续所有menuconfig中的板型选项都会受目标芯片约束见下文构建系统集成。打开 menuconfig 并选择板型配置编译目标后进入交互式配置菜单idf.py menuconfig在菜单中按如下路径导航选择开发板Xiaozhi Assistant - Board Type - Spotpear ESP32-S3-1.28-BOX选中后保存退出。对应到源码该板型在 main/Kconfig.projbuild 中定义为config BOARD_TYPE_SPOTPEAR_ESP32_S3_1_28_BOX bool Spotpear ESP32-S3 1.28 Box depends on IDF_TARGET_ESP32S3depends on IDF_TARGET_ESP32S3正是只有在set-target esp32s3之后该选项才会出现在菜单中的原因。若尚未执行 set-target 或目标芯片不是 ESP32-S3该板型选项不会显示。编译固件完成板型选择后执行idf.py build编译产物位于build/目录。如需烧录并查看日志可继续执行idf.py flash monitor除了手动idf.py流程项目还提供了脚本化构建方式python scripts/build.py sp-esp32-s3-1.28-box可参考 docs/custom-board_zh.md 中关于build.py的说明。脚本会自动读取板目录下config.json中的target与构建变体信息并通过一次idf.py reconfigure完成目标芯片、板型、defaults 与sdkconfig_append的配置随后复用该配置执行idf.py build默认生成build/merged-binary.bin。板级源码与硬件映射解析选择该板型后构建系统会通过 main/CMakeLists.txt 中的映射加载板级目录elseif(CONFIG_BOARD_TYPE_SPOTPEAR_ESP32_S3_1_28_BOX) set(BOARD_DIR spotpear/sp-esp32-s3-1.28-box) set(BUILTIN_TEXT_FONT font_noto_sans_basic_16_4) set(BUILTIN_ICON_FONT font_material_symbols_16_4) set(DEFAULT_EMOJI_COLLECTION noto-color-emoji_64)该板型使用 16x4 字号的内置文字字体与图标字体并配置了 64x64 的 emoji 表情集合适配 240×240 的小尺寸圆屏。板级目录共包含四个文件sp-esp32-s3-1.28-box.cc— 板级初始化与功能实现主源码config.h— 硬件管脚映射与参数配置config.json— 板型上报类型与自动化编译配置power_manager.h— 电池电量检测与充电状态管理板内私有头文件README.md— 板型说明文档引脚映射表config.h 完整定义了该板所有外设的 GPIO 映射整理如下功能模块宏定义GPIO说明音频采样率AUDIO_INPUT_SAMPLE_RATE/AUDIO_OUTPUT_SAMPLE_RATE—均为 24000 HzI2SAUDIO_I2S_GPIO_MCLKGPIO16主时钟 MCLKI2SAUDIO_I2S_GPIO_WSGPIO45字选择 LRCKI2SAUDIO_I2S_GPIO_BCLKGPIO9位时钟 SCLKI2SAUDIO_I2S_GPIO_DINGPIO10数据输出 DOUT接 codecI2SAUDIO_I2S_GPIO_DOUTGPIO8数据输入 DIN接 codec音频功放AUDIO_CODEC_PA_PINGPIO46PA 使能音频 I2CAUDIO_CODEC_I2C_SDA_PIN/SCL_PINGPIO15 / GPIO14ES8311 控制总线编解码器AUDIO_CODEC_ES8311_ADDR—ES8311 默认 I2C 地址LEDBUILTIN_LED_GPIOGPIO48板载单 LED按键BOOT_BUTTON_GPIOGPIO0BOOT 按键显示参数DISPLAY_WIDTH/HEIGHT—240 × 240显示镜像DISPLAY_MIRROR_X/MIRROR_Y/SWAP_XY—true / false / false显示偏移DISPLAY_OFFSET_X/OFFSET_Y—0 / 0背光DISPLAY_BACKLIGHT_PINGPIO42输出反相OUTPUT_INVERT trueSPIDISPLAY_SPI_SCLK_PIN/MOSI_PINGPIO4 / GPIO2屏幕 SPI 时钟与数据SPIDISPLAY_SPI_CS_PIN/DC_PIN/RESET_PINGPIO5 / GPIO47 / GPIO38片选、数据/命令、复位SPI 频率DISPLAY_SPI_SCLK_HZ—40 MHz触摸 I2CTP_PIN_NUM_TP_SDA/TP_SCLGPIO11 / GPIO7CST816D 数据总线触摸控制TP_PIN_NUM_TP_RST/TP_INTGPIO6 / GPIO12复位与中断引脚电池 ADCBATTERY_ADC_PINGPIO1电池电压检测充电检测BATTERY_CHARGING_PINGPIO41充电状态输入config.json 与板型上报config.json 用于上报板型并驱动自动化编译{ manufacturer: spotpear, type: sp-esp32-s3-1.28-box, target: esp32s3, builds: [ { name: sp-esp32-s3-1.28-box, sdkconfig_append: [] } ] }其中type是固件上报的开发板系列类型发布后应保持稳定直接影响 OTA 升级通道target指定目标芯片name是 release 构建上报的固件变体名称。该板与项目默认配置一致因此sdkconfig_append为空未额外覆盖 Flash 大小或分区表。硬件组成与底层实现1.28 英寸圆形屏GC9A01 驱动在 sp-esp32-s3-1.28-box.cc 中屏幕初始化分为两步先通过GC9A01_PANEL_BUS_SPI_CONFIG在SPI3_HOST上初始化 SPI 总线DMA 自动分配再以esp_lcd_new_panel_gc9a01创建 GC9A01 面板驱动。初始化序列包含使能颜色反转esp_lcd_panel_invert_color(panel_handle, true)与 X 方向镜像esp_lcd_panel_mirror(panel_handle, true, false)通过esp_lcd_panel_io_tx_param写入 0x62、0x63、0x36、0xC3、0xC4 等厂商寄存器配置伽马与显示方向设定创建CustomLcdDisplay显示对象。由于屏幕是圆形的CustomLcdDisplay::SetupUI()在调用父类创建 LVGL 对象后为状态栏额外设置了左右 33% 水平分辨率的内边距lv_obj_set_style_pad_left(status_bar_, LV_HOR_RES * 0.33, 0)避免文字顶到圆屏边缘。触摸交互CST816D 驱动板级源码内置了一个完整的 CST816D 电容触摸驱动类Cst816d实现方式包括探测通过Probe()在 I2C 地址 0x15 上读取芯片 ID寄存器 0xA3判断触摸芯片是否在线若探测失败会删除触摸 I2C 总线并以无触摸模式继续运行InitializeCst816DTouchPad()中打印CST816D not found, running in non-touch mode。数据读取UpdateTouchPoint()从寄存器 0x02 起连续读取 6 字节解析出触摸点数与 x/y 坐标。交互逻辑touchpad_timer_callback以 10ms 周期轮询触摸状态并实现短触/长按区分——触摸时长超过 500ms 视为长按只有短触才会触发动作。短触动作与 BOOT 按键一致设备处于启动态未连接时进入 Wi-Fi 配置模式EnterWifiConfigMode()否则切换对话状态app.ToggleChatState()。触摸芯片的 RST 引脚初始化时执行了复位序列拉低 5ms、拉高 50msINT 引脚配置为上拉输入。音频链路ES8311 编解码器GetAudioCodec()使用板级静态实例Es8311AudioCodec构造参数依次为音频 I2C 总线、I2C 端口号、输入/输出采样率24kHz、MCLK/BCLK/WS/DOUT/DIN 引脚、PA 使能引脚与 I2C 地址。音频控制总线使用I2C_NUM_0而触摸使用独立的I2C_NUM_1两条 I2C 总线物理隔离避免外设间互相干扰。在关机流程中系统会先关闭 ES8311 的输入与输出codec-EnableInput(false)/EnableOutput(false)再进入深度睡眠。电源管理与省电策略板级实现了完整的电池管理电量检测PowerManager见 power_manager.h通过 ADCADC_CHANNEL_012 位宽、12dB 衰减每 100ms 定时采样电池电压取最近 3 次采样的平均值再依据{1980,0}、{2081,20}、{2163,40}、{2250,60}、{2340,80}、{2480,100}的分段表做线性插值得到电量百分比电量 ≤20% 时判定低电量。充电检测BATTERY_CHARGING_PINGPIO41作为输入读取充电状态充电状态变化会触发回调充电时禁用省电定时器未充电时重新启用。省电定时器PowerSaveTimer(-1, 60, 290)负责空闲休眠调度。进入休眠模式时关闭显示、将背光亮度降至 1关机时拉低 GPIO3 电平并启用 RTC GPIO 保持rtc_gpio_hold_en关闭面板esp_lcd_panel_disp_on_off(panel_, false)后调用esp_deep_sleep_start()进入深度睡眠。电量上报GetBatteryLevel()向应用层返回电量、充电与放电状态并仅在放电状态变化时切换省电定时器避免频繁抖动。此外SetPowerSaveLevel()在收到非LOW_POWER等级时调用power_save_timer_-WakeUp()唤醒设备保证用户交互时设备及时响应。注意事项必须执行set-targetBOARD_TYPE_SPOTPEAR_ESP32_S3_1_28_BOX依赖IDF_TARGET_ESP32S3未先设置目标芯片会导致板型选项缺失。保持板型标识唯一config.json中的type会作为固件上报的开发板类型并决定 OTA 升级通道自定义改动时切勿直接覆盖原有板型配置详见 docs/custom-board_zh.md。触摸可用性若 CST816D 探测失败板子会自动降级为无触摸模式仅保留 BOOT 按键交互此时代码会释放触摸 I2C 总线避免反复报错。省电与充电充电状态下省电定时器会被禁用避免充电过程中设备误入休眠电量采样表基于特定硬件如需适配其他电池应在power_manager.h的levels[]表中按实际硬件调整 ADC 阈值。通过以上流程你可以在 xiaozhi-esp32 项目中完成 Spotpear ESP32-S3 1.28 Box 固件的配置、编译与烧录并借助板级源码深入理解圆屏显示、触摸交互、音频编解码与电源管理的完整实现链路。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaozhi-esp32 适配实战：Spotpear ESP32-S3 1.28 英寸圆屏 Box 开发板编译指南
xiaozhi-esp32 适配实战Spotpear ESP32-S3 1.28 英寸圆屏 Box 开发板编译指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文以 xiaozhi-esp32 开源项目中的 Spotpear ESP32-S3 1.28 Box 开发板说明 为核心系统讲解如何为这款带触摸、可充电的圆形 1.28 英寸 LCD 外壳开发板配置并编译固件。读完本文你将掌握从idf.py set-target到menuconfig板型选择、再到idf.py build的完整编译流程并能结合板级源码理解其 GC9A01 圆屏、CST816D 触摸、ES8311 音频与电源管理模块的底层实现。开发板概述与硬件特性Spotpear ESP32-S3 1.28 Box 是一款以 ESP32-S3N16R8即 16MB Flash 8MB PSRAM为核心、配备 1.28 英寸圆形 LCD 的 AI 语音盒子开发板。依据其 README 的产品简介该开发板具备三项突出特性支持触摸圆屏表面集成电容触摸可直接通过触摸完成唤醒、打断、切换对话等交互支持充电板载锂电池充电管理电路可在充电状态下自动调整省电策略独特外形设计圆形屏幕配合盒体结构适合作为桌面级 AI 陪伴终端。在 xiaozhi-esp32 项目中该开发板属于spotpear厂商目录下的一个独立板型sp-esp32-s3-1.28-box拥有完整的板级配置、板级初始化源码与自动化构建描述是体验开箱即编译的典型板型之一。编译前置设置目标芯片该开发板基于 ESP32-S3 芯片因此编译的第一步是让 ESP-IDF 构建系统以 ESP32-S3 为目标生成构建配置idf.py set-target esp32s3该命令会清除并重新生成与芯片型号相关的sdkconfig配置。首次配置或更换目标芯片后必须执行此步骤且后续所有menuconfig中的板型选项都会受目标芯片约束见下文构建系统集成。打开 menuconfig 并选择板型配置编译目标后进入交互式配置菜单idf.py menuconfig在菜单中按如下路径导航选择开发板Xiaozhi Assistant - Board Type - Spotpear ESP32-S3-1.28-BOX选中后保存退出。对应到源码该板型在 main/Kconfig.projbuild 中定义为config BOARD_TYPE_SPOTPEAR_ESP32_S3_1_28_BOX bool Spotpear ESP32-S3 1.28 Box depends on IDF_TARGET_ESP32S3depends on IDF_TARGET_ESP32S3正是只有在set-target esp32s3之后该选项才会出现在菜单中的原因。若尚未执行 set-target 或目标芯片不是 ESP32-S3该板型选项不会显示。编译固件完成板型选择后执行idf.py build编译产物位于build/目录。如需烧录并查看日志可继续执行idf.py flash monitor除了手动idf.py流程项目还提供了脚本化构建方式python scripts/build.py sp-esp32-s3-1.28-box可参考 docs/custom-board_zh.md 中关于build.py的说明。脚本会自动读取板目录下config.json中的target与构建变体信息并通过一次idf.py reconfigure完成目标芯片、板型、defaults 与sdkconfig_append的配置随后复用该配置执行idf.py build默认生成build/merged-binary.bin。板级源码与硬件映射解析选择该板型后构建系统会通过 main/CMakeLists.txt 中的映射加载板级目录elseif(CONFIG_BOARD_TYPE_SPOTPEAR_ESP32_S3_1_28_BOX) set(BOARD_DIR spotpear/sp-esp32-s3-1.28-box) set(BUILTIN_TEXT_FONT font_noto_sans_basic_16_4) set(BUILTIN_ICON_FONT font_material_symbols_16_4) set(DEFAULT_EMOJI_COLLECTION noto-color-emoji_64)该板型使用 16x4 字号的内置文字字体与图标字体并配置了 64x64 的 emoji 表情集合适配 240×240 的小尺寸圆屏。板级目录共包含四个文件sp-esp32-s3-1.28-box.cc— 板级初始化与功能实现主源码config.h— 硬件管脚映射与参数配置config.json— 板型上报类型与自动化编译配置power_manager.h— 电池电量检测与充电状态管理板内私有头文件README.md— 板型说明文档引脚映射表config.h 完整定义了该板所有外设的 GPIO 映射整理如下功能模块宏定义GPIO说明音频采样率AUDIO_INPUT_SAMPLE_RATE/AUDIO_OUTPUT_SAMPLE_RATE—均为 24000 HzI2SAUDIO_I2S_GPIO_MCLKGPIO16主时钟 MCLKI2SAUDIO_I2S_GPIO_WSGPIO45字选择 LRCKI2SAUDIO_I2S_GPIO_BCLKGPIO9位时钟 SCLKI2SAUDIO_I2S_GPIO_DINGPIO10数据输出 DOUT接 codecI2SAUDIO_I2S_GPIO_DOUTGPIO8数据输入 DIN接 codec音频功放AUDIO_CODEC_PA_PINGPIO46PA 使能音频 I2CAUDIO_CODEC_I2C_SDA_PIN/SCL_PINGPIO15 / GPIO14ES8311 控制总线编解码器AUDIO_CODEC_ES8311_ADDR—ES8311 默认 I2C 地址LEDBUILTIN_LED_GPIOGPIO48板载单 LED按键BOOT_BUTTON_GPIOGPIO0BOOT 按键显示参数DISPLAY_WIDTH/HEIGHT—240 × 240显示镜像DISPLAY_MIRROR_X/MIRROR_Y/SWAP_XY—true / false / false显示偏移DISPLAY_OFFSET_X/OFFSET_Y—0 / 0背光DISPLAY_BACKLIGHT_PINGPIO42输出反相OUTPUT_INVERT trueSPIDISPLAY_SPI_SCLK_PIN/MOSI_PINGPIO4 / GPIO2屏幕 SPI 时钟与数据SPIDISPLAY_SPI_CS_PIN/DC_PIN/RESET_PINGPIO5 / GPIO47 / GPIO38片选、数据/命令、复位SPI 频率DISPLAY_SPI_SCLK_HZ—40 MHz触摸 I2CTP_PIN_NUM_TP_SDA/TP_SCLGPIO11 / GPIO7CST816D 数据总线触摸控制TP_PIN_NUM_TP_RST/TP_INTGPIO6 / GPIO12复位与中断引脚电池 ADCBATTERY_ADC_PINGPIO1电池电压检测充电检测BATTERY_CHARGING_PINGPIO41充电状态输入config.json 与板型上报config.json 用于上报板型并驱动自动化编译{ manufacturer: spotpear, type: sp-esp32-s3-1.28-box, target: esp32s3, builds: [ { name: sp-esp32-s3-1.28-box, sdkconfig_append: [] } ] }其中type是固件上报的开发板系列类型发布后应保持稳定直接影响 OTA 升级通道target指定目标芯片name是 release 构建上报的固件变体名称。该板与项目默认配置一致因此sdkconfig_append为空未额外覆盖 Flash 大小或分区表。硬件组成与底层实现1.28 英寸圆形屏GC9A01 驱动在 sp-esp32-s3-1.28-box.cc 中屏幕初始化分为两步先通过GC9A01_PANEL_BUS_SPI_CONFIG在SPI3_HOST上初始化 SPI 总线DMA 自动分配再以esp_lcd_new_panel_gc9a01创建 GC9A01 面板驱动。初始化序列包含使能颜色反转esp_lcd_panel_invert_color(panel_handle, true)与 X 方向镜像esp_lcd_panel_mirror(panel_handle, true, false)通过esp_lcd_panel_io_tx_param写入 0x62、0x63、0x36、0xC3、0xC4 等厂商寄存器配置伽马与显示方向设定创建CustomLcdDisplay显示对象。由于屏幕是圆形的CustomLcdDisplay::SetupUI()在调用父类创建 LVGL 对象后为状态栏额外设置了左右 33% 水平分辨率的内边距lv_obj_set_style_pad_left(status_bar_, LV_HOR_RES * 0.33, 0)避免文字顶到圆屏边缘。触摸交互CST816D 驱动板级源码内置了一个完整的 CST816D 电容触摸驱动类Cst816d实现方式包括探测通过Probe()在 I2C 地址 0x15 上读取芯片 ID寄存器 0xA3判断触摸芯片是否在线若探测失败会删除触摸 I2C 总线并以无触摸模式继续运行InitializeCst816DTouchPad()中打印CST816D not found, running in non-touch mode。数据读取UpdateTouchPoint()从寄存器 0x02 起连续读取 6 字节解析出触摸点数与 x/y 坐标。交互逻辑touchpad_timer_callback以 10ms 周期轮询触摸状态并实现短触/长按区分——触摸时长超过 500ms 视为长按只有短触才会触发动作。短触动作与 BOOT 按键一致设备处于启动态未连接时进入 Wi-Fi 配置模式EnterWifiConfigMode()否则切换对话状态app.ToggleChatState()。触摸芯片的 RST 引脚初始化时执行了复位序列拉低 5ms、拉高 50msINT 引脚配置为上拉输入。音频链路ES8311 编解码器GetAudioCodec()使用板级静态实例Es8311AudioCodec构造参数依次为音频 I2C 总线、I2C 端口号、输入/输出采样率24kHz、MCLK/BCLK/WS/DOUT/DIN 引脚、PA 使能引脚与 I2C 地址。音频控制总线使用I2C_NUM_0而触摸使用独立的I2C_NUM_1两条 I2C 总线物理隔离避免外设间互相干扰。在关机流程中系统会先关闭 ES8311 的输入与输出codec-EnableInput(false)/EnableOutput(false)再进入深度睡眠。电源管理与省电策略板级实现了完整的电池管理电量检测PowerManager见 power_manager.h通过 ADCADC_CHANNEL_012 位宽、12dB 衰减每 100ms 定时采样电池电压取最近 3 次采样的平均值再依据{1980,0}、{2081,20}、{2163,40}、{2250,60}、{2340,80}、{2480,100}的分段表做线性插值得到电量百分比电量 ≤20% 时判定低电量。充电检测BATTERY_CHARGING_PINGPIO41作为输入读取充电状态充电状态变化会触发回调充电时禁用省电定时器未充电时重新启用。省电定时器PowerSaveTimer(-1, 60, 290)负责空闲休眠调度。进入休眠模式时关闭显示、将背光亮度降至 1关机时拉低 GPIO3 电平并启用 RTC GPIO 保持rtc_gpio_hold_en关闭面板esp_lcd_panel_disp_on_off(panel_, false)后调用esp_deep_sleep_start()进入深度睡眠。电量上报GetBatteryLevel()向应用层返回电量、充电与放电状态并仅在放电状态变化时切换省电定时器避免频繁抖动。此外SetPowerSaveLevel()在收到非LOW_POWER等级时调用power_save_timer_-WakeUp()唤醒设备保证用户交互时设备及时响应。注意事项必须执行set-targetBOARD_TYPE_SPOTPEAR_ESP32_S3_1_28_BOX依赖IDF_TARGET_ESP32S3未先设置目标芯片会导致板型选项缺失。保持板型标识唯一config.json中的type会作为固件上报的开发板类型并决定 OTA 升级通道自定义改动时切勿直接覆盖原有板型配置详见 docs/custom-board_zh.md。触摸可用性若 CST816D 探测失败板子会自动降级为无触摸模式仅保留 BOOT 按键交互此时代码会释放触摸 I2C 总线避免反复报错。省电与充电充电状态下省电定时器会被禁用避免充电过程中设备误入休眠电量采样表基于特定硬件如需适配其他电池应在power_manager.h的levels[]表中按实际硬件调整 ADC 阈值。通过以上流程你可以在 xiaozhi-esp32 项目中完成 Spotpear ESP32-S3 1.28 Box 固件的配置、编译与烧录并借助板级源码深入理解圆屏显示、触摸交互、音频编解码与电源管理的完整实现链路。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考