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系统 (可选但推荐)

# 检查Windows更新
Get-WindowsUpdate
# 或通过设置 -> Windows更新进行升级

1.2 安装Ubuntu 24.04 LTS

# 安装Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

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

1.3 配置WSL2

# 设置WSL2为默认版本
wsl --set-default-version 2

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

第二阶段：ROS2 Jazzy安装

2.1 进入Ubuntu环境

# 启动Ubuntu 24.04
wsl -d Ubuntu-24.04

2.2 系统更新和基础依赖

# 更新系统包
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

# 添加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 安装项目依赖

# 安装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环境

# 添加到bashrc
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc

# 验证安装
ros2 --version

第三阶段：Unity环境配置

3.1 安装Unity Hub和Unity Editor

1. 下载并安装 Unity Hub
2. 通过Unity Hub安装Unity 2021.3 LTS或更高版本
3. 确保安装了以下模块：
   • Windows Build Support (IL2CPP)
   • Linux Build Support (IL2CPP)

3.2 导入Unity项目

# 切换到项目目录
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镜像

# 在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镜像

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

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

第五阶段：网络配置

5.1 配置网络通信

# 在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 测试网络连通性

# 在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环境验证

# 在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. 完整系统测试

# 运行集成测试
# 在Unity中按F5或运行TestRunner组件

📊 性能优化

系统配置建议

WSL2优化

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

# 重启WSL
wsl --shutdown

Docker优化

// Docker Desktop设置
{
  "memory": 8192,
  "cpus": 4,
  "swap": 2048,
  "experimental": true
}

🔧 故障排除

常见问题

1. WSL2网络问题

# 重置网络
wsl --shutdown
# 重新启动WSL

2. ROS2连接问题

# 检查ROS_DOMAIN_ID
echo $ROS_DOMAIN_ID

# 检查防火墙设置
sudo ufw status

3. Unity连接问题

• 检查IP地址配置
• 验证端口是否开放
• 查看Unity控制台错误信息

日志收集

# ROS2日志
ros2 log info

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

📈 监控和维护

系统监控

# 资源使用情况
htop
docker stats

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

定期维护

# 更新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