Xiaozhi Arduino Library

小智 AI 语音助手 Arduino 库 — 从 xiaozhi-esp32 ESP-IDF 项目移植而来。

简介

Xiaozhi 是一个功能完整的 AI 语音助手框架，支持 100+ 种 ESP32 开发板。主要特性：

• 🎙️ 语音交互 — 唤醒词检测、语音识别、TTS 播放
• 📡 双协议 — WebSocket 和 MQTT+UDP 通信
• 🖥️ 显示支持 — LVGL LCD、OLED、表情包动画
• 💡 LED 状态 — 单色/RGB/灯环状态指示
• 🔄 OTA 升级 — 空中固件升级
• 🤖 MCP 协议 — 支持 AI 工具调用控制硬件
• 🌍 20+ 语言 — 国际化支持

系统要求

• Arduino-ESP32 Core 3.x+ (基于 ESP-IDF 5.5.2+)
• ESP32-S3 (推荐) / ESP32 / ESP32-C3 / ESP32-P4
• PSRAM (大部分板型需要)
• PlatformIO 或 Arduino IDE 2.x

快速开始

PlatformIO

1. 创建新项目，选择 ESP32-S3 开发板
2. 将此库复制到 lib/ 目录下
3. 在项目根目录创建 xiaozhi_user_config.h，配置你的板型
4. 编写 sketch：

#include <Xiaozhi.h>

void setup() {
    Serial.begin(115200);
    Xiaozhi.begin();
}

void loop() {
    Xiaozhi.loop();
}

Arduino IDE

1. 将此库文件夹复制到 Arduino 库目录 (Documents/Arduino/libraries/)
2. 在 File > Examples > Xiaozhi 中打开示例
3. 配置板型并上传

配置

板型选择

在你的项目中创建 xiaozhi_user_config.h：

#include "boards/board_ids.h"

// 取消注释你使用的开发板
#define XIAOZHI_BOARD_ID BOARD_ID_ESP_BOX_3
// #define XIAOZHI_BOARD_ID BOARD_ID_BREAD_COMPACT_WIFI
// #define XIAOZHI_BOARD_ID BOARD_ID_ATOMS3_ECHO_BASE

// 板型名称字符串 (用于运行时上报)
#define XIAOZHI_BOARD_TYPE "esp-box-3"

或在 PlatformIO build_flags 中设置：

build_flags = -DXIAOZHI_BOARD_ID=BOARD_ID_ESP_BOX_3 -DXIAOZHI_BOARD_TYPE=\"esp-box-3\"

完整的板型 ID 列表见 src/boards/board_ids.h。

支持的板型列表见 src/boards/ 目录，包括：

板型	Board Type
ESP-BOX-3	esp-box-3
ESP-BOX	esp-box
M5Stack AtomS3 + Echo Base	atoms3-echo-base
Bread Compact WiFi	bread-compact-wifi
DFRobot K10	df-k10
LilyGO T-Circle-S3	lilygo-t-circle-s3
Waveshare ESP32-S3	waveshare-*
...	100+ 更多

语言配置

#define XIAOZHI_LANGUAGE "zh-CN"  // 默认中文简体

如需切换语言，运行脚本重新生成语言资源：

python scripts/generate_lang_config.py --language en-US --output src/assets/lang_config.h
python scripts/generate_sound_data.py --language en-US --output src/assets/sound_data.h

API 参考

XiaozhiClass

// 全局实例
extern XiaozhiClass Xiaozhi;

// 基本操作
Xiaozhi.begin();              // 初始化 (在 setup() 中调用)
Xiaozhi.loop();               // 循环处理 (在 loop() 中调用)

// 交互控制
Xiaozhi.toggleChat();         // 切换对话状态
Xiaozhi.startListening();     // 开始监听
Xiaozhi.stopListening();      // 停止监听

// 状态查询
Xiaozhi.getState();           // 获取设备状态枚举
Xiaozhi.getStateName();       // 获取状态名称字符串
Xiaozhi.isVoiceDetected();    // 是否检测到语音

