first commit

9.14 Open Duck Mini技术文档.md

@@ -0,0 +1,91 @@
+# 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
+