小智 AI(xiaozhi-esp32) 复刻全流程
小智 AI(xiaozhi-esp32) 从采购、打印、组装到装软件、标定和训练的 263 个步骤,附物料表、购买链接与官方出处。
现成板卡 21.50 美元起:AtomS3R AI Chatbot Kit 21.50 美元、CoreS3 59.90 美元(M5Stack 商店),SenseCAP Watcher for XiaoZhi 49.90 美元(Seeed);不含运费。面包板方案物料见飞书百科,本次未核对
采购
- 考虑其他数字麦克风模块
ZTS6672 和 ICS43434 也可作为备选的麦克风模块。
- 检查替换麦克风模块
替换麦克风模块前,检查其引脚方向、通道和固件配置。
- 检查 HT517 模块规格
使用 HT517 放大器模块前,检查其实际输入、供电、使能行为和扬声器连接器规格。
- 检查扬声器负载与功率余量
如果考虑文档中的 4Ω 封闭式扬声器示例,需要单独检查放大器负载和功率余量。
- 准备 ESP32S3CAM 开发板
硬件基于 ESP32S3CAM 开发板,代码基于 bread-compact-wifi-lcd 修改。
- 准备 OV2640 摄像头
使用 OV2640 摄像头。
- 选用PDM麦克风
该盒子使用PDM麦克风。
- 选用共阳极LED
该盒子使用共阳极LED。
- 检查硬件兼容性
检查编解码器、PMIC 和触摸控制器组合的兼容性。
- 获取 electronBot 开源硬件
立创开源页面提供本版本的硬件,electronBot 官网提供项目入口。
- 购买手表形态套件
购买链接中提供的手表形态套件,文档称其是最便宜的套件之一。
组装
- 识别 INMP441 麦克风引脚
识别 INMP441 数字麦克风模块上的 VDD、GND、WS、SCK、SD 和 L/R 引脚。
- 连接 MAX98357A 与扬声器
使用接受数字 I2S 输入的 MAX98357A 数字放大器,并将扬声器连接在其两个输出端子之间。本指南使用 8Ω、3W 的封闭式扬声器。
- 排列并检查面包板
使用两块互锁的 400 点面包板,将控制器放在中间,模块放在两侧。断电后检查电源轨的通断,以及长电源轨是否在中途断开。
- 准备导线和可选按钮
使用短面包板跳线和杜邦线,为开发板和模块排针选择合适的接头。对于可选的轻触开关,安装前检查同一侧的引脚是否已经连通。
- 检查 OLED 引脚排列
选择 0.91 英寸 128×32 OLED 或 0.96 英寸 128×64 OLED。根据显示模块自身的标记检查引脚顺序以及 VCC/GND 位置。
- 连接麦克风
将麦克风的 SD 输出连接到固件的 DIN 输入。INMP441 的供电和通道选择请遵循 TDK 数据手册。如果麦克风排针焊接在另一侧,应识别朝上的一侧并按照匹配的信号标签连接;44 针和 42 针布局分别单独展示。
- 连接功放和扬声器
按照音频接线表连接功放和扬声器。SD/MODE 和 GAIN 应按照模块制造商的默认工作设置处理;如果裸模块需要电阻或使能信号,应先提供相应电路。MAX98357B 不是 A 的直接替代品,且不要将耳机连接到扬声器输出。没有面包板时,可按照图示进行麦克风到功放的直接接线,并根据本指南选择的供电方案及实际模块的工作要求调整图示的功放 3V3 供电和 SD/GAIN 连接。
- 对照完成后的组装
利用照片确认整体布局、焊接或杜邦线连接以及完成的 OLED 组装。按照上面的电源方案连接放大器和 4G;不要用导线颜色代替信号标签。
- 从相似开发板开始
复制并调整现有开发板,而不是从零开始。
- 检查所有引脚分配
确保 `config.h` 中定义的每个引脚都与原理图一致。
- 按引脚定义连接硬件
参考 config.h 文件中的引脚定义进行连线。由于摄像头占用较多 IO,ESP32S3 的 USB 19、20 两个引脚已被占用。
- 拆开电池以露出编程接口
组装产品前,将电池从主板上脱胶分开,以接触编程接口。
- 搭建 ESP32-S3 面包板项目
按照链接中的 ESP32-S3 面包板教程搭建这个练习项目。
软件与固件
- 定义硬件配置
创建 `config.h`,定义音频采样率、I2S 引脚映射、音频编解码器 I2C 地址和引脚、按键及 LED 引脚,以及显示参数和引脚。示例使用 24000 Hz 音频采样率和列出的 GPIO_NUM 映射。
- 创建板级构建配置
创建包含 `type`、`target` 和 `builds` 数组的 `config.json`,在 `builds` 中设置固件变体名称和 `sdkconfig_append` 条目。将 `target` 设置为实际硬件目标,例如 `esp32s3`,并在发布后保持 `type` 和 `name` 稳定;两者只能包含小写字母、数字、句点和连字符。
- 添加闪存、分区和音频设置
在 `sdkconfig_append` 中添加所需的闪存大小和分区表条目。需要启用设备端 AEC 时添加 `CONFIG_USE_DEVICE_AEC=y`,不要重复已经与有效项目默认值匹配的值;适用目标默认使用 16MB 闪存和 `partitions/v2/16m.csv`。
- 保留目标默认值
板级预设应保留目标默认值,仅将实际的板级专用覆盖项放入 `sdkconfig_append`。
- 排除用户界面选项
通过 `menuconfig` 或构建脚本参数一致地配置语言和唤醒词,使 CLI、agent 和在线构建使用相同接口。
- 排除唤醒词引擎预设
不要向板级或芯片预设添加 `CONFIG_USE_*_WAKE_WORD` 条目或模型选择,因为 `scripts/build.py` 会选择唤醒词引擎。
- 禁用唤醒词检测
出于内存、闪存或性能原因,可在 `sdkconfig_append` 中设置 `CONFIG_WAKE_WORD_DISABLED=y`。构建脚本会保留该退出选项,并将该变体的 `wake_word_supported` 报告为 `false`。
- 仅公开已实现的显示屏
仅当板级源码或配置引用对应的 `CONFIG_OLED_*` 或 `CONFIG_LCD_*` 符号时,才公开 `display_model` 选项。添加新型号时,应同时加入面板初始化、所需尺寸和背光设置;固定显示屏板级不公开型号选项。
- 创建板级源文件
创建 `my_custom_board.cc`,并在其中放置板级实现。
- 声明板级类
自定义类应派生自 `WifiBoard` 或 `Ml307Board`。示例使用派生自 `WifiBoard` 的 `MyCustomBoard`,并包含 I2C 总线句柄、启动按钮和显示屏指针。
- 添加板级初始化辅助函数
添加 I2C、显示屏、按钮以及 IoT/MCP 工具的初始化辅助函数。示例提供 `InitializeI2c()`,并开始实现 `InitializeSpi()`。
- 配置 I2C 总线
在 `I2C_NUM_0` 上配置编解码器 I2C 总线,使用 `AUDIO_CODEC_I2C_SDA_PIN` 和 `AUDIO_CODEC_I2C_SCL_PIN`、默认时钟源、毛刺忽略计数 7、中断优先级 0、传输队列深度 0,并启用内部上拉。通过 `ESP_ERROR_CHECK(i2c_new_master_bus(&i2c_bus_cfg, &codec_i2c_bus_))` 创建主总线。
- 开始初始化 SPI 总线
使用 `DISPLAY_SPI_MOSI_PIN`、`DISPLAY_SPI_SCK_PIN`,将 MISO 和未使用的四线数据引脚设为 `GPIO_NUM_NC`,并将最大传输大小设为 `DISPLAY_WIDTH * DISPLAY_HEIGHT * sizeof(uint16_t)`,以初始化 SPI 总线。
- 实现板级虚函数重写
实现所需的虚函数重写,包括 `GetAudioCodec()`、`GetDisplay()` 和 `GetBacklight()`。
- 注册板级类
使用 `DECLARE_BOARD(ClassName)` 注册板级类。
- 配置启动按钮操作
绑定启动按钮:设备处于启动状态时,点击后进入 Wi-Fi 配置模式;其他情况下,点击后切换聊天状态。
- 初始化 ST7789 SPI 显示屏
使用配置的 CS、DC 引脚在 SPI2_HOST 上创建 ST7789 面板,设置 SPI 模式 2、80 MHz 时钟、10 项传输队列以及 8 位命令和参数字段。配置 RGB 顺序、每像素 16 位、无复位引脚、颜色反转、XY 交换、镜像以及指定的显示尺寸和偏移。
- 构建自定义开发板
使用 BOOT_BUTTON_GPIO 构建开发板,并初始化 I2C、SPI、显示屏和按钮。将背光亮度设置为 100。
- 配置 ES8311 音频编解码器
使用 codec_i2c_bus_ 在 I2C_NUM_0 上创建静态 Es8311AudioCodec,并提供输入和输出采样率、MCLK、BCLK、WS、DOUT、DIN、PA 引脚及 ES8311 地址。
- 返回已初始化的显示屏
返回由 InitializeDisplay 创建的显示屏实例。
- 配置 PWM 背光
使用 DISPLAY_BACKLIGHT_PIN 和 DISPLAY_BACKLIGHT_OUTPUT_INVERT 创建静态 PwmBacklight,然后返回该实例。
- 添加自定义板卡 Kconfig 项
在 `main/Kconfig.projbuild` 的 `BOARD_TYPE` 选项中添加使用大写字母和下划线分隔的板卡标识符。使用 `depends on` 将其限制为匹配的 IDF 目标,并可按需本地化标签。
- 添加自定义板卡 CMake 分支
打开 `main/CMakeLists.txt`,为 `CONFIG_BOARD_TYPE_MY_CUSTOM_BOARD` 添加 `elseif` 分支,并在该分支中设置板卡目录、显示字体和可选的表情集合。
- 选择显示字体和表情
根据显示屏选择文字和图标字体:128x64 使用 `font_puhui_basic_14_1` 和 `font_awesome_14_1`;240x240 使用 16_4 字体;240x320 使用 20_4 字体;480x320 或更大使用 30_4 字体。小屏幕选择 `twemoji_32`,大屏幕选择 `twemoji_64`。
- 设置 ESP-IDF 目标芯片
首次构建或切换目标时,将目标设置为 ESP32-S3、ESP32-C3 或 ESP32。
- 清理旧配置
在配置开发板之前,移除已有的构建配置。
- 选择开发板类型
打开 menuconfig,进入 `Xiaozhi Assistant -> Board Type` 并选择所需开发板。
- 构建、烧录并监视
构建固件,将其烧录到开发板,并启动串口监视器。
- 自动配置并构建开发板
使用包含 `config.json` 的开发板目录运行构建脚本。
- 选择语言和唤醒词
构建时明确指定语言和 ESP-SR 唤醒词模型。
- 选择界面语言地区
Kconfig 默认值和脚本默认值均为 `en-US`;省略 `--language` 时会选择英文。使用 `zh-CN` 选择中文,或使用 `main/assets/locales/` 中列出的其他语言地区。该选项控制界面文字和语音提示。
- 使用默认唤醒词
在受支持的开发板上省略 `--wake-word` 时,脚本会为 `zh-CN` 和 `zh-TW` 选择“你好小智”,为其他语言选择“Hi ESP”。
- 覆盖唤醒词默认值
可传入 ESP-SR 模型名称、`nihaoxiaozhi`、`hiesp` 或 `disabled`。别名会为目标选择兼容的模型。
- 按芯片匹配唤醒词
ESP32-C3、C5 和 C6 使用 WakeNet9s(`wn9s_*`)模型。ESP32-S3、P4 和 S31 使用 AFE 引擎并要求 PSRAM;ESP32 同样要求 PSRAM,但不使用 AFE。
- 检查唤醒词支持情况
不受支持的开发板以及明确选择停用的板型变体会保持停用。在 SDK 配置前,启用这些板型唤醒词检测的请求会被拒绝。
- 替换打包的语音模型
Custom 和 Emote 资源会保留其 UI 资源,但其打包语音模型会替换为当前 `sdkconfig` 中选择的模型;停用唤醒词检测时则移除这些模型。最终数据包必须能够装入 assets 分区。
- 手动配置唤醒词
直接使用 `idf.py` 构建时,需要在 menuconfig 中明确选择唤醒词实现和模型。芯片默认值不会选择模型,全新的手动配置会停用唤醒词检测。
- 查询可用选项值
以文本或 JSON 格式列出语言和唤醒词。
- 先生成托管组件
如果尚未生成 `managed_components/`,先运行 reconfigure 再查询唤醒词,因为该列表读取自当前解析出的 ESP-SR 组件。
- 列出可用开发板
不带参数运行脚本会显示帮助。使用开发板列表选项可列出开发板类型及其变体。
标定与测试
- 配置分区表与设备端 AEC
在 sdkconfig_append 中选择 4MB 或 8MB 分区表,并通过 CONFIG_USE_DEVICE_AEC=y 启用设备端 AEC。适用的目标芯片默认使用 16MB Flash 和 partitions/v2/16m.csv。
- 保留用户构建选项
不要在板子的 config.json 中选择语言或具体唤醒词。这些选项应统一通过 menuconfig 或构建脚本参数配置,供 CLI、Agent 和在线编译接口共用。
- 分步实现并调试
先实现显示等基础功能,再添加音频等更复杂的功能。
- 检查硬件兼容性
确认所有芯片和驱动程序彼此兼容。
- 排查显示屏异常
如果显示屏不正常,检查 SPI 配置、镜像设置和颜色反转设置。
- 排查音频无输出
如果音频没有输出,检查 I2S 配置、PA 使能引脚和编解码器地址。
- 排查网络连接失败
如果无法连接网络,检查 Wi-Fi 凭据和网络配置。
- 排查服务器通信失败
如果无法与服务器通信,检查 MQTT 或 WebSocket 配置。
- 记录设备配置
记录固件版本、板卡 ID、Flash/PSRAM、显示屏规格和当前配置状态。
- 区分账户设置与刷写操作
在 Console 账户中保留智能体设置。重新刷写固件与解绑账户是两种不同的操作。
- 识别开发板接口
根据开发板文档识别其原生 USB 和 USB-UART 接口。
- 检查下载接口
确认 USB 连接器连接到芯片的下载接口,而不只是提供电源。
- 检查硬件版本支持情况
部分 Tudouzi (tudouzi)、KevinBox2 和其他硬件版本未引出所需的 USB 引脚。
- 重启并检查启动提示
关闭连接。按下 RESET/EN 或重新给设备上电,然后检查启动提示。
- 验证烧录成功
确认写入和校验均已成功。重启后,检查预期的开发板固件和版本是否运行,并显示预期的画面和播放启动音效。
- 选择动作名称
将必填的 `action` 参数设置为支持的动作列表中的名称。
- 设置动作步数
将 `steps` 设置为 1-100,默认值为 3;数值越大,动作持续时间越长。
- 设置动作速度
将 `speed` 设置为 100-3000,默认值为 700;数值越小越快。大多数动作为 500-1500 毫秒,特殊动作可能不同,例如旋风腿为 100-1000、起飞为 200-600。
- 设置动作方向
将 `direction` 设置为 -1、0 或 1,默认值为 1。walk/turn 中 1 表示前进/左转、-1 表示后退/右转;bend/shake_leg/moonwalk 中 1 表示左、-1 表示右;手部动作中 1 表示左手、-1 表示右手,支持时 0 表示双手。
- 设置动作幅度
将 `amount` 设置为 0-170,默认值为 30;数值越大,动作幅度越大。
- 设置手臂摆动幅度
将 `arm_swing` 设置为 0-170,默认值为 50;仅用于 walk/turn 动作,0 表示不摆动手臂。
- 按顺序逐步启动开发板
先启动显示屏,然后是音频,最后启动完整系统。
- 修复显示异常
检查 SPI 配置、镜像设置和颜色反转设置。
- 修复无音频问题
检查 I2S 接线、PA 使能引脚和编解码器 I2C 地址。
- 修复 WiFi 连接失败
重新检查 WiFi 凭据和配网方式。
- 修复服务器连接失败
检查 WebSocket 或 MQTT 端点配置。
- 检查显示、提示音和连接
确认 OLED 正常显示、启动提示音可听见,并且设备已连接并出现在 Console 中。
- 测试对话控制
按下按钮开始对话,讲话让麦克风听见,并确认无需重启即可播放回复。
- 使用默认 Simplex 配置
本页使用源代码的默认 Simplex 配置。
- 确认固件安全限幅
固件会自动裁剪超出范围的目标角度,并限制 AI 自编程振荡动作的振幅,使 `中心角 +/- 振幅` 不超过安全范围。
- 配置大模型
如果小智 AI 聊天设备已连接到官方服务器,请登录 xiaozhi.me 控制台进行配置。
用起来
- 调用统一动作工具
调用 `self.otto.action`,通过 `action` 参数指定动作名称。
- 使用基础移动动作
`walk` 和 `turn` 需要 steps、speed、direction、arm_swing;`jump` 需要 steps、speed。
- 使用特殊动作
`swing` 需要 steps、speed、amount;`moonwalk` 需要 steps、speed、direction、amount;`bend` 和 `shake_leg` 需要 steps、speed、direction;`updown` 和 `whirlwind_leg` 需要 steps、speed、amount。
- 执行固定动作
无需参数即可调用 `sit`、`showcase` 或 `home`;`showcase` 串联执行多个动作,`home` 将机器人复位到初始位置。
- 使用手部动作
配置手部舵机后,`hands_up` 和 `hands_down` 需要 speed、direction;`hand_wave` 需要 direction;`windmill`、`takeoff`、`fitness` 需要 steps、speed、amount;`greeting` 和 `shy` 需要 direction、steps;`radio_calisthenics` 和 `magic_circle` 无需参数。
- 检查手部舵机支持
带星号的手部动作仅在配置手部舵机后可用。
- 让 Otto 回到初始位置
调用 `self.otto.action` 工具并传入 `{"action": "home"}`,将机器人复位到初始位置。
- 每个动作后自动复位
每个动作执行完成后,机器人会自动回到初始位置(home),以便执行下一个动作。
- 两个动作不自动复位
sit(坐下)和showcase(展示动作)执行后不会自动复位。
- 使用默认动作参数
所有参数都有合理的默认值,可以省略不需要自定义的参数。
- 在后台执行动作
动作在后台任务中执行,不会阻塞主程序。
- 连续执行多个动作
支持动作队列,可以连续执行多个动作。
- 配置手部舵机
手部动作需要配置手部舵机才能使用;如果没有配置手部舵机,相关动作将被跳过。
- 使用默认参数向前走
调用Otto动作工具执行walk动作,并省略可自定义参数。
- 稍快地向前走五步
调用walk动作,设置步数为5、速度为800。
- 左转并大幅摆臂
调用turn动作,设置步数为2、手臂摆动幅度为100。
- 中等幅度摇摆
调用swing动作,设置步数为5、幅度为50。
- 跳跃
调用jump动作,设置步数为1、速度为1000。
- 太空步
调用moonwalk动作,设置步数为3、速度为800、方向为1、幅度为30。
- 挥左手打招呼
调用hand_wave动作,设置方向为1。
- 执行展示动作
调用showcase展示动作,串联多个动作执行。
- 坐下
调用sit坐下动作。
- 大风车动作
调用windmill动作,设置步数为10、速度为500、幅度为80。
- 起飞动作
调用takeoff动作,设置步数为5、速度为300、幅度为40。
- 广播体操
调用radio_calisthenics广播体操动作。
- 复位到初始位置
调用home动作,将机器人复位到初始位置。
- 立即停止所有动作
调用stop工具,立即停止所有动作并复位机器人。
- 获取机器人IP地址
调用get_ip工具,获取机器人的IP地址。
- 挥手
安装手部舵机后,使用挥手动作。
- 立即停止所有动作
调用停止工具,立即停止奥托机器人的所有动作。
- 获取运动状态
获取机器人的运动状态,返回值为“moving”或“idle”。
- 获取 IP 地址
请求设备的 IP 地址。
- 获取电池电量
请求设备的电池电量。
- 获取设备状态
获取音量、网络和电池等设备状态信息。
- 设置扬声器音量
使用 0 至 100 范围内的值,将扬声器音量设置为 70。
- 运行普通舵机序列
运行普通序列,逐步移动各个舵机。
- 双臂摆动
运行振荡器模式,使双臂摆动。
- 创建左右摇摆波浪
运行振荡器模式,创建左右摇摆波浪。
- 体验语音动作指令
可通过语音控制举手、挥手、拍打、放下手臂,以及身体转向、抬头、低头、点头和组合动作。
- 通过 WebSocket 调用工具
连接 WiFi 后,在同一局域网访问 `ws://<设备IP>:8080/ws`;可发送 MCP 格式消息或直接的 JSON-RPC `tools/call` 消息。
常见问题
物料
- 主控:ESP32、ESP32‑C3/C5/C6/S3 或 P4(README)
- 麦克风与扬声器(具备 AEC 的硬件可全双工)
- 可选:OLED/LCD 屏、摄像头、ML307/EC801E/NT26 Cat.1 4G 模组
- 机器人躯体可选 StackChan、Otto、ElectronBot 等已适配板型
工具
- 电脑与可传数据的 USB 线
- DIY:面包板与杜邦线
技能
- 新手可用免环境固件直接烧录
- 自定义板卡:ESP‑IDF v6.0.1 及以上与 C++
- MCP 工具与角色提示词配置
软件
- xiaozhi-esp32 固件
- xiaozhi.me 控制台(模型、音色、角色)
- 第三方自建服务器,如 xinnan-tech/xiaozhi-esp32-server(Python)