企业官网建设流程全解析

为 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.json（manufacturer 为xorigin，type 为aipi-lite，build 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 esp32s3

AiPi-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 中的硬件定义决定了固件如何驱动这块板卡，理解它们有助于排错与定制：

其中电源与电量管理由板卡目录下的 power_manager.h 实现：它以 100 ms 周期定时器轮询充电引脚状态，并通过 ADC1 采集电池电压，在{1480, 0}…{1980, 100}六个标定点之间做线性插值得到电量百分比，电量低于 20% 时触发低电量回调。充电时 aipi-lite.cc 会暂停省电定时器，拔电后恢复。

按键行为定义在 aipi-lite.cc：BOOT 键单击唤醒并在设备就绪后切换对话状态，长按进入 WiFi 配网模式；电源键长按在非充电或未满电时关闭显示并进入深度睡眠（esp_deep_sleep_start）。

四、编译与烧录（含出厂信息备份警告）

完成配置后，使用以下命令构建并烧录：

idf.py -DBOARD_NAME=aipi-lite build flash

说明：

• -DBOARD_NAME=aipi-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

参数含义：

完成备份后，再执行上文的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