# xiaozhi_linux-fusion

**Repository Path**: genvex/xiaozhi_linux-fusion

## Basic Information

- **Project Name**: xiaozhi_linux-fusion
- **Description**: https://github.com/100askTeam/xiaozhi-linux
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小智 Linux 融合版 (xiaozhi-linux-fusion)

基于 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 协议的 Linux 原生实现，专为 RK3588/Rock 5T 等 ARM 开发板设计。

## ✨ 特性

- 🎯 **完整协议实现**：OTA 激活、WebSocket 通信、Opus 音频编解码
- 🔄 **自动对话循环**：`--auto-loop` 参数实现无人值守连续对话
- 🎵 **真实音频链路**：ALSA 录音/播放，支持 USB 声卡
- 🖥️ **LVGL 9.5 UI**：320x175 分辨率，21 种表情动画
- 🧠 **MCP 工具支持**：可扩展的工具调用接口
- 📦 **双模式运行**：STUB（本地模拟）和 FULL（真实服务器）

## 🚀 快速开始

### 1. 环境准备

**硬件要求**：
- Rock 5T / RK3588 开发板（8GB RAM 推荐）
- USB 麦克风（16kHz 采样率）
- USB 喇叭或 HDMI 音频输出
- HDMI 显示器（1280x400 或类似分辨率）

**软件依赖**：

```bash
# 基础编译工具
sudo apt update
sudo apt install -y build-essential cmake git

# 音频和编解码库
sudo apt install -y libasound2-dev libopus-dev libspeexdsp-dev

# 网络和加密库
sudo apt install -y libcurl4-openssl-dev libssl-dev libwebsockets-dev

# LVGL UI 依赖（可选，仅 USE_LVGL=1 时需要）
sudo apt install -y libsdl2-dev libpng-dev libfreetype6-dev
```

### 2. 克隆并编译

```bash
# 克隆项目
git clone https://github.com/genvex/xiaozhi-linux-fusion.git
cd xiaozhi-linux-fusion

# 初始化 LVGL 子模块（如果需要 UI）
git submodule update --init --recursive

# 编译 LVGL 库（如果需要 UI）
make lvgl

# 编译主程序（带 LVGL UI）
make USE_LVGL=1

# 或编译无 UI 版本
make FULL=1
```

**编译模式说明**：
- `make` → STUB 模式（本地模拟，用于开发调试）
- `make FULL=1` → 完整模式（真实服务器，无 UI）
- `make USE_LVGL=1` → LVGL UI 模式（推荐）
- `make USE_LVGL=1 FULL=1` → LVGL UI + 完整功能

### 3. 配置音频设备

**检查 USB 声卡**：

```bash
# 查看声卡列表
arecord -l
aplay -l

# 假设 USB 麦克风/喇叭是 Card 5（MV-SILICON Y11）
# 录音测试
arecord -D plughw:5,0 -f S16_LE -r 16000 -c 1 -d 3 /tmp/test.wav

# 播放测试
amixer -c 5 sset PCM 10%  # 办公室音量 10%
aplay -D plughw:5,0 /tmp/test.wav
```

**解决 PipeWire 冲突**（如果遇到 `Device or resource busy`）：

```bash
systemctl --user disable --now pipewire pipewire-pulse
```

### 4. 配置显示设备

项目默认使用 `DISPLAY=:1`（第二块屏幕，如 HDMI-1）。

**检查显示器**：

```bash
export DISPLAY=:1
xdpyinfo | grep dimensions
# 应该显示 1280x400 或类似分辨率
```

### 5. 运行程序

```bash
# 设置显示环境
export DISPLAY=:1

# 启动程序（自动循环对话模式）
./build/xiaozhi-card --auto-loop

# 或手动触发对话（按回车键）
./build/xiaozhi-card
```

**首次运行**：
1. 程序会生成设备身份文件 `board_identity.json`
2. 控制台输出激活验证码（如 `460003`）
3. 访问 https://xiaozhi.me 输入验证码完成设备绑定
4. 绑定成功后自动连接 WebSocket 服务器

### 6. 配置文件

程序自动创建 `board_identity.json`：

```json
{
  "mac_address": "98:88:e0:0f:18:6c",
  "uuid": "9edbbc88-a058-4484-9771-0459cbe30635"
}
```

**注意**：`uuid` 是设备唯一标识，删除此文件会导致设备需要重新激活。

## 📖 使用说明

### 对话模式

- **自动模式**：`./build/xiaozhi-card --auto-loop`
  - 程序自动检测语音活动，触发对话
  - 适合长时间无人值守场景

- **手动模式**：`./build/xiaozhi-card`
  - 按回车键触发一次对话
  - 适合测试和调试

### 查看日志

```bash
# 实时查看程序输出
./build/xiaozhi-card --auto-loop 2>&1 | tee /tmp/fusion.log

# 或后台运行
nohup ./build/xiaozhi-card --auto-loop > /tmp/fusion.log 2>&1 &
tail -f /tmp/fusion.log
```

### 常见问题

**Q: WebSocket 连接后立即断开？**  
A: 可能是设备未激活。检查控制台输出的激活码，访问 xiaozhi.me 完成绑定。

**Q: ALSA 报 `Device or resource busy`？**  
A: PipeWire 占用了声卡。运行 `systemctl --user disable --now pipewire pipewire-pulse`。

