isaac-sim-ros2-bridge

Isaac Sim ROS 2 桥接

用途

使用 OmniGraph 桥接节点从 Isaac Sim 发布和订阅 ROS 2 主题，包括 Nav2 集成和多机器人命名空间配置。

限制

• 目标版本为 Isaac Sim 6 / Kit 110，除非某个章节另有说明。
• 无法替代 NVIDIA 官方文档来处理不受支持的边缘情况。

故障排查

错误 / 症状	原因	解决方案
没有 ROS 主题	桥接图未运行，或域设置错误	按下 Play；确保 ROS_DOMAIN_ID 设置一致
缺少 humble 库	启动进程前未设置 LD_LIBRARY_PATH	修复父 Shell 环境（加载 ROS 环境或使用默认启动器），然后重新启动——不要对正在运行的进程进行热修补
命名空间主题不匹配	坐标系或命名空间发生偏移	确保 OmniGraph 命名空间与 Nav2 配置一致

可用脚本

脚本	用途	参数
scripts/multi_robot_namespacing.py	车队演示：按机器人创建由播放状态控制的桥接图（odom、TF、scan、joint states、cmd_vel）+ 共享时钟	--robots NAME:PRIM_PATH [...] --usd_path --lidar_suffix --headless --test
scripts/prerequisites.sh	先决条件	按脚本标头中的位置参数传入（见脚本）

运行脚本

在提供技能执行辅助函数的 Agent 运行环境中，使用 run_script() 调用辅助函数：

run_script("scripts/multi_robot_namespacing.py", args=["--help"])

在已构建的 Isaac Sim 目录中，从 _build/*/release 使用 ./python.sh（Linux）或 python.bat（Windows）运行同一文件；如果 Shell 辅助脚本不需要模拟器，也可以直接执行。

架构

Isaac Sim 6.0 中的 ROS 2 Bridge 基于扩展（isaacsim.ros2.bridge）并构建在 OmniGraph 动作图之上。只有按下播放按钮后，发布器、订阅器和服务才会激活。

扩展栈

扩展	用途
isaacsim.ros2.core	后端库、设置和轻量级 ROS 2 库
isaacsim.ros2.nodes	用于主题 / 服务的 OmniGraph 节点
isaacsim.ros2.bridge	顶层桥接扩展（启用所有功能）
isaacsim.ros2.tf_viewer	TF 树可视化
isaacsim.ros2.urdf	按照 ROS 2 规范导入 URDF
isaacsim.ros2.examples	示例场景（Nova Carter、iw_hub、hospital、office）
isaacsim.ros2.sim_control	通过 ROS 2 服务控制模拟

先决条件

默认工作流无需手动设置。启动 isaacsim.ros2.core 时，它会读取 ROS_DISTRO；如果未设置，则回退到扩展内打包的轻量级 ROS 2 库，并设置 internal_lib_fallback=True。isaac-sim.sh / python.sh 启动器会自动加载 setup_ros_env.sh，在进程启动前导出 ROS_DISTRO、RMW_IMPLEMENTATION 和打包的 ROS 库路径。

只有当你需要打包库未提供的消息类型或 RMW 实现时，才在父 Shell 中加载系统 ROS 2 安装（/opt/ros/<distro>/setup.bash）。在 Linux 上，任何 LD_LIBRARY_PATH 更改都必须在启动 Isaac Sim 前完成，因为动态链接器会在进程启动时读取这些设置；进程运行后更改 LD_LIBRARY_PATH，不会追溯修复 ROS 库解析问题。

传入 --no-ros-env 可绕过自动加载；在这种情况下，父 Shell 必须提供可用的 ROS 2 环境，包括任何必需的 LD_LIBRARY_PATH 条目。

ROS 环境决策规则

用户反馈 ROS 2 Bridge 启动或符号解析问题时，请按以下优先顺序处理：

1. **默认路径：**通过 isaac-sim.sh / python.sh 启动，并由 setup_ros_env.sh 提供捆绑的 ROS 环境。
2. **系统 ROS 路径：**如果需要自定义消息包或其他 RMW 实现，请在启动前，于父 shell 中 source /opt/ros/<distro>/setup.bash（以及任何 overlay 工作区）。
3. **不要热修补 LD_LIBRARY_PATH：**如果 Isaac Sim 已在错误的加载器环境下运行，请从正确 source 过的 shell 重新启动，而不是尝试在进程运行时修复。

请将“在当前 Isaac Sim 进程内导出 LD_LIBRARY_PATH 并重试”视为反模式；正确的处理方式始终是“修复父 shell，然后重新启动”。

[代码：scripts/prerequisites.sh]

OmniGraph ROS 2 节点

所有 ROS 2 通信均通过 OmniGraph 动作图配置。主要节点类型：

发布者

节点类型	话题类型	用例
ROS2PublishClock	rosgraph_msgs/Clock	仿真时间同步
ROS2PublishJointState	sensor_msgs/JointState	关节位置/速度
ROS2PublishOdometry	nav_msgs/Odometry	机器人里程计
ROS2PublishLaserScan	sensor_msgs/LaserScan	激光雷达数据
ROS2PublishImage	sensor_msgs/Image	相机 RGB/深度
ROS2PublishCameraInfo	sensor_msgs/CameraInfo	相机内参
ROS2PublishTransformTree	tf2_msgs/TFMessage	TF 坐标系
ROS2PublishSemanticLabels	std_msgs/String	语义分割标签
ROS2PublishPointCloud	sensor_msgs/PointCloud2	激光雷达/深度点云
ROS2PublishImu	sensor_msgs/Imu	IMU 数据

订阅者

节点类型	话题类型	用例
ROS2SubscribeJointState	sensor_msgs/JointState	关节命令
ROS2SubscribeTwist	geometry_msgs/Twist	速度命令（cmd_vel）
ROS2SubscribeAckermannDrive	ackermann_msgs/AckermannDriveStamped	Ackermann 转向命令

通用 / 其他

节点类型	用例
ROS2Publisher / ROS2Subscriber	用于任意消息类型的通用发布/订阅
ROS2PublishBoundingBox2D / ROS2PublishBoundingBox3D	将标注器输出发送到 ROS 2
ROS2PublishRgbd	发布组合 RGB+D 数据
ROS2PublishSemanticSegmentation / ROS2PublishInstanceSegmentation	分割输出

设置 ROS 2 Bridge 图（Python）

此仓库提供了一个规范示例，演示如何使用 og.Controller.edit(...) 构建 ROS 2 发布动作图，包括将 OnPlaybackTick 连接到发布者节点、将 IsaacReadSimulationTime 接入 ROS2PublishClock，以及在同一脚本中创建匹配的 rclpy 订阅者。

• 参考示例：source/standalone_examples/api/isaacsim.ros2.bridge/clock.py

扩展此模式时，请使用当前的 isaacsim.ros2.bridge.ROS2Publish* / ROS2Subscribe* 节点名称（旧版 omni.isaac.ros2_bridge.* 命名空间已弃用，且无法在 Kit 110 中加载）。

**迁移：**有关逐节点重命名对照表，请参阅 迁移 ROS 2 OmniGraph 节点；有关更全面的 omni.isaac.* → isaacsim.* 映射，请参阅重命名扩展。

多机器人命名空间

在多机器人场景中，每个机器人都需要自己的 ROS 2 主题命名空间。仓库中的多机器人场景（医院/办公室中的 Carter）演示了手动加载和逐机器人设置模式；此技能中的 scripts/multi_robot_namespacing.py 提供了完整的车队桥接工厂。

• 场景参考：source/standalone_examples/api/isaacsim.ros2.bridge/carter_multiple_robot_navigation.py
• 车队图工厂：scripts/multi_robot_namespacing.py

由 Play 控制激活

所有桥接图都使用 OnPlaybackTick 作为执行触发器。这意味着：

1. 在阶段处于停止状态时创建图（不会发布主题）。
2. 调用 app_utils.play()（或在 GUI 中按下 Play）后，OnPlaybackTick 会在每帧触发，并驱动所有已连接的发布者/订阅者。
3. 停止播放会立即停止所有主题的活动。

这是车队演示的正确模式——可以先启动 Nav2 节点并等待主题出现，车队则会在 Play 启动时开始同步发布。

API 用法

from multi_robot_namespacing import setup_fleet, create_ros2_bridge_for_robot

# Full fleet setup (clock + per-robot graphs)
setup_fleet([
    ("carter1", "/World/Carter1"),
    ("carter2", "/World/Carter2"),
    ("carter3", "/World/Carter3"),
])

# Or create individual robot graphs
create_ros2_bridge_for_robot(
    robot_name="carter1",
    robot_prim_path="/World/Carter1",
    lidar_prim_path="/World/Carter1/Lidar",
    publish_joint_states=True,
)

逐机器人发布的主题（Play 后）

主题	消息类型	坐标系
/<name>/odom	nav_msgs/Odometry	<name>/odom → <name>/base_link
/<name>/scan	sensor_msgs/LaserScan	<name>/lidar_link
/<name>/joint_states	sensor_msgs/JointState	—
/tf	tf2_msgs/TFMessage	机器人子树
/clock	rosgraph_msgs/Clock	共享，一个图

订阅的主题

主题	消息类型	用途
/<name>/cmd_vel	geometry_msgs/Twist	来自 Nav2 的速度命令

Nav2 集成

要将 Nav2 与 Isaac Sim ROS 2 Bridge 配合使用：

1. 发布所需主题：/odom、/tf、/scan（或 /pointcloud）、/joint_states
2. 订阅：/cmd_vel
3. 在 /clock 上发布仿真时钟，并在 Nav2 参数中设置 use_sim_time: true

已知问题（Isaac Sim 6.0 rc.22）

• ROS 2 bridge 仅在 timeline.play() 时激活——停止状态下不会发布主题
• 相机发布者要求相机 prim 附带渲染产品
• 如果机器人 prim 路径在运行时发生变化，TF 树可能变得不一致
• 捆绑的 ROS 2 库可能缺少自定义主题所需的消息类型——启动 Isaac Sim 前，请在父 shell 中加载系统 ROS 2 安装

示例场景

预构建的示例 USD 文件（来自 isaacsim.ros2.examples）：

场景	路径	描述
Nova Carter 导航	/Isaac/Samples/ROS2/Scenario/carter_warehouse_navigation.usd	单机器人 Nav2
Nova Carter 关节状态	/Isaac/Samples/ROS2/Scenario/carter_warehouse_navigation_joint_states.usd	含关节状态发布
iw_hub 导航	/Isaac/Samples/ROS2/Scenario/iw_hub_warehouse_navigation.usd	iw_hub AMR
多机器人导航	ROS2/Navigation/Multiple Robots 类别	车队 Nav2
医院场景	/Isaac/Samples/ROS2/Scenario/hospital_scene.usd	Perceptor + 医院
办公室场景	/Isaac/Samples/ROS2/Scenario/office_scene.usd	办公室导航