unity2moveit2/UNITY_SETUP_COMPLETE_GUIDE.md

Unity 完整配置指南 🎮

Unity-MoveIt2项目 - UR5机器人完整配置教程

本指南提供Unity项目的完整配置步骤，包括所有必需的脚本、场景和组件设置。

---

📋 目录

1. 前提条件
2. Unity项目配置
3. 创建UR5机器人
4. 配置ROS连接
5. 测试验证
6. 常见问题

---

前提条件

✅ 必需项

• Unity版本: 2022.3.57f1c2 LTS (推荐) 或 2022.3.x 系列
• Docker环境: ROS2容器 unity-ros2-system 正在运行
• 操作系统: Windows 10/11

✅ 验证Docker状态

# 检查Docker容器
docker ps | grep unity-ros2-system

# 应显示容器状态为 Up (healthy)

✅ 项目文件检查

确认以下文件存在：

• UR5/urdf/ur5.urdf - UR5 URDF模型
• UR5/meshes/ - UR5 mesh文件（.obj和.stl）
• configs/robots/ur5.yaml - UR5配置文件

---

Unity项目配置

步骤 1: 打开Unity项目

1. 启动 Unity Hub
2. 添加项目：d:\ros2\DockerRos2Arm-niryo_arm\Unity_MoveIt2\unity-project
3. 使用Unity 2022.3.57f1c2打开项目

步骤 2: 验证包安装

打开 Window → Package Manager 确认以下包已安装：

包名	版本	状态
ROS TCP Connector	0.7.0	✅ 已安装
Test Framework	1.1.33	✅ 已安装
TextMeshPro	3.0.6	✅ 已安装

如果缺少ROS TCP Connector：

1. Package Manager → Add package from git URL
2. 输入: https://github.com/Unity-Technologies/ROS-TCP-Connector.git
3. 点击 Add

步骤 3: 检查Assembly Definitions

项目使用模块化Assembly Definitions：

Assets/Scripts/
├── Core/                    # Core.asmdef
│   ├── UniversalRobotAdapter.cs
│   ├── UR5ManualSetup.cs
│   ├── UrdfRobotImporter.cs
│   └── ...
├── Communication/           # Communication.asmdef
│   ├── ROSTCPBridge.cs
│   └── MessageConverter.cs
├── Managers/               # Managers.asmdef
│   └── RobotManager.cs
├── RosMessages/            # RosMessages.asmdef
│   └── (ROS消息类型)
├── Editor/                 # Editor.asmdef
│   └── UR5SceneSetup.cs
└── Tests/                  # Tests.asmdef
    └── (测试脚本)

步骤 4: 项目设置

1. Edit → Project Settings → Player

   • API Compatibility Level: .NET Framework
   • Scripting Backend: Mono

2. Edit → Project Settings → Physics

   • Solver Iterations: 12 (提高关节稳定性)
   • Solver Velocity Iterations: 8

---

创建UR5机器人

方式 1: 使用自动化场景设置工具 🚀 (推荐)

这是最快速的方式，会自动创建完整的测试场景。

步骤 1: 打开场景设置工具

在Unity菜单栏选择：

Unity-MoveIt2 → Setup UR5 Scene

步骤 2: 配置场景参数

在弹出窗口中设置：

参数	值	说明
场景名称	UR5_TestScene	场景文件名
创建相机	✅	自动配置观察视角
创建光照	✅	添加定向光
创建地面	✅	创建2x2米地面
创建ROS连接	✅	自动添加ROSTCPBridge
ROS IP	127.0.0.1	Docker ROS2地址
ROS Port	10000	ROS-TCP-Endpoint端口

步骤 3: 创建场景

点击 "创建 UR5 测试场景" 按钮

工具会自动完成：

• ✅ 创建UR5机器人结构（6个关节）
• ✅ 配置Articulation Bodies
• ✅ 设置相机和光照
• ✅ 创建地面
• ✅ 添加ROS连接对象
• ✅ 保存场景到 Assets/Scenes/UR5_TestScene.unity

步骤 4: 完成配置

创建完成后，需要手动配置以下内容：

1. 在Hierarchy中选中 UR5_Robot

2. 在Inspector中找到 Universal Robot Adapter 组件

3. 配置以下字段：

   字段	操作
   DOF	确认为 6
   Base Link	从Hierarchy拖拽 base_link 到此字段
   End Effector	从Hierarchy拖拽 tool0 到此字段
   Robot Config Path	输入 configs/robots/ur5.yaml

4. 在Hierarchy中选中 ROS_Connection

