为 XOrigin AiPi-Lite 编译与烧录 xiaozhi-esp32 固件一键构建、手动配置与出厂信息备份指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本指南面向想要把基于 MCP 的聊天机器人固件xiaozhi-esp32部署到XOrigin AiPi-Lite开发板的开发者。文章以板卡官方构建说明main/boards/xorigin/aipi-lite/README_en.md为主线完整覆盖一键编译、手动配置、烧录与烧录前必须执行的出厂信息备份操作并结合仓库内该板卡的源码实现aipi-lite.cc、config.h、power_manager.h深入说明板卡配置的含义。读完本文你将能独立完成 AiPi-Lite 的固件构建、烧录与安全的设备信息保全。一、板卡背景与适用前提XOrigin AiPi-Lite 是一块基于ESP32-S3的 AI 语音交互开发板在 xiaozhi-esp32 仓库中归属于xorigin制造商板卡类型为aipi-lite见 config.json。它自带 128×128 彩色 LCD 屏、ES8311 音频编解码器、板载 LED 与电源管理电路非常适合用作桌面 AI 语音助手终端。在开始编译前请确认以下前提本板卡的目标芯片为ESP32-S3编译时必须将 IDF 目标设置为esp32s3需要已安装 ESP-IDF 开发环境并已执行idf.py set-target初始化若设备在出厂时预装的是AiPi-Lite 原厂固件非小智版本烧录前务必先阅读本文第四节完成出厂信息备份否则可能造成设备信息如 EUI被擦除且无法恢复。二、一键编译推荐仓库提供了统一构建脚本 scripts/build.py它会自动完成板卡配置、目标设置、依赖管理、编译与固件合并merge-bin。对 AiPi-Lite 一键编译的命令为python scripts/build.py xorigin/aipi-lite --language en-US参数说明xorigin/aipi-lite板卡路径与 main/boards/xorigin/aipi-lite 目录结构对应。脚本会读取该目录下的config.jsonmanufacturer 为xorigintype 为aipi-litebuild name 为aipi-lite来确定板卡标识--language en-US指定固件默认语言为美式英语对应仓库 main/assets/locales/en-US 中的语音与文案资源。若需其他语言如zh-CN、ja-JP改为对应 locale 目录名即可语言资源可在 main/assets/locales 中查看全部可选值。脚本内部会调用idf.py系列命令对应_run_idf逻辑并在编译成功后执行idf.py merge-bin生成build/merged-binary.bin合并固件。从源码结构可以推断esp32s3属于_AFE_WAKE_WORD_TARGETS见 scripts/build.py因此该板卡会默认启用 AFE 唤醒词引擎。三、手动配置与编译进阶如果希望精细控制每一个编译选项可以走标准 ESP-IDF 手动流程。3.1 设置目标芯片idf.py set-target esp32s3AiPi-Lite 的主控是 ESP32-S3该命令会为项目生成适配该芯片的 sdkconfig。3.2 配置菜单选择板卡idf.py menuconfig在菜单中按如下路径选择板卡Xiaozhi Assistant - Target Board - XOrigin AiPi-Lite选择后menuconfig 会把CONFIG_BOARD_TYPE等配置项指向aipi-lite板卡。仓库根目录下的 sdkconfig.defaults.esp32s3 会提供 ESP32-S3 平台的通用默认配置板卡专用参数则由 config.h 在编译期注入。3.3 板卡关键配置解读选中板卡后config.h 中的硬件定义决定了固件如何驱动这块板卡理解它们有助于排错与定制配置项取值说明AUDIO_INPUT_SAMPLE_RATE/AUDIO_OUTPUT_SAMPLE_RATE24000音频采样率 24 kHz与 ESP32-S3 的 AFE 音频引擎配置相匹配AUDIO_I2S_GPIO_MCLK/WS/BCLK/DIN/DOUTGPIO 6/12/14/13/11I2S 音频总线引脚连接 ES8311 编解码器AUDIO_CODEC_ES8311_ADDR默认地址ES8311 的 I2C 地址由 es8311_audio_codec.h 定义AUDIO_CODEC_PA_PINGPIO 9功放使能引脚DISPLAY_WIDTH/HEIGHT128×128LCD 分辨率DISPLAY_SWAP_XYtrue屏幕需交换 X/Y 轴竖屏/横屏适配DISPLAY_RGB_ORDERBGRST7789 面板的 RGB 像素顺序DISPLAY_SPI_*SCLK 16 / MOSI 17 / CS 15 / DC 7 / RST 18LCD 的 SPI 接口引脚SPI 时钟 20 MHz见DISPLAY_SPI_SCLK_HZ由 aipi-lite.cc 中InitializeSpi初始化 SPI3 主机BOOT_BUTTON_GPIOGPIO 42主交互按键短按切换对话、长按进入配网POWER_BUTTON_GPIOGPIO 1电源键长按关机POWER_CONTROL_PINGPIO 10电源自锁控制引脚关机时通过 RTC GPIO 拉低断电POWER_CHARGE_DETECT_PINGPIO 8充电状态检测引脚POWER_ADC_UNIT/CHANNELADC1 / CH1电池电压采样通道用于电量估算其中电源与电量管理由板卡目录下的 power_manager.h 实现它以 100 ms 周期定时器轮询充电引脚状态并通过 ADC1 采集电池电压在{1480, 0}…{1980, 100}六个标定点之间做线性插值得到电量百分比电量低于 20% 时触发低电量回调。充电时 aipi-lite.cc 会暂停省电定时器拔电后恢复。按键行为定义在 aipi-lite.ccBOOT 键单击唤醒并在设备就绪后切换对话状态长按进入 WiFi 配网模式电源键长按在非充电或未满电时关闭显示并进入深度睡眠esp_deep_sleep_start。四、编译与烧录含出厂信息备份警告完成配置后使用以下命令构建并烧录idf.py -DBOARD_NAMEaipi-lite build flash说明-DBOARD_NAMEaipi-lite显式指定板卡标识与 config.json 中的type/name一致build编译固件flash通过串口烧录到设备。4.1 重要警告原厂 AiPi-Lite 设备信息如果你的设备出厂时预装的是AiPi-Lite 原厂固件非小智版本请特别小心处理 Flash 固件分区地址以避免错误擦除 AiPi-Lite 自身的设备信息如 EUI 等。否则即使之后恢复 Xorigin 原厂固件设备也可能无法正确连接 Xorigin 服务器原因在于AiPi-Lite 的联网凭据用于连接 SenseCraft 服务器存放在板卡的出厂信息分区中。该分区位于 Flash 的0x9000偏移处大小 16384 字节。若小智固件的分区表见 partitions 目录覆盖或擦除了这段区域EUI 等身份信息将永久丢失导致设备无法被服务器识别。因此在刷写固件之前请务必记录设备的相关必要信息确保有可恢复的手段。4.2 备份出厂信息分区使用 esptool 将包含服务器连接凭据的出厂信息分区读取出来保存为本地备份文件# 备份包含 SenseCraft 服务器连接凭据的出厂信息分区 esptool.py --chip esp32s3 --baud 2000000 --before default_reset --after hard_reset --no-stub read_flash 0x9000 16384 nvsfactory.bin参数含义参数说明--chip esp32s3指定芯片型号与板卡主控一致--baud 2000000串口波特率 2 Mbps加速读取--before default_reset/--after hard_reset读取前执行默认复位、读取后硬件复位--no-stub不使用 RAM stub直接通过 ROM 引导加载器读取read_flash 0x9000 16384从地址0x9000开始读取16384字节即 16 KBnvsfactory.bin备份输出文件名请妥善保存烧录小智固件后如需恢复原厂环境可用它回写完成备份后再执行上文的build flash烧录小智固件。若日后需要恢复 Xorigin 原厂环境可借助该备份文件还原出厂信息分区。五、烧录后的验证与常见问题开机配网首次启动若处于kDeviceStateStarting状态短按 BOOT 键会进入 WiFi 配网模式也可在任意时刻长按 BOOT 键强制进入配网对应 aipi-lite.cc确认板卡识别烧录后串口日志中 TAG 为AIPI-Lite若日志中出现屏幕初始化与 ES8311 初始化错误请对照 config.h 核对 SPI/I2C 引脚定义无法连接服务器若此前未备份就刷写过固件且连接异常优先检查出厂信息分区是否完好回写备份后重试电量显示异常可查看串口中PowerManager的 ADC 值与电量百分比日志若偏差较大需检查电池采样电路与标定点。六、参考文件板卡官方构建说明中文版main/boards/xorigin/aipi-lite/README.md板卡官方构建说明英文版main/boards/xorigin/aipi-lite/README_en.md板卡源码实现main/boards/xorigin/aipi-lite/aipi-lite.cc板卡引脚配置main/boards/xorigin/aipi-lite/config.h电源与电量管理main/boards/xorigin/aipi-lite/power_manager.h板卡元数据制造商/类型/构建名main/boards/xorigin/aipi-lite/config.json统一构建脚本scripts/build.py分区表定义partitions【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考