unity2moveit2/UR5_QUICK_START.md

UR5 快速开始指南 ⚡

一站式 UR5 机器人 Unity-MoveIt2 集成指南

---

📋 准备工作检查清单

在开始之前，确认以下项目已完成：

• ✅ Docker 容器运行中

  cd docker
  docker-compose ps  # 确认 unity-ros2-system 状态为 Up
  

• ✅ 配置文件已创建 (已自动生成)

  • configs/robots/ur5.yaml
  • UR5/urdf/ur5.urdf (含 tool0)
  • UR5/urdf/ur5.srdf
  • ros2-workspace/.../ur5_robot_config.yaml

• ✅ 集成测试通过

  python test_ur5_integration.py
  # 应显示：所有 5 项测试通过 (100%)
  

---

🚀 Unity 导入步骤 (3 分钟)

方式 1: 使用导入辅助脚本 (推荐)

步骤 1: 打开 Unity 项目

# 使用 Unity Hub 打开
# 路径: unity-project/
# 版本: Unity 2022.3.57f1c2 LTS

步骤 2: 创建导入器对象

1. 在 Hierarchy 窗口中：

   • 右键 → Create Empty
   • 命名为 UR5_Importer

2. 在 Project 窗口中：

   • 导航到 Assets/Scripts/Core/
   • 找到 UrdfRobotImporter.cs
   • 拖拽到 UR5_Importer 对象上

步骤 3: 配置导入参数

在 Inspector 窗口中确认以下设置：

参数	值
Urdf Asset Path	URDF/UR5/urdf/ur5.urdf
Axis Type	Z Axis
Convex Method	Unity
Position At Origin	✅
Auto Add Adapter	✅
DOF	6
Config Path	configs/robots/ur5.yaml

步骤 4: 执行导入

1. 在 Inspector 中，右键点击 UrdfRobotImporter 组件
2. 选择 "导入 URDF / Import URDF"
3. 等待导入完成（查看 Console 输出）

步骤 5: 验证导入

1. 在 Inspector 中，右键点击 UrdfRobotImporter 组件
2. 选择 "验证导入 / Validate Import"
3. 检查 Console，应显示：

   ✓ 找到 base_link
   ✓ 找到 tool0 末端执行器
   ✓ 找到 X 个 Mesh Renderer
   ✓ 找到 X 个 Collider
   ✓ 找到 X 个 Articulation Body
   ========== ✓ 导入验证通过 ==========
   

---

方式 2: 使用 URDF Importer 菜单

如果您能在 Unity 中找到 URDF 导入菜单，请参考： 👉 UR5_UNITY_IMPORT_GUIDE.md - 详细导入指南

---

⚙️ 配置机器人控制器

步骤 1: 设置机器人适配器

导入后，UR5 对象已自动添加 UniversalRobotAdapter 组件，但需要手动设置引用：

1. 在 Hierarchy 中选中 ur5 根对象
2. 在 Inspector 中找到 Universal Robot Adapter 组件
3. 配置以下字段：

   字段	操作
   DOF	保持 6
   Base Link	从 Hierarchy 拖拽 base_link 对象
   End Effector	从 Hierarchy 拖拽 tool0 对象
   Robot Config Path	输入 configs/robots/ur5.yaml

步骤 2: 配置 ROS 连接

如果场景中没有 ROS 连接器：

1. 创建 ROS 连接对象

   • Hierarchy 右键 → Create Empty
   • 命名为 ROSConnection

2. 添加 ROSTCPBridge 组件

   • Project 窗口：Assets/Scripts/Communication/
   • 拖拽 ROSTCPBridge.cs 到 ROSConnection 对象

3. 配置连接参数

   IP Address: 127.0.0.1
   Port: 10000
   Timeout: 30
   Reconnect Attempts: 5
   

步骤 3: 保存场景

1. File → Save As
2. 命名为 UR5_Scene.unity
3. 保存路径：Assets/Scenes/

---

🧪 测试机器人

测试 1: 可视化检查

1. 点击 Unity 的 Play 按钮
2. 在 Scene 窗口中：
   • 应能看到蓝灰色的 UR5 机器人模型
   • 使用鼠标旋转、缩放视图
   • 确认模型完整（7 个连杆 + 1 个末端）

测试 2: ROS2 连接测试

1. 确认 Docker 运行

   docker exec unity-ros2-system bash -c "source /opt/ros/jazzy/setup.bash && ros2 node list"
   # 应显示: /UnityEndpoint
   

2. 启动 Unity Play 模式

   • 点击 Play 按钮
   • 检查 Console 输出

3. 验证连接

   • 应看到：[ROSTCPBridge] Connected to ROS2 at 127.0.0.1:10000
   • 如果失败，检查 Docker 端口映射和防火墙

测试 3: 关节运动测试

方法 A: 手动测试

1. 选中关节

   • Hierarchy: ur5 → shoulder_link
   • Inspector: 找到 Articulation Body 组件

2. 调整关节位置

   • 在 Play 模式下
   • 修改 X Drive → Target 值（例如：0 → 0.5）
   • 观察机器人肩关节旋转

方法 B: 使用测试脚本

// 在 Unity Console 中执行
GameObject.Find("ur5").GetComponent<UniversalRobotAdapter>().MoveToJointPosition(
    new float[] { 0.5f, -0.5f, 0.5f, 0f, 0f, 0f }
);

