unity2moveit2/DEPLOYMENT_GUIDE.md

# Unity-ROS2 系统部署指南

## 📋 部署概述

本指南将帮助您在Windows 11环境下部署Unity-ROS2机器人控制系统，使用Ubuntu 24.04 LTS作为ROS2运行环境。

**部署架构**:
- **Windows 11**: Unity开发环境 + Docker Desktop
- **Ubuntu 24.04 LTS**: ROS2 Jazzy运行环境 (通过WSL2或Docker)
- **通信方式**: TCP/IP网络通信

## 🛠️ 环境检查

### 当前环境状态
- ✅ **Windows版本**: Windows 10 Pro for Workstations (版本 2009)
  - ⚠️ **建议升级**: 推荐升级到Windows 11以获得更好的WSL2支持
- ✅ **Docker**: Docker version 28.4.0 已安装
- ✅ **WSL2**: WSL 版本 2.6.1.0 已安装
- ⚠️ **Ubuntu发行版**: 当前只有docker-desktop，需要安装Ubuntu 24.04

## 🚀 部署步骤

### 第一阶段：环境准备

#### 1.1 升级Windows系统 (可选但推荐)
```powershell
# 检查Windows更新
Get-WindowsUpdate
# 或通过设置 -> Windows更新进行升级
```

#### 1.2 安装Ubuntu 24.04 LTS
```powershell
# 安装Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

# 或者从Microsoft Store安装
# 搜索 "Ubuntu 24.04 LTS" 并安装
```

#### 1.3 配置WSL2
```powershell
# 设置WSL2为默认版本
wsl --set-default-version 2

# 设置Ubuntu 24.04为默认发行版
wsl --set-default Ubuntu-24.04
```

### 第二阶段：ROS2 Jazzy安装

#### 2.1 进入Ubuntu环境
```powershell
# 启动Ubuntu 24.04
wsl -d Ubuntu-24.04
```

#### 2.2 系统更新和基础依赖
```bash
# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl gnupg2 lsb-release software-properties-common

# 安装Python 3.10+
sudo apt install -y python3 python3-pip python3-dev
```

#### 2.3 安装ROS2 Jazzy
```bash
# 添加ROS2 GPG密钥
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

# 添加ROS2源
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

# 更新包列表
sudo apt update

# 安装ROS2 Jazzy Desktop
sudo apt install -y ros-jazzy-desktop

# 安装开发工具
sudo apt install -y ros-dev-tools
```

#### 2.4 安装项目依赖
```bash
# 安装ROS-TCP-Endpoint
sudo apt install -y ros-jazzy-ros-tcp-endpoint

# 安装MoveIt2
sudo apt install -y ros-jazzy-moveit

# 安装其他依赖
sudo apt install -y ros-jazzy-ros2-control ros-jazzy-ros2-controllers
sudo apt install -y ros-jazzy-joint-state-publisher ros-jazzy-robot-state-publisher
sudo apt install -y ros-jazzy-xacro ros-jazzy-urdf
```

#### 2.5 配置ROS2环境
```bash
# 添加到bashrc
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc

# 验证安装
ros2 --version
```

### 第三阶段：Unity环境配置