**Q: UI 显示异常或黑屏？**  
A: 检查 `DISPLAY` 环境变量是否正确（通常是 `:1`），确认 Xorg 服务器正在运行。

## 🏗️ 项目架构

```
xiaozhi-linux-fusion/
├── src/                    # 源代码
│   ├── main.cpp           # 主程序入口
│   ├── application.*      # 应用层核心（状态机、调度器）
│   ├── audio/             # 音频子系统
│   │   ├── audio_engine.*    # ALSA 录音引擎
│   │   ├── audio_player.*    # ALSA 播放器
│   │   ├── audio_simulator.* # 音频模拟器（STUB 模式）
│   │   └── voice_detector.*  # 语音活动检测（VAD）
│   ├── protocol/          # 协议层
│   │   └── websocket_protocol.*  # libwebsockets 实现
│   ├── opus/              # Opus 编解码
│   │   └── opus_codec.*
│   ├── ota/               # OTA 激活
│   │   └── ota_activator.*
│   ├── mcp/               # MCP 工具服务器
│   │   └── mcp_server.*
│   ├── display/           # 显示模块
│   │   ├── display.h         # 显示接口
│   │   ├── display_stub.cpp  # STUB 模式（终端输出）
│   │   └── display_lvgl.cpp  # LVGL 9.5 实现
│   └── common/            # 公共组件
│       ├── scheduler.h       # 任务调度器
│       ├── state_machine.h   # 状态机框架
│       ├── ring_buffer.h     # 环形缓冲区
│       ├── event_group.h     # 事件组
│       └── async_queue.h     # 异步队列
├── libs/                   # 第三方库
│   ├── lvgl/              # LVGL 9.5（子模块）
│   ├── lv_conf.h          # LVGL 配置
│   └── CMakeLists.txt     # LVGL 编译配置
├── assets/                 # UI 资源
│   ├── emoji/             # 21 种表情 PNG
│   └── NotoSansSC.ttf     # 中文字体
├── scripts/                # 辅助脚本
│   └── generate_test_audio.py
├── docs/                   # 文档
│   └── OTA-WEBSOCKET-DEBUG.md  # 联网调试记录
├── Makefile               # 构建脚本
└── README.md              # 本文件
```

## 🔧 开发指南

### 添加新的 MCP 工具

编辑 `src/mcp/mcp_server.cpp`，在 `RegisterTools()` 函数中注册：

```cpp
void McpServer::RegisterTools() {
    tools_["get_weather"] = [](const json& params) {
        // 工具实现
        return json{{"result", "晴天"}};
    };
}
```

### 自定义 UI

LVGL UI 实现在 `src/display/display_lvgl.cpp`：

- `CreateUI()` → 初始化界面
- `UpdateEmotion()` → 更新表情
- `ShowText()` → 显示状态文本

### 修改音频参数

编辑 `src/application.h` 中的 `AppConfig` 结构体：

```cpp
struct AppConfig {
    int record_sample_rate = 16000;  // 录音采样率
    int play_sample_rate = 24000;    // 播放采样率
    int channels = 1;                // 声道数
    // ...
};
```

## 📊 性能指标

| 指标 | 数值 |
|------|------|
| 音频延迟 | < 100ms |
| Opus 编码 | 16kHz, 20ms 帧 |
| Opus 解码 | 24kHz, 20ms 帧 |
| WebSocket 连接 | < 500ms |
| 内存占用 | ~20MB |
| CPU 占用 | ~5% (单核) |

## 🐛 已知问题

### ES8316 半双工限制

Rock 5T 板载 ES8316 声卡不支持同时录音和播放。

**解决方案**：使用 USB 声卡替代，或启用半双工模式：

```cpp
// src/application.h
bool g_half_duplex_mode = true;
bool g_mic_enabled = false;  // 播放时禁用麦克风
```

### 网卡名称非标准

Rock 5T 的网卡名称不是标准的 `wlan0`/`eth0`：

| 接口 | 实际名称 |
|------|---------|
| WiFi | wlP2p33s0 |
| ETH1 | enP4p65s0 |
| ETH0 | enP3p49s0 |

程序会自动尝试多个接口名获取 MAC 地址。

## 📄 许可证

MIT License

## 🙏 致谢

- [小智 AI (xiaozhi-esp32)](https://github.com/78/xiaozhi-esp32) - ESP32 版本参考
- [LVGL](https://lvgl.io/) - 图形库
- [libwebsockets](https://libwebsockets.org/) - WebSocket 库
- [Opus](https://opus-codec.org/) - 音频编解码
- [SpeexDSP](https://www.speex.org/) - 音频处理

## 📝 版本历史

### v2.1.0 (2026-07-21)

- ✅ 完整 OTA 两步激活流程
- ✅ WebSocket 协议实现（对齐 ESP32 原版）
- ✅ LVGL 9.5 UI（21 种表情动画）
- ✅ 真实音频录音/播放（ALSA）
- ✅ Opus 编解码器集成
- ✅ 自动对话循环功能
- ✅ MCP 工具支持

### v2.0.0

- 基础架构搭建
- STUB 模式完整实现
- 状态机和调度器

### v1.0.0

- 项目初始化
- ESP32 协议逆向分析

---

**开发环境**：Ubuntu 22.04 on Rock 5T (RK3588)  
**编译工具链**：GCC 11.4.0  
**最后更新**：2026-07-21