// 音量控制
Xiaozhi.setVolume(70);        // 设置音量 (0-100)
Xiaozhi.getVolume();          // 获取当前音量

// 高级访问
Xiaozhi.getApplication();     // 获取 Application 实例
Xiaozhi.getBoard();           // 获取 Board 实例
Xiaozhi.getMcpServer();       // 获取 MCP 服务器实例

DeviceState (设备状态)

kDeviceStateUnknown           // 未知
kDeviceStateStarting          // 启动中
kDeviceStateWifiConfiguring   // WiFi 配网
kDeviceStateIdle              // 待命
kDeviceStateConnecting        // 连接中
kDeviceStateListening         // 聆听中
kDeviceStateSpeaking          // 说话中
kDeviceStateUpgrading         // 升级中
kDeviceStateActivating        // 激活中
kDeviceStateAudioTesting      // 音频测试
kDeviceStateFatalError        // 致命错误

MCP 工具注册

auto& mcp = Xiaozhi.getMcpServer();

PropertyList props;
props.AddProperty(Property("name", kPropertyTypeString));
props.AddProperty(Property("value", kPropertyTypeInteger, 0, 0, 100));

mcp.AddTool("my_tool", "工具描述", props,
    [](const PropertyList& p) -> ReturnValue {
        return std::string("执行结果");
    });

架构说明

与 ESP-IDF 版本的差异

组件	ESP-IDF 版本	Arduino 版本
入口点	app_main()	setup() + loop()
配置系统	Kconfig	xiaozhi_config.h
构建系统	CMake	Arduino/PlatformIO
音频嵌入	EMBED_FILES	PROGMEM C 数组
事件循环	主任务阻塞	独立 FreeRTOS 任务
NVS	ESP-IDF NVS API	同上 (Arduino-ESP32 兼容)

模块架构

XiaozhiClass (Arduino 包装)
    └── Application (核心应用)
        ├── DeviceStateMachine (状态机)
        ├── AudioService (音频服务)
        │   ├── AudioCodec (音频编解码)
        │   ├── AudioProcessor (VAD/AEC/NS)
        │   └── WakeWord (唤醒词检测)
        ├── Protocol (通信协议)
        │   ├── WebsocketProtocol
        │   └── MqttProtocol
        ├── Display (显示)
        │   ├── LcdDisplay (LVGL)
        │   ├── OledDisplay
        │   └── EmoteDisplay
        ├── Led (LED 指示)
        ├── McpServer (工具调用)
        ├── Ota (固件升级)
        ├── Settings (持久化配置)
        └── Board (硬件抽象层)

自定义开发板

参考 src/boards/ 目录中的现有实现，创建自己的板级定义：

// my_board.h
#include "boards/common/wifi_board.h"

class MyBoard : public WifiBoard {
public:
    AudioCodec* GetAudioCodec() override { ... }
    Display* GetDisplay() override { ... }
};

// my_board.cc
#include "xiaozhi_config.h"
#include "boards/board_ids.h"

// 使用自定义 ID (可在 board_ids.h 末尾添加)
#if XIAOZHI_BOARD_ID == BOARD_ID_MY_BOARD

#include "my_board.h"
// ... 实现代码 ...
DECLARE_BOARD(MyBoard)

#endif

DECLARE_BOARD(MyBoard)

详细说明请参考原始项目的 [自定义板型文档](https://github.com/78/xiaozhi-esp32/blob/main/docs/custom-board.md)。

## 脚本工具

| 脚本 | 用途 |
|------|------|
| `scripts/generate_lang_config.py` | 生成语言配置头文件 |
| `scripts/generate_sound_data.py` | 将 OGG 音频转换为 PROGMEM 数组 |
| `scripts/fix_includes.py` | 修复跨目录 include 路径 |
| `scripts/generate_board_guards.py` | 生成板型条件编译守卫 |

## 许可证

本项目基于 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 致谢

本 Arduino 库移植自 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 项目。