# 机械臂语音控制系统使用指南 v1.0

## 一、系统简介
本系统是一套基于多模态大模型的具身智能控制方案，能够让用户通过**自然语言**直接指挥机械臂完成抓取、搬运、运动控制等任务。系统集成了 Whisper 语音识别、DeepSeek 语义理解、YOLOv8 视觉定位以及自动化运动控制算法。

---

## 二、快速开始

### 2.1 启动程序
1. **硬件准备**：插入 USB 摄像头，连接 ESP32 控制板（请确保已烧录 `main.ino` 固件，其串口默认为 COM3）。
2. **运行命令**：在终端输入：

```powershell
python voice_main.py
```

程序启动流程：
1. **连接机械臂**：尝试通过 COM3 连接 ESP32，如失败将进入仿真模式。
2. **加载模型**：依次加载 YOLOv8s（视觉）、Faster-Whisper（语音）和 DeepSeek（语义解析）。
3. **打开界面**：弹出摄像头实时画面窗口 `Voice Robot Control`。

### 2.2 界面交互与快捷键

| 按键 | 功能描述 |
|:---|:---|
| **SPACE (空格)** | **主要的交互键**。按住开始录音说话，松开即结束录音并开始识别指令。 |
| **C 键** | **进入/退出标定模式**。用于重新校准摄像头坐标与机械臂坐标的映射关系。 |
| **R 键** | **手动复位**。强制让机械臂回到初始等待位置 (120, 0, 60)。 |
| **O 键** | **手动松开**。强制张开夹爪 (Open)。 |
| **Q 键** | **退出程序**。安全关闭摄像头、释放显存并断开串口连接。 |

---

## 三、语音指令说明

您可以用自然的中文直接说话，系统支持多种指令类型。

### 3.1 物品抓取与搬运 (视觉定位)
系统会自动在画面中寻找物体（如削笔刀、盒子等），并根据您的指令操作。

- **抓取指令**：
  - "把削笔刀抓起来"
  - "抓住那个盒子"
- **抬起指令**（支持指定高度）：
  - "把削笔刀抬起5厘米"
  - "将零件举高10公分"
  - *注意：系统会自动将“公分”换算为厘米，“两”换算为2。*

### 3.2 空间运动控制 (无目标)
您可以像驾驶员一样指挥机械臂上下左右移动，**支持中文数字**。

- **精确移动**：
  - "向上三厘米"
  - "向左移动四米米" (兼容“米米”等语音误识别)
  - "往前伸10厘米"
- **模糊移动** (不指定数值)：
  - 假如您只说 "向左"、"抬起"、"往下"，系统将**默认移动 5厘米**。

### 3.3 动作交互
- **点头**："点头" —— 机械臂会在当前位置上下以 3cm 幅度快速往复运动三次。
- **摇头**："摇头" —— 机械臂会在当前位置左右以 3cm 幅度快速往复运动三次。

### 3.4 放置与复位
- **放下**：
  - 说 "放下" 或 "放到桌面上"。
  - **智能特性**：无论当前机械臂在多高，它会自动计算距离桌面的高度，精准降落到桌面 (Z=-15mm) 并松开夹爪。
- **复位**：
  - 说 "复位"、"回到原点" 或 "归位"，机械臂将回到初始安全姿态。

---

## 四、标定教程 (C键)
如果发现机械臂抓不准物体，说明摄像头位置变动了，需要重新标定。

1. **按 `C` 键**：进入标定模式，屏幕左上角显示 `CALIBRATION MODE`。
2. **依次点击4个点**：请在画面中依次点击以下四个位置（假设机械臂原点在正下方）：
   - **P1**: 左上方 (对应现实坐标 x=90, y=90)
   - **P2**: 右上方 (对应现实坐标 x=200, y=90)
   - **P3**: 右下方 (对应现实坐标 x=200, y=-90)
   - **P4**: 左下方 (对应现实坐标 x=90, y=-90)
3. **完成**：点完第4个点后，系统会自动计算映射矩阵并立即生效，无需重启。

---

## 五、故障排除

| 问题现象 | 可能原因 | 解决方法 |
|:---|:---|:---|
| **按空格没反应** | 程序焦点不在画面窗口上 | 请点击一下摄像头的画面窗口，确保它被激活。 |
| **语音识别乱码** | 麦克风噪音过大或语速过快 | 请在安静环境下，语速适中，按住空格等0.5秒再说话。 |
| **"未找到目标"** | YOLO没检测到物体 | 调整物体角度，确保护光照充足；或者物体不在训练类别中。 |
| **抓取位置偏离** | 摄像头被移动过 | 请按 `C` 键重新进行四点标定。 |
| **无法连接串口** | ESP32未插入或端口占线 |检查 USB 线，确认设备管理器中端口号是否为 COM3。 |

---

## 六、高级特性
- **防幻觉机制**：系统会自动过滤 Whisper 产生的"向右向右向右"等重复幻觉。
- **谐音纠错**：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。
- **安全边界**：内置软件限位保护，防止机械臂撞击底座或过度伸展。