unity2moveit2/docs/deployment/DEPLOYMENT.md

Unity-MoveIt2 部署指南

📋 目录

• 1. 环境要求
• 2. 快速部署
• 3. 详细安装步骤
• 4. 配置说明
• 5. Docker部署
• 6. 开发环境搭建
• 7. 故障排除
• 8. 性能优化

1. 环境要求

1.1 硬件要求

组件	最低要求	推荐配置
CPU	Intel i5-8400 / AMD Ryzen 5 2600	Intel i7-10700K / AMD Ryzen 7 3700X
内存	8GB RAM	16GB RAM
显卡	GTX 1060 / RX 580	RTX 3070 / RX 6700 XT
存储	20GB 可用空间	50GB SSD
网络	千兆以太网	千兆以太网

1.2 软件要求

Windows环境

• 操作系统: Windows 10/11 (64位)
• Unity: 2022.3 LTS 或更高版本
• Docker Desktop: 4.0+ (可选，用于ROS2容器)
• Git: 2.30+
• Visual Studio: 2019/2022 (可选，用于C#开发)

Linux环境

• 操作系统: Ubuntu 20.04/22.04 LTS
• ROS2: Humble Hawksbill 或 Iron Irwini
• Docker: 20.10+
• Unity: 通过Unity Hub安装

网络要求

• 端口: 10000 (ROS TCP Bridge)
• 防火墙: 允许Unity与ROS2通信
• 延迟: < 10ms (本地网络)

2. 快速部署

2.1 一键部署脚本

# Windows (PowerShell)
.\scripts\quick-deploy.ps1

# Linux/macOS
./scripts/quick-deploy.sh

2.2 Docker Compose部署

# 克隆项目
git clone <repository-url>
cd DockerRos2Arm-niryo_arm

# 启动所有服务
docker-compose up -d

# 检查服务状态
docker-compose ps

2.3 验证部署

# 检查ROS2服务
ros2 service list | grep unity

# 检查话题
ros2 topic list | grep joint

# 测试通信
ros2 topic echo /joint_states

3. 详细安装步骤

3.1 ROS2环境安装

Ubuntu 22.04安装ROS2 Humble

# 1. 设置locale
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

# 2. 添加ROS2 APT源
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# 3. 安装ROS2
sudo apt update
sudo apt upgrade
sudo apt install ros-humble-desktop

# 4. 安装开发工具
sudo apt install ros-dev-tools

# 5. 环境设置
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

Windows安装ROS2

# 1. 下载ROS2 Humble Windows版本
# https://github.com/ros2/ros2/releases

# 2. 解压到C:\ros2_humble

# 3. 设置环境变量
$env:PATH += ";C:\ros2_humble\bin"
$env:PYTHONPATH += ";C:\ros2_humble\Lib\site-packages"

# 4. 安装Visual C++ Redistributables
# https://aka.ms/vs/17/release/vc_redist.x64.exe

3.2 MoveIt2安装

# Ubuntu
sudo apt install ros-humble-moveit
sudo apt install ros-humble-moveit-planners
sudo apt install ros-humble-moveit-plugins
sudo apt install ros-humble-moveit-ros-planning-interface

# 验证安装
ros2 pkg list | grep moveit

3.3 Unity环境搭建

安装Unity Hub和Unity Editor

# 1. 下载Unity Hub
# https://unity3d.com/get-unity/download

# 2. 安装Unity 2022.3 LTS
# 通过Unity Hub安装，选择以下模块：
# - Windows Build Support (IL2CPP)
# - Linux Build Support (Mono)
# - Visual Studio Community (Windows)

安装ROS TCP Connector

# 在Unity Package Manager中添加：
# https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.ros-tcp-connector

3.4 项目构建

构建ROS2工作空间

# 1. 创建工作空间
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

# 2. 克隆项目
git clone <repository-url> src/unity_moveit_bridge

# 3. 安装依赖
rosdep install --from-paths src --ignore-src -r -y

# 4. 构建
colcon build --symlink-install

# 5. 设置环境
echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

配置Unity项目

# 1. 打开Unity Hub
# 2. 添加项目：选择unity-project目录
# 3. 打开项目
# 4. 导入ROS TCP Connector包
# 5. 配置ROS Settings
#    - ROS IP Address: 127.0.0.1
#    - ROS Port: 10000

4. 配置说明

4.1 机器人配置

创建机器人配置文件

# configs/robots/niryo_one.yaml
robot_name: "niryo_one"
description: "Niryo One 6-DOF Robot Arm"
dof: 6
urdf_path: "robots/niryo_one/niryo_one.urdf"
srdf_path: "robots/niryo_one/niryo_one.srdf"

# 关节配置
joints:
  - name: "joint_1"
    type: "revolute"
    axis: [0, 0, 1]
    limits:
      lower: -3.14159
      upper: 3.14159
      velocity: 1.0
      effort: 50.0
  # ... 其他关节配置

# 运动学配置
kinematics:
  group_name: "manipulator"
  base_link: "base_link"
  tip_link: "tool_link"
  solver: "kdl_kinematics_plugin/KDLKinematicsPlugin"

# 规划配置
planning:
  default_planner: "RRTConnect"
  planning_time: 5.0
  planning_attempts: 10
  max_velocity_scaling: 0.5
  max_acceleration_scaling: 0.5

4.2 Unity配置

ROS连接配置

{
  "ros_connection": {
    "ip_address": "127.0.0.1",
    "port": 10000,
    "timeout": 5.0,
    "retry_attempts": 3,
    "heartbeat_interval": 1.0
  },
  "visualization": {
    "show_trajectory": true,
    "show_collision_objects": true,
    "show_workspace": true,
    "trajectory_color": "#00FF00",
    "collision_color": "#FF0000",
    "workspace_transparency": 0.3
  },
  "performance": {
    "update_rate": 30,
    "max_trajectory_points": 1000,
    "collision_check_resolution": 0.01
  }
}

4.3 Docker配置

Docker Compose文件

# docker-compose.yml
version: '3.8'

services:
  ros2-bridge:
    build:
      context: ./ros2-workspace
      dockerfile: Dockerfile
    ports:
      - "10000:10000"
    environment:
      - ROS_DOMAIN_ID=42
      - RMW_IMPLEMENTATION=rmw_cyclonedx_cpp
    volumes:
      - ./configs:/workspace/configs:ro
      - ./logs:/workspace/logs
    networks:
      - unity-ros-network
    restart: unless-stopped

  moveit-planner:
    build:
      context: ./ros2-workspace
      dockerfile: Dockerfile.moveit
    depends_on:
      - ros2-bridge
    environment:
      - ROS_DOMAIN_ID=42
    volumes:
      - ./configs/robots:/workspace/robots:ro
    networks:
      - unity-ros-network
    restart: unless-stopped

  feasibility-analyzer:
    build:
      context: ./analysis-service
      dockerfile: Dockerfile
    depends_on:
      - ros2-bridge
    environment:
      - ROS_DOMAIN_ID=42
    volumes:
      - ./configs/analysis:/workspace/configs:ro
    networks:
      - unity-ros-network
    restart: unless-stopped

networks:
  unity-ros-network:
    driver: bridge

Dockerfile示例

# ros2-workspace/Dockerfile
FROM ros:humble-desktop

# 安装依赖
RUN apt-get update && apt-get install -y \
    ros-humble-moveit \
    ros-humble-ros-tcp-endpoint \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# 安装Python依赖
COPY requirements.txt /tmp/
RUN pip3 install -r /tmp/requirements.txt

# 复制源码
COPY src /workspace/src
WORKDIR /workspace

# 构建
RUN . /opt/ros/humble/setup.sh && \
    colcon build --symlink-install

# 设置入口点
COPY docker-entrypoint.sh /
RUN chmod +x /docker-entrypoint.sh
ENTRYPOINT ["/docker-entrypoint.sh"]

# 默认命令
CMD ["ros2", "launch", "unity_moveit_bridge", "bridge.launch.py"]

5. Docker部署

5.1 构建镜像

# 构建所有服务
docker-compose build

# 构建特定服务
docker-compose build ros2-bridge

# 查看镜像
docker images | grep unity-moveit

5.2 启动服务

# 启动所有服务
docker-compose up -d

# 启动特定服务
docker-compose up -d ros2-bridge moveit-planner

# 查看日志
docker-compose logs -f ros2-bridge

# 进入容器
docker-compose exec ros2-bridge bash

5.3 服务管理

# 停止服务
docker-compose stop

# 重启服务
docker-compose restart ros2-bridge

# 删除服务
docker-compose down

# 删除所有数据
docker-compose down -v

6. 开发环境搭建

6.1 IDE配置

Visual Studio Code

// .vscode/settings.json
{
    "python.defaultInterpreter": "/opt/ros/humble/bin/python3",
    "python.autoComplete.extraPaths": [
        "/opt/ros/humble/lib/python3.10/site-packages",
        "/workspace/install/lib/python3.10/site-packages"
    ],
    "ros.distro": "humble",
    "C_Cpp.default.includePath": [
        "/opt/ros/humble/include/**",
        "/workspace/install/include/**"
    ]
}

Unity Editor配置

// Unity Editor设置
// Edit -> Project Settings -> XR Plug-in Management
// 启用所需的XR提供程序

// Window -> Package Manager
// 安装以下包：
// - ROS TCP Connector
// - Universal Render Pipeline
// - ProBuilder (可选)

6.2 调试配置

ROS2调试

# 启用调试日志
export RCUTILS_LOGGING_SEVERITY=DEBUG

# 使用GDB调试
gdb --args ros2 run unity_moveit_bridge bridge_node

# 使用Valgrind检查内存
valgrind --tool=memcheck ros2 run unity_moveit_bridge bridge_node

Unity调试

// Unity Console日志级别
Debug.unityLogger.logEnabled = true;
Debug.unityLogger.filterLogType = LogType.Log;

// 性能分析
using UnityEngine.Profiling;
Profiler.BeginSample("RobotUpdate");
// ... 代码 ...
Profiler.EndSample();

7. 故障排除

7.1 常见问题

连接问题

# 问题：Unity无法连接到ROS2
# 解决方案：
1. 检查防火墙设置
   sudo ufw allow 10000
   
2. 检查ROS2服务状态
   ros2 service list | grep unity
   
3. 检查网络连接
   telnet 127.0.0.1 10000
   
4. 重启ROS TCP Bridge
   ros2 launch ros_tcp_endpoint endpoint.launch.py

规划失败

# 问题：路径规划失败
# 解决方案：
1. 检查URDF文件
   check_urdf robot.urdf
   
2. 检查SRDF配置
   # 验证规划组配置
   
3. 增加规划时间
   # 在配置中设置更长的planning_time
   
4. 尝试不同规划器
   # RRTConnect, RRT, PRM等

性能问题

# 问题：系统响应慢
# 解决方案：
1. 检查CPU使用率
   top -p $(pgrep -f ros2)
   
2. 检查内存使用
   free -h
   
3. 优化QoS设置
   # 使用BEST_EFFORT而非RELIABLE
   
4. 减少可视化频率
   # 降低update_rate

7.2 日志分析

ROS2日志

# 查看ROS2日志
ros2 log list
ros2 log view <node_name>

# 设置日志级别
ros2 run unity_moveit_bridge bridge_node --ros-args --log-level DEBUG

# 保存日志到文件
ros2 launch unity_moveit_bridge bridge.launch.py 2>&1 | tee bridge.log

Unity日志

// Unity日志文件位置
// Windows: %USERPROFILE%\AppData\LocalLow\<companyname>\<productname>\Player.log
// Linux: ~/.config/unity3d/<companyname>/<productname>/Player.log

// 自定义日志
public class Logger
{
    public static void LogToFile(string message)
    {
        string logPath = Path.Combine(Application.persistentDataPath, "unity_ros.log");
        File.AppendAllText(logPath, $"{DateTime.Now}: {message}\n");
    }
}

8. 性能优化

8.1 网络优化

// ROS2 QoS优化
rclcpp::QoS qos_profile(10);
qos_profile.reliability(RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT);
qos_profile.durability(RMW_QOS_POLICY_DURABILITY_VOLATILE);
qos_profile.deadline(std::chrono::milliseconds(33)); // 30Hz

auto publisher = node->create_publisher<sensor_msgs::msg::JointState>(
    "/joint_states", qos_profile);

8.2 Unity优化

// Unity性能优化
public class PerformanceOptimizer : MonoBehaviour
{
    void Start()
    {
        // 设置目标帧率
        Application.targetFrameRate = 60;
        
        // 启用多线程渲染
        QualitySettings.vSyncCount = 0;
        
        // 优化物理更新
        Time.fixedDeltaTime = 0.02f; // 50Hz
        
        // 启用GPU Instancing
        Graphics.DrawMeshInstanced(...);
    }
}

8.3 系统监控

# 创建监控脚本
#!/bin/bash
# monitor.sh

while true; do
    echo "=== $(date) ==="
    echo "CPU Usage:"
    top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1
    
    echo "Memory Usage:"
    free -h | grep "Mem:" | awk '{print $3 "/" $2}'
    
    echo "ROS2 Processes:"
    ps aux | grep ros2 | wc -l
    
    echo "Network Connections:"
    netstat -an | grep :10000
    
    sleep 5
done

---

总结

本部署指南提供了Unity-MoveIt2系统的完整部署流程，包括：

1. 环境准备：硬件要求、软件依赖
2. 快速部署：一键脚本、Docker Compose
3. 详细安装：分步骤安装指南
4. 配置管理：机器人、Unity、Docker配置
5. 开发环境：IDE配置、调试设置
6. 故障排除：常见问题解决方案
7. 性能优化：网络、Unity、系统优化

通过遵循本指南，您可以快速搭建一个稳定、高性能的机械臂仿真系统。如遇到问题，请参考故障排除章节或联系技术支持。