99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 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`开启摄像头权限 |
|
||
| 找不到libcamera | https://blog.csdn.net/2301_78638152/article/details/145655038 |
|
||
| 其他问题 | 先把官方github仓库连接提交至豆包,作为参考进而排查问题 |
|
||
|
||
## 五、存在问题:
|
||
|
||
- 鸭子在启动后会乱动,关节会发生偏移,导致在执行前进后退时无法走直线
|
||
- 解决方案:在每次执行运动指令前重新初始化标准站立位姿
|
||
|
||
## 六、//TODO
|
||
|
||
- **接入ai小智(mcp)**:https://www.ncnynl.com/archives/202509/6827.html
|
||
|