# Open Duck Mini技术文档 

## 一、项目概述

### 1.1 项目简介

本项目是一款基于树莓派的智能机器人控制系统，支持**语音唤醒、语音指令识别、运动控制、图像识别、实时语音反馈**等核心功能。系统采用模块化设计，便于维护与扩展。

### 1.2 核心功能

| 功能模块 | 具体能力                                                     |
| -------- | ------------------------------------------------------------ |
| 语音唤醒 | 通过 “小黄鸭” 唤醒词激活机器人，进入指令接收状态             |
| 语音识别 | 识别中文指令（如 “前进 3 秒”,“这是什么”,“增大音量”）         |
| 运动控制 | 控制机器人前进、后退、左转、右转（基于 ONNX 运动模型）       |
| 图像识别 | 拍摄图像并通过火山方舟 API 识别物体，实时语音播报结果        |
| 语音反馈 | 通过百度 TTS 实现中文语音反馈，支持 “边生成文字边播报” 的实时交互体验 |
| 音量控制 | 调节系统音量（增大、减小、最大、最小）                       |

## 二、环境准备

### 2.1 硬件要求

| 硬件设备 | 规格要求                              |
| -------- | ------------------------------------- |
| 主控板   | 树莓派 4B/5（建议 4GB 以上内存）      |
| 摄像头   | 树莓派官方摄像头（或兼容 USB 摄像头） |
| 麦克风   | USB 麦克风（支持 16kHz 采样率）       |
| 扬声器   | 树莓派兼容扬声器（GPIO或 USB）        |
| 电源     | 5V/3A 直流电源（确保运动时供电稳定）  |

### 2.2 软件依赖

#### 2.2.1 系统环境:

- 操作系统：Raspberry Pi OS (Bookworm，64 位)
- Python 版本：3.10~3.11

#### 2.2.2 必装依赖库:

通过以下命令安装所有依赖(在虚拟环境中安装)：

```bash
# 基础依赖
sudo apt-get update && sudo apt-get install -y ffmpeg portaudio19-dev libportaudio2

# Python库
pip install sounddevice pvporcupine websocket-client openai picamera2 pillow pyaudio pydub requests
```

#### 2.2.3 特殊依赖:

1. **火山方舟 API**：需注册火山引擎账号，创建 API 密钥（`ARK_API_KEY`）和模型 ID（`ARK_MODEL_ID`），参考main_scheduler.py。
2. **百度 TTS API**：需注册百度智能云账号，创建应用获取`BAIDU_TTS_API_KEY`和`BAIDU_TTS_SECRET_KEY`。
3. **讯飞语音识别 API**：需注册讯飞开放平台账号，创建应用获取`APPID`、`ACCESS_KEY_ID`、`ACCESS_KEY_SECRET`。
4. **PicoVoice 唤醒词**：需注册 PicoVoice 账号，获取`ACCESS_KEY`，并下载 “小黄鸭” 中文唤醒词文件（`.ppn`格式）以及porcupine_params_zh.pv文件。

## 三、部署流程:

- **创建虚拟环境时注意 **: python3 -m venv ~/duck --system-site-packages(否则无法找到libcamera)
- **启动虚拟环境**:source ~/duck/bin/activate
- **项目路径：**cd open_duck_mini_ws/OPEN_DUCK_MINI/Open_Duck_Mini_Runtime-2/scripts/

- 运行main_scheduler.py观察终端输出，确认模块初始化成功：

  ```plaintext
  ✅ 成功获取百度API访问令牌
  🔊 音量控制初始化成功（当前音量：40%）
  🤖 运动控制模块初始化成功
  📷 摄像头模块初始化成功
  ✅ API模块：初始化成功
  ✅ 语音识别模块：初始化成功
  🔍 正在测试语音输出...
  ✅ 语音播放完成: 系统初始化完成,等待语音唤醒...
  🎯 语音识别模块：唤醒词引擎就绪（采样率：16000）
  📢 语音识别模块：等待唤醒词「小黄鸭」
  ```

## 四、常见问题:

| 报错信息                                 | 排查方向                                                     |
| ---------------------------------------- | ------------------------------------------------------------ |
| `TTS初始化失败：无法获取百度API访问令牌` | 1. 检查百度 TTS 的`API_KEY`和`SECRET_KEY`是否正确；2. 树莓派是否能联网 |
| `运动控制失败：找不到v2_rl_walk_mujoco`  | 1. 检查`PROJECT_ROOT`路径是否正确；2. 确认`v2_rl_walk_mujoco.py`已存在 |
| `摄像头失败：无法初始化Picamera2`        | 1. 检查摄像头是否正确连接；2. 执行`sudo raspi-config`开启摄像头权限 |
| 其他问题                                 | 先把官方github仓库连接提交至豆包,作为参考进而排查问题        |

## 五、//TODO

- **接入ai小智(mcp)**:https://www.ncnynl.com/archives/202509/6827.html