robot_arm/使用说明书.md

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

一、系统简介

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

---

二、快速开始

2.1 启动程序

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

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 产生的"向右向右向右"等重复幻觉。
• 谐音纠错：支持将"电头"自动纠正为"点头"，"离米"纠正为"厘米"等。
• 安全边界：内置软件限位保护，防止机械臂撞击底座或过度伸展。