5. 在Inspector中配置 ROSTCPBridge 组件：

   字段	值
   ROS IP	127.0.0.1
   ROS Port	10000
   Auto Reconnect	✅ 勾选
   Publish Rate	50 Hz

6. 保存场景: Ctrl + S

---

方式 2: 手动创建UR5机器人

如果您想手动控制每一步：

步骤 1: 创建空场景

1. File → New Scene
2. File → Save As → Assets/Scenes/UR5_Manual.unity

步骤 2: 创建UR5机器人对象

1. Hierarchy → 右键 → Create Empty
2. 命名为 UR5_Robot
3. 设置位置为原点 (0, 0, 0)

步骤 3: 添加UR5手动设置组件

1. 选中 UR5_Robot 对象
2. 在Inspector中点击 Add Component
3. 搜索并添加 UR5 Manual Setup
4. 在Inspector中右键 UR5ManualSetup 组件
5. 选择 "创建 UR5 结构 / Create UR5 Structure"

这会自动创建：

• base_link (固定基座)
• shoulder_link (肩部旋转关节)
• upper_arm_link (肩部抬升关节)
• forearm_link (肘关节)
• wrist_1_link (腕关节1)
• wrist_2_link (腕关节2)
• wrist_3_link (腕关节3)
• tool0 (末端执行器)

步骤 4: 验证结构

在Inspector中右键 UR5ManualSetup 组件，选择 "验证导入 / Validate Import"

检查Console输出，应显示：

✓ 找到 base_link
✓ 找到 tool0 末端执行器
✓ 找到 8 个 Mesh Renderer
✓ 找到 X 个 Articulation Body
========== ✓ 导入验证完成 ==========

步骤 5: 配置机器人适配器

按照方式1的步骤4完成配置。

---

配置ROS连接

步骤 1: 创建ROS连接对象

如果使用方式2手动创建：

1. Hierarchy → 右键 → Create Empty
2. 命名为 ROS_Connection
3. 位置设为 (0, 0, 0)

步骤 2: 添加ROSTCPBridge组件

1. 选中 ROS_Connection 对象
2. Add Component → Scripts → ROS TCP Bridge
3. 配置参数（见上方表格）

步骤 3: 测试连接

1. 确保Docker容器运行中
2. 点击Unity的 Play 按钮
3. 检查Console输出

成功连接时应看到：

[ROSTCPBridge] 初始化ROS TCP桥梁
[ROSTCPBridge] 正在连接到ROS2服务器: 127.0.0.1:10000
[ROSTCPBridge] 成功连接到ROS2服务器

连接失败时检查：

• Docker容器是否运行
• 端口映射是否正确
• Windows防火墙设置

---

测试验证

测试 1: 可视化检查

1. 进入Play模式
2. Scene视图中应看到：
   • UR5机器人结构（带彩色标记球）
   • 连接线显示关节层级
   • 红色球标记末端执行器（tool0）

测试 2: 关节运动测试

方法 A: 手动调整关节

1. Play模式下，在Hierarchy中选中 shoulder_link
2. 在Inspector中找到 Articulation Body 组件
3. 展开 X Drive 部分
4. 修改 Target 值（例如：0 → 30）
5. 观察机器人肩关节旋转

方法 B: 使用脚本测试

创建测试脚本：

// 文件: Assets/Scripts/Tests/UR5MovementTest.cs
using UnityEngine;
using UnityMoveIt2.Core;

public class UR5MovementTest : MonoBehaviour
{
    public UniversalRobotAdapter robot;

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            // 测试关节位置
            float[] targetJoints = new float[] {
                30f, -30f, 45f, 0f, 0f, 0f
            };
            Debug.Log("移动到测试位置");
            // 调用机器人移动方法
        }
    }
}

测试 3: ROS2服务验证

在PowerShell中运行：

# 进入Docker容器
docker exec -it unity-ros2-system bash

# 检查ROS2节点
source /opt/ros/jazzy/setup.bash
ros2 node list
# 应显示: /UnityEndpoint

# 检查话题
ros2 topic list
# 应显示Unity相关话题

# 检查服务
ros2 service list | grep -E 'ik|fk|plan'

测试 4: 性能检查

1. Window → Analysis → Profiler
2. 进入Play模式
3. 检查以下指标：

指标	期望值	说明
FPS	> 30	帧率
CPU Time	< 20ms	主线程时间
Physics	< 5ms	物理模拟时间
Scripts	< 10ms	脚本执行时间

---

常见问题

❌ 问题 1: 找不到UR5SceneSetup菜单

原因: Editor脚本未正确编译

解决方案:

1. 检查 Assets/Scripts/Editor/UR5SceneSetup.cs 是否存在
2. 检查 Assets/Scripts/Editor/Editor.asmdef 是否正确配置
3. Assets → Reimport All 重新导入所有资源
4. 重启Unity编辑器

❌ 问题 2: ROS连接失败

症状: Console显示 "连接失败"

排查步骤:

# 1. 检查Docker
docker ps | grep unity-ros2-system

# 2. 检查端口映射
docker port unity-ros2-system
# 应显示: 10000/tcp -> 0.0.0.0:10000

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

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

❌ 问题 3: 关节不运动

可能原因:

1. Articulation Body配置错误
2. 关节驱动参数设置不当
3. 物理设置问题

解决方案:

1. 选中关节对象，检查 Articulation Body 组件
2. 确认 Drive 设置：
   • Stiffness: 10000
   • Damping: 100
   • Force Limit: 150
3. Edit → Project Settings → Physics
   • Solver Iterations ≥ 12

❌ 问题 4: 机器人看不见

解决方案:

1. Scene视图中双击 UR5_Robot 对象（自动聚焦）
2. 检查Mesh Renderer是否启用
3. 当前版本使用彩色标记球可视化（临时）
4. 后续需要手动添加实际mesh模型

❌ 问题 5: 编译错误

常见错误:

error CS0246: The type or namespace name 'UnityMoveIt2' could not be found

解决方案:

1. 检查所有 .asmdef 文件的引用关系
2. Assets → Reimport All
3. 关闭并重新打开Unity
4. 删除 Library/ 文件夹并重新打开项目

---

📁 完整文件清单

核心脚本

✅ 已创建的脚本：

Assets/Scripts/
├── Core/
│   ├── UniversalRobotAdapter.cs        ✅ 通用机器人适配器
│   ├── UR5ManualSetup.cs               ✅ UR5手动配置工具
│   ├── UrdfRobotImporter.cs            ✅ URDF导入辅助
│   ├── InteractiveEndEffectorController.cs ✅ 末端控制器
│   ├── VisualizationEngine.cs          ✅ 可视化引擎
│   └── Core.asmdef                     ✅
├── Communication/
│   ├── ROSTCPBridge.cs                 ✅ ROS通信桥
│   ├── MessageConverter.cs             ✅ 消息转换器
│   └── Communication.asmdef            ✅
├── Managers/
│   ├── RobotManager.cs                 ✅ 机器人管理器
│   └── Managers.asmdef                 ✅
├── Editor/
│   ├── UR5SceneSetup.cs                ✅ 场景设置工具
│   └── Editor.asmdef                   ✅
└── Tests/
    └── Tests.asmdef                    ✅

配置文件

configs/robots/
└── ur5.yaml                            ✅ UR5配置

UR5/
├── urdf/
│   ├── ur5.urdf                        ✅ URDF模型
│   └── ur5.srdf                        ✅ 语义配置
└── meshes/
    └── ur5/
        ├── visual/*.obj                ✅ 可视化mesh
        └── collision/*.stl             ✅ 碰撞mesh

---

🎯 下一步

Unity配置完成后，您可以：

1. 添加实际Mesh模型

当前使用彩色球体标记，需要：

• 为每个link加载对应的mesh文件
• 从 Assets/UR5/meshes/ur5/visual/ 加载.obj文件
• 配置材质和渲染器

2. 测试IK/FK功能

• 使用 InteractiveEndEffectorController 拖拽末端
• 测试逆运动学求解
• 验证关节限位

3. 集成MoveIt2规划

• 配置路径规划服务
• 测试轨迹规划和执行
• 验证碰撞检测

4. 性能优化

• 运行性能基准测试
• 调整发布频率
• 优化物理参数

5. 开发自定义控制

• 修改 UniversalRobotAdapter
• 实现自定义运动控制
• 添加传感器模拟

---

📚 参考文档

• 快速开始: UR5_QUICK_START.md
• 系统设计: SYSTEM_DESIGN.md
• 开发规范: CLAUDE.md
• 部署指南: DEPLOYMENT_GUIDE.md
• Docker部署: DOCKER_DEPLOYMENT_GUIDE.md

---

💡 提示

• 💾 经常保存: Unity可能不稳定，记得 Ctrl + S
• 🔍 查看Console: 所有日志信息都在Console窗口
• 📝 记录问题: 遇到错误时截图Console输出
• 🧪 小步测试: 每次修改后立即测试
• 🎨 使用Scene视图: 可视化调试关节结构

---

祝您配置顺利！ 🚀

如有问题，请检查Console日志或查阅相关文档。