测试 4: IK/FK 服务测试

1. 检查 ROS2 服务

   docker exec unity-ros2-system bash -c "source /opt/ros/jazzy/setup.bash && ros2 service list | grep -E 'ik|fk'"
   

2. 在 Unity 中调用 IK

   • 使用 InteractiveEndEffectorController 组件
   • 在 Scene 视图中拖拽末端执行器
   • 观察 IK 求解结果

---

📊 验证清单

导入和配置完成后，确认以下各项：

✅ 结构完整性

• Hierarchy 中包含 ur5 根对象
• 包含 8 个连杆：base_link, shoulder_link, upper_arm_link, forearm_link, wrist_1_link, wrist_2_link, wrist_3_link, tool0
• 每个连杆包含 Mesh Renderer 和 Collider
• 包含 7 个 Articulation Body 组件（6 个运动关节 + 1 个 base）

✅ 组件配置

• ur5 对象包含 UniversalRobotAdapter 组件
• UniversalRobotAdapter 的 Base Link 和 End Effector 已设置
• 场景中包含 ROSConnection 对象
• ROSTCPBridge IP 和端口配置正确

✅ 功能测试

• Unity Play 模式下机器人可见
• ROS2 连接成功（Console 无错误）
• 关节可以手动调整并运动
• IK/FK 服务响应正常

---

❌ 常见问题快速解决

问题 1: 导入后机器人不可见

检查项：

1. Scene 窗口中调整相机位置（双击 ur5 对象自动聚焦）
2. 确认 Mesh Renderer 已启用（Inspector 中勾选）
3. 检查材质是否丢失（Mesh Renderer → Materials）

问题 2: 找不到 URDF Importer 菜单

解决方案：

# 方法 1: 使用导入辅助脚本（推荐）
# 见上方 "方式 1: 使用导入辅助脚本"

# 方法 2: 重新安装 URDF Importer 包
# 在 Unity 中:
# Window → Package Manager → URDF Importer → Remove → Reinstall

问题 3: ROS2 连接失败

检查步骤：

# 1. 确认 Docker 运行
docker ps | grep unity-ros2-system

# 2. 检查端口映射
docker port unity-ros2-system

# 3. 测试端口连通性（PowerShell）
Test-NetConnection -ComputerName 127.0.0.1 -Port 10000

# 4. 查看 Docker 日志
docker logs unity-ros2-system --tail 50

问题 4: 关节不动

检查项：

1. 确认 Articulation Body 的 Drive 已配置：
   - Drive Type: Position 或 Velocity
   - Stiffness: > 0 (如使用 Position 模式)
   - Force Limit: > 0

2. 检查关节限位：
   - Lower Limit 和 Upper Limit 是否合理
   - 是否启用了 Limit

3. 验证物理设置：
   - Edit → Project Settings → Physics
   - Solver Iterations 建议设置 ≥ 12

---

📁 项目文件总览

UR5 集成涉及的关键文件：

Unity 端

unity-project/
├── Assets/
│   ├── URDF/UR5/              # URDF 模型文件
│   ├── Scripts/
│   │   ├── Core/
│   │   │   ├── UrdfRobotImporter.cs     # 导入辅助脚本
│   │   │   └── UniversalRobotAdapter.cs # 机器人适配器
│   │   └── Communication/
│   │       └── ROSTCPBridge.cs          # ROS 通信桥
│   └── Scenes/
│       └── UR5_Scene.unity              # UR5 测试场景

配置文件

configs/robots/ur5.yaml                   # Unity 配置
UR5/urdf/ur5.urdf                         # URDF 模型
UR5/urdf/ur5.srdf                         # MoveIt 语义
ros2-workspace/.../ur5_robot_config.yaml  # ROS2 配置

测试和文档

test_ur5_integration.py          # 集成测试脚本
UR5_UNITY_IMPORT_GUIDE.md        # 详细导入指南
UR5_QUICK_START.md               # 本快速开始指南

---

🎯 下一步

导入和测试成功后，您可以：

1. 开发自定义控制器

   • 修改 UniversalRobotAdapter.cs
   • 实现自定义运动规划

2. 集成 MoveIt2 规划

   • 使用 planning_service.py 进行路径规划
   • 实现避障功能

3. 添加末端工具

   • 在 tool0 下添加夹爪或传感器模型
   • 更新 URDF 包含末端工具

4. 性能优化

   • 运行 PerformanceBenchmark.cs 测试
   • 调整物理参数和更新频率

5. 多机器人协同

   • 导入第二个机器人
   • 实现双臂协同任务

---

📚 参考文档

• 详细导入指南: UR5_UNITY_IMPORT_GUIDE.md
• 系统架构: SYSTEM_DESIGN.md
• Claude 工作规范: CLAUDE.md
• 部署指南: DEPLOYMENT_GUIDE.md

---

💡 提示

• 💾 经常保存: Unity 可能崩溃，记得保存场景和项目
• 🔍 查看 Console: 所有调试信息都在 Console 窗口
• 📝 记录问题: 遇到问题时记录 Console 输出，便于排查
• 🧪 小步测试: 每次修改后立即测试，避免问题累积

---

祝您使用愉快！ 如有问题，请查看详细文档或检查 Console 日志。🚀