#### 3.1 安装Unity Hub和Unity Editor
1. 下载并安装 [Unity Hub](https://unity3d.com/get-unity/download)
2. 通过Unity Hub安装Unity 2021.3 LTS或更高版本
3. 确保安装了以下模块：
   - Windows Build Support (IL2CPP)
   - Linux Build Support (IL2CPP)

#### 3.2 导入Unity项目
```powershell
# 切换到项目目录
cd "D:\ros2\DockerRos2Arm-niryo_arm\Unity_MoveIt2\unity-project"

# 使用Unity Hub打开项目
# 或直接双击 .unity 文件
```

#### 3.3 安装Unity包依赖
在Unity Package Manager中安装：
- **ROS-TCP-Connector** (如果需要)
- **Unity Test Framework**
- **Input System** (新版本)

### 第四阶段：Docker环境配置

#### 4.1 创建ROS2 Docker镜像
```bash
# 在WSL Ubuntu中创建Dockerfile
cat > ~/ros2_jazzy_dockerfile << 'EOF'
FROM ros:jazzy-desktop

# 安装项目依赖
RUN apt-get update && apt-get install -y \
    ros-jazzy-ros-tcp-endpoint \
    ros-jazzy-moveit \
    ros-jazzy-ros2-control \
    ros-jazzy-ros2-controllers \
    ros-jazzy-joint-state-publisher \
    ros-jazzy-robot-state-publisher \
    ros-jazzy-xacro \
    ros-jazzy-urdf \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /ros2_ws

# 设置环境变量
ENV ROS_DOMAIN_ID=0
ENV RMW_IMPLEMENTATION=rmw_cyclonedx_cpp

# 启动脚本
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]
CMD ["bash"]
EOF

# 创建启动脚本
cat > ~/entrypoint.sh << 'EOF'
#!/bin/bash
source /opt/ros/jazzy/setup.bash
exec "$@"
EOF
```

#### 4.2 构建Docker镜像
```bash
# 构建镜像
docker build -t unity-ros2-jazzy -f ~/ros2_jazzy_dockerfile ~/

# 验证镜像
docker images | grep unity-ros2-jazzy
```

### 第五阶段：网络配置

#### 5.1 配置网络通信
```bash
# 在WSL中获取IP地址
ip addr show eth0

# 在Windows中配置防火墙规则（以管理员身份运行PowerShell）
New-NetFirewallRule -DisplayName "ROS2-Unity-TCP" -Direction Inbound -Protocol TCP -LocalPort 10000-10010 -Action Allow
```

#### 5.2 测试网络连通性
```bash
# 在Ubuntu中启动ROS2节点
ros2 run ros_tcp_endpoint default_server_endpoint --ros-args -p ROS_IP:=0.0.0.0 -p ROS_TCP_PORT:=10000

# 在Windows中测试连接
# telnet <WSL_IP> 10000
```

## 🧪 部署验证

### 验证步骤

#### 1. ROS2环境验证
```bash
# 在WSL Ubuntu中
ros2 topic list
ros2 node list
ros2 service list
```

#### 2. Unity项目验证
1. 打开Unity项目
2. 运行测试场景
3. 检查控制台是否有错误

#### 3. 通信验证
1. 启动ROS2 TCP端点
2. 在Unity中配置连接参数
3. 测试消息收发

#### 4. 完整系统测试
```bash
# 运行集成测试
# 在Unity中按F5或运行TestRunner组件
```

## 📊 性能优化

### 系统配置建议

#### WSL2优化
```bash
# 创建 .wslconfig 文件 (在Windows用户目录下)
cat > /mnt/c/Users/$USER/.wslconfig << 'EOF'
[wsl2]
memory=8GB
processors=4
swap=2GB
localhostForwarding=true
EOF

# 重启WSL
wsl --shutdown
```

#### Docker优化
```json
// Docker Desktop设置
{
  "memory": 8192,
  "cpus": 4,
  "swap": 2048,
  "experimental": true
}
```

## 🔧 故障排除

### 常见问题

#### 1. WSL2网络问题
```bash
# 重置网络
wsl --shutdown
# 重新启动WSL
```

#### 2. ROS2连接问题
```bash
# 检查ROS_DOMAIN_ID
echo $ROS_DOMAIN_ID

# 检查防火墙设置
sudo ufw status
```

#### 3. Unity连接问题
- 检查IP地址配置
- 验证端口是否开放
- 查看Unity控制台错误信息

### 日志收集
```bash
# ROS2日志
ros2 log info

# Unity日志位置
# %USERPROFILE%\AppData\LocalLow\<CompanyName>\<ProductName>\Player.log
```

## 📈 监控和维护

### 系统监控
```bash
# 资源使用情况
htop
docker stats

# 网络连接
netstat -tulpn | grep :10000
```

### 定期维护
```bash
# 更新ROS2包
sudo apt update && sudo apt upgrade

# 清理Docker
docker system prune -f
```

## 🎯 下一步

部署完成后，您可以：

1. **运行示例项目** - 测试基本功能
2. **自定义机器人配置** - 添加您的机器人URDF
3. **开发自定义功能** - 基于现有框架扩展
4. **性能调优** - 根据实际需求优化参数

---

**部署指南版本**: v1.0  
**最后更新**: 2025年9月30日  
**适用系统**: Windows 11 + Ubuntu 24.04 LTS + ROS2 Jazzy