unity2moveit2/UNITY_QUICK_FIX.md

Unity 快速修复指南 🔧

解决 "Base link not set" 错误

---

🎯 问题诊断

您遇到的错误日志：

[UniversalRobotAdapter] 基座链接未设置 / Base link not set
[UniversalRobotAdapter] 配置验证失败 / Configuration validation failed

原因: 场景中的机器人对象缺少实际的UR5结构（base_link和tool0）

---

✅ 解决方案（3选1）

方案 1: 使用自动化场景设置工具 ⚡ (最快)

适用场景: 从头开始创建新场景

步骤:

1. 删除当前场景中的问题对象

   • 在Hierarchy中选中有问题的机器人对象
   • 按Delete删除

2. 使用场景设置工具创建新场景

   • Unity菜单: Unity-MoveIt2 → Setup UR5 Scene
   • 场景名称: UR5_TestScene
   • 勾选所有选项
   • 点击 "创建 UR5 测试场景"

3. 完成后自动配置

   • 工具会自动创建UR5结构
   • 自动设置Base Link和End Effector
   • 无需手动配置

4. 保存并运行

   • Ctrl + S 保存场景
   • 点击 Play ▶️ 测试

---

方案 2: 在现有对象上添加UR5结构 🔨 (推荐)

适用场景: 保留当前场景，修复现有机器人对象

步骤:

1. 在Hierarchy中选中您的机器人对象

   • 通常名为 universal_robot 或 Robot

2. 添加UR5手动设置组件

   • Inspector → Add Component
   • 搜索: UR5 Manual Setup
   • 点击添加

3. 创建UR5结构

   • 在Inspector中找到 UR5ManualSetup 组件
   • 右键点击组件标题栏
   • 选择: 创建 UR5 结构 / Create UR5 Structure

   这会自动创建:

   您的机器人对象
   ├── base_link
   │   └── shoulder_link
   │       └── upper_arm_link
   │           └── forearm_link
   │               └── wrist_1_link
   │                   └── wrist_2_link
   │                       └── wrist_3_link
   │                           └── tool0
   

4. 自动配置完成

   • UR5ManualSetup会自动调用配置方法
   • Base Link和End Effector会自动设置
   • DOF自动设为6

5. 验证配置

   • 停止Play模式（如果正在运行）
   • 再次点击Play查看日志
   • 应该看到: ✓ 初始化成功

---

方案 3: 手动配置（如果已有UR5结构）🖐️

适用场景: 您已经手动创建了UR5的层级结构

步骤:

1. 添加自动配置组件

   • 选中您的机器人根对象
   • Add Component → Robot Auto Configurator

2. 配置参数

   • Base Link Name: base_link
   • End Effector Name: tool0
   • 勾选: Auto Configure At Runtime

3. 运行自动配置

   • 右键 RobotAutoConfigurator 组件
   • 选择: 自动配置机器人 / Auto Configure Robot

4. 验证

   • 右键组件选择: 验证配置 / Validate Configuration
   • 检查Console输出

---

🧪 验证修复结果

预期的正确日志

修复后，运行Unity应该看到：

[UR5ManualSetup] ✓ 自动设置 Base Link: base_link
[UR5ManualSetup] ✓ 自动设置 End Effector: tool0
[UR5ManualSetup] ✓ 自动设置 DOF: 6
[UR5ManualSetup] ✓ UniversalRobotAdapter 已自动配置完成!

[UniversalRobotAdapter] 初始化 6 DOF 机器人: UR5
[UniversalRobotAdapter] UR5 初始化成功 / Initialized successfully

[ROSTCPBridge] 成功连接到ROS2服务器

检查机器人结构

在Hierarchy中展开您的机器人对象，应该看到：

UR5_Robot (或您的对象名)
│
├── 📦 UniversalRobotAdapter     ✅
├── 📦 UR5ManualSetup           ✅
│
└── 🔗 base_link                 ✅
    └── 🔗 shoulder_link
        └── 🔗 upper_arm_link
            └── 🔗 forearm_link
                └── 🔗 wrist_1_link
                    └── 🔗 wrist_2_link
                        └── 🔗 wrist_3_link
                            └── 🎯 tool0

每个link都应该有：

• ✅ Articulation Body 组件
• ✅ 彩色球体标记（临时可视化）
• ✅ Collider（除了tool0）

---

🎨 可视化检查

在Scene视图中

进入Play模式后，在Scene视图中应该看到：

• 青色球体 = 各个关节link
• 红色球体 = 末端执行器（tool0）
• 黄色线条 = 连接层级关系（Gizmos）

调整视角

1. 在Hierarchy中选中 base_link
2. 按键盘 F 键聚焦到对象
3. 鼠标中键拖拽旋转视角
4. 滚轮缩放

---

⚙️ 测试关节运动

快速测试

1. 进入Play模式
2. 在Hierarchy中选中 shoulder_link
3. 在Inspector中找到 Articulation Body
4. 展开 X Drive
5. 修改 Target 值 (例如: 0 → 30)
6. 观察机器人肩部旋转

预期结果

• 关节应该平滑旋转
• 子链接跟随父链接运动
• 末端执行器（红球）随整体结构移动

---

❌ 常见问题

Q1: 看不到 "Unity-MoveIt2" 菜单

解决:

1. Assets → Reimport All
2. 等待编译完成（检查右下角进度条）
3. 重启Unity编辑器

Q2: "创建 UR5 结构"后看不到对象

解决:

1. 在Hierarchy中双击机器人对象（自动聚焦）
2. 检查Scene视图（不是Game视图）
3. 确保对象的Position为(0, 0, 0)

Q3: 关节不动

检查:

1. 确认在Play模式下
2. 检查 Articulation Body → Drive → Stiffness > 0
3. Edit → Project Settings → Physics → Solver Iterations ≥ 12

Q4: 仍然显示"Base link not set"

排查:

1. 停止Play模式
2. 选中机器人对象
3. 右键 UR5ManualSetup 组件
4. 重新执行 "创建 UR5 结构"
5. 检查Console确认自动配置日志

---

📋 完整操作检查清单

• 停止当前Play模式
• 选择修复方案（推荐方案2）
• 添加UR5ManualSetup组件
• 执行"创建 UR5 结构"
• 检查Console日志确认自动配置成功
• 保存场景 (Ctrl + S)
• 进入Play模式测试
• 验证日志无错误
• 在Scene视图中观察机器人结构
• 测试关节运动

---

🚀 下一步

配置成功后，您可以：

1. 添加实际Mesh模型

当前使用彩色球体，替换为真实模型：

1. 在Assets中找到 UR5/meshes/ur5/visual/
2. 为每个link添加对应的.obj文件
3. 配置材质和渲染器

2. 测试IK/FK

1. 添加 InteractiveEndEffectorController 组件
2. 在Scene视图中拖拽末端执行器
3. 测试逆运动学求解

3. 集成MoveIt2规划

1. 确认ROS2连接成功
2. 测试路径规划服务
3. 验证轨迹执行

---

📚 相关文档

• 完整配置指南: UNITY_SETUP_COMPLETE_GUIDE.md
• 快速开始: UR5_QUICK_START.md
• 系统设计: SYSTEM_DESIGN.md

---

💡 提示

• 💾 经常保存: Unity可能不稳定
• 🔍 查看Console: 所有调试信息都在这里
• 🎬 先停止Play再修改: 避免修改丢失
• 🧪 小步测试: 每次修改后立即验证

---

如果仍有问题，请截图Console完整日志！ 📸