Ros2UnityWeb

本仓库提供了一个Unity WebGL插件，用于实现Unity Web端与ROS（机器人操作系统）之间的通信。 由于浏览器环境限制，无法直接使用TCP协议，本插件通过roslibjs库并借助Unity Plugin实现WebSocket通信。

项目背景

在Unity Web端开发中，ROS-TCP-Connector无法直接使用，因为：

• 浏览器无法直接建立TCP连接
• Web环境只支持WebSocket协议
• 需要通过JavaScript桥接层实现通信

本插件解决了Unity WebGL应用与ROS系统之间的通信问题，适用于机器人可视化、遥操作、轨迹规划等应用场景。

目录结构

Ros2UnityWeb/
├── Assert/
│   ├── Plugins/
│   │   ├── JS.jslib              # Unity Native Plugin JavaScript桥接层
│   │   └── roslib.min.js         # roslibjs库（用于浏览器端ROS通信）
│   ├── RosConnector.cs           # 主连接器类，管理ROS连接和话题订阅
│   ├── RosPublisher.cs           # 消息发布类，用于向ROS发送消息
│   ├── RosPublisherObject.cs     # 发布消息类型定义
│   ├── SubscriberObject.cs       # ROS消息类型定义和序列化
│   ├── SubscribeUavInfo.cs       # UAV（无人机）状态订阅处理器
│   ├── SubscribeUgvInfo.cs       # UGV（无人车）状态订阅处理器
│   ├── SubscribeMesh.cs          # 网格数据订阅处理器
│   ├── SubscribePanel.cs         # 面板更新订阅处理器
│   ├── SubscribePerformanceInfo.cs # 性能指标订阅处理器
└── Readme.md                 # 本文档

核心功能

1. ROS连接管理

• 支持WebSocket协议连接ROS服务端
• 自动重连机制和连接状态反馈
• 连接参数动态配置（IP地址和端口）

2. 话题订阅

• 无人机（UAV）数据：里程计、GPS定位、飞行速度、飞控状态等
• 无人车（UGV）数据：车辆位姿、GPS定位、速度信息、车辆状态等
• 可视化数据：三维网格模型、点云数据、轨迹路径等
• 性能指标：路径规划性能统计信息

3. 消息发布

• 车辆位姿发布（car_pose）
• 目标点发布（target_point）
• 导航目标发布（goal_point）
• 控制指令发布（uav_run、ugv_run）
• 地图更新触发（updateMap）

4. 服务调用

• 支持ROS服务注册和调用
• 事件处理服务示例

使用方法

环境要求

• Unity 2020.3或更高版本
• 支持WebGL构建的Unity项目
• ROS系统（ melodic/noetic/humble/jazzy 版本）

ROS服务端部署

本插件使用rosbridge_suite提供WebSocket服务器。rosbridge_suite是一个ROS元包，包含rosbridge_library和rosbridge_server，实现了rosbridge v2协议。

ROS 1环境部署（ melodic/noetic ）

# 安装rosbridge_suite
sudo apt-get install ros-<distro>-rosbridge-suite

# 启动rosbridge服务器（默认端口9090）
roslaunch rosbridge_server rosbridge_websocket.launch

ROS 2环境部署（ humble/jazzy ）

# 安装rosbridge_suite
sudo apt-get install ros-<distro>-rosbridge-suite

# 启动rosbridge服务器（默认端口9090）
ros2 launch rosbridge2_server rosbridge_websocket_launch.py

配置文件说明

rosbridge_server支持多种传输协议，默认使用WebSocket。主要配置参数：

• port：WebSocket端口（默认9090）
• address：绑定地址（默认0.0.0.0）
• SSL：是否启用加密连接

验证部署

启动rosbridge_server后，可以通过以下方式验证：

1. 在浏览器中测试： 打开rosbridge提供的Web测试页面（如果有）或使用JavaScript控制台连接测试。

2. 使用wscat工具测试：

   # 安装wscat
   npm install -g wscat
   
   # 连接到rosbridge服务器
   wscat -c ws://localhost:9090

3. 查看话题列表： 在另一个终端运行：

   # ROS 1
   rostopic list
   
   # ROS 2
   ros2 topic list

如果Unity应用能够成功连接并获取话题数据，说明部署成功。

安装步骤

1. 将文件放置到Unity项目中

将所有文件复制到Unity项目的Assets目录下：

• Plugins/ 整个目录放入 Assets/Plugins/
• 其余 .cs 文件放入 Assets/ 或 Assets/Scripts/ 目录

2. 配置RosConnector组件

在Unity场景中创建空GameObject，添加 RosConnector 组件，并配置以下字段：

• connectStatus：连接状态显示的UI Text组件
• iPInputField：IP地址输入框（TMP_InputField）
• portInputField：端口输入框（TMP_InputField）
• dialogPrefab：连接对话框预制体
• ipDialogInputField：对话框中的IP地址输入框
• portDialogInputField：对话框中的端口输入框
• dialogStatusText：对话框中的状态显示文本
• dialogBtn：对话框中的连接按钮

3. 配置RosPublisher组件

添加 RosPublisher 组件到场景中的GameObject：

• ugv：无人车模型的Transform组件
• flag：目标旗帜GameObject
• connectStatus：连接状态文本（引用RosConnector的connectStatus）
• rosConnector：RosConnector组件引用

4. 运行并测试

• 构建Unity项目为WebGL格式
• 启动ROS服务端（确保WebSocket支持已启用）
• 在浏览器中打开构建后的页面
• 输入ROS服务端IP地址和端口，点击连接
• 观察连接状态，确认成功后即可开始数据交互

消息类型支持

本插件支持以下ROS消息类型：

消息类型	说明
nav_msgs/Odometry	里程计消息，包含位姿和速度信息
sensor_msgs/NavSatFix	GPS定位消息，包含经纬度高度
mavros_msgs/VFR_HUD	飞行数据消息，空速地速高度等
mavros_msgs/State	飞控状态消息，连接状态、解锁状态等
std_msgs/Float32	浮点数消息，用于速度等数据
std_msgs/Bool	布尔值消息，用于开关控制
std_msgs/Int32	整数消息，用于触发信号
nav_msgs/Path	路径消息，用于轨迹显示
voxblox_msgs/Mesh	网格消息，用于三维重建显示
sensor_msgs/PointCloud2	点云消息，用于障碍物可视化
voxblox_msgs/plannerPerformance	规划性能消息，记录算法表现

扩展开发

添加新的话题订阅

1. 在 RosConnector.cs 中添加初始化方法：

public void InitSubscribeCustomTopic()
{
    const string className = "SubscribeCustomClass";
    SubscribeROSTopic("topic_name", "message_type", className, "CallbackFunction");
}

2. 创建对应的订阅处理类，继承自 MonoBehaviour，实现回调方法：

public class SubscribeCustomClass : MonoBehaviour
{
    public void CallbackFunction(string messageJson)
    {
        // 解析JSON消息并更新Unity场景
    }
}

3. 在 ConnectStatus 回调中调用初始化方法

添加新的消息类型

在 SubscriberObject.cs 中添加消息类型定义：

[Serializable]
public class CustomMsg
{
    public Header header;
    public float data;
    // 添加其他字段...
}

添加新的发布话题

1. 在 JS.jslib 中添加发布者注册函数（如果需要自定义处理）
2. 在 RosConnector.cs 的 InitRegisterPublisher 中注册新话题
3. 在 RosPublisher.cs 的 Update 方法中添加发布逻辑

工作原理

JavaScript桥接层

JS.jslib 是Unity的Native Plugin，负责JavaScript和C#之间的通信：

• 加载roslibjs库到浏览器环境
• 建立WebSocket连接到ROS服务端
• 将C#调用转换为JavaScript执行
• 通过 SendMessage 将ROS消息回调到C#

消息流

Unity C# ←──SendMessage──→ JavaScript(roslibjs) ←──WebSocket──→ ROS
     ↓                              ↑
Publish调用               Subscribe回调

坐标系转换

插件中实现了Unity坐标系与ROS坐标系的转换：

• Unity坐标系：X向右，Y向上，Z向前
• ROS坐标系：X向前，Y向左，Z向上

在 RosPublisher.cs 中进行了坐标轴映射：

carPose.pose.pose.position.x = ugv.position.z;
carPose.pose.pose.position.y = ugv.position.x;
carPose.pose.pose.position.z = -0.1;

注意事项

1. WebSocket支持：确保ROS服务端已启用WebSocket功能（通常使用 rosbridge_server 包）
2. 跨域问题：在生产环境中可能需要配置CORS以允许WebGL应用连接
3. 性能考虑：大量点云或网格数据可能影响Web端性能，建议进行适当的LOD处理
4. 内存管理：大型消息处理时注意内存分配和释放，避免内存泄漏

相关依赖

• roslibjs - 浏览器端ROS客户端库