unity2moveit2/docs/deployment/DEPLOYMENT.md

# Unity-MoveIt2 部署指南

## 📋 目录

- [1. 环境要求](#1-环境要求)
- [2. 快速部署](#2-快速部署)
- [3. 详细安装步骤](#3-详细安装步骤)
- [4. 配置说明](#4-配置说明)
- [5. Docker部署](#5-docker部署)
- [6. 开发环境搭建](#6-开发环境搭建)
- [7. 故障排除](#7-故障排除)
- [8. 性能优化](#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 一键部署脚本

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

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

### 2.2 Docker Compose部署

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

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

# 检查服务状态
docker-compose ps
```

### 2.3 验证部署

```bash
# 检查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

```bash
# 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

```powershell
# 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安装

```bash
# 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

```bash
# 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

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

### 3.4 项目构建

#### 构建ROS2工作空间

```bash
# 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项目

```bash
# 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 机器人配置

#### 创建机器人配置文件

```yaml
# 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连接配置

```json
{
  "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文件

```yaml
# 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示例

```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 构建镜像

```bash
# 构建所有服务
docker-compose build

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

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

### 5.2 启动服务

```bash
# 启动所有服务
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 服务管理

```bash
# 停止服务
docker-compose stop

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

# 删除服务
docker-compose down

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

## 6. 开发环境搭建

### 6.1 IDE配置

#### Visual Studio Code

```json
// .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配置

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

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

### 6.2 调试配置

#### ROS2调试

```bash
# 启用调试日志
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调试

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

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

## 7. 故障排除

### 7.1 常见问题

#### 连接问题

```bash
# 问题：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
```

#### 规划失败

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

#### 性能问题

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

### 7.2 日志分析

#### ROS2日志

```bash
# 查看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日志

```csharp
// 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 网络优化

```cpp
// 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优化

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

### 8.3 系统监控

```bash
# 创建监控脚本
#!/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、系统优化

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