仿真机器人MetaEngine

准备环境

执行如下命令，确认ROS2环境：

source /opt/ros/${ROS_DISTRO}/setup.bash 
python3 -c "import rclpy; print('rclpy OK')"

MetaEngine（O3DE）仿真侧准备

1. 在O3DE工程中启用ROS2 Gem（Project Manager > Gems > ROS2）。
2. 导入机器人URDF：使用ROS2RobotImporter导入机器人模型，生成物理模型与关节。
3. 为机器人挂载：
   • ROS2RobotControl/控制器 > 发布/joint_states、暴露关节命令话题。
   • ROS2CameraSensor（手/头/外置）> 发布sensor_msgs/Image。
   • 夹爪等执行器 > Float64MultiArray 命令话题。
4. 运行仿真并验证话题可用：

ros2 topic list 
ros2 topic echo /joint_states --once
ros2 topic hz /joint_states 

记录下仿真侧实际发布的话题名与消息类型，这是后续配置subscriptions / command_publishers的依据。

编写R2C客户端通信配置

config/client_config.yaml（Zenoh通信）：

project_id: "test-tenant"      # 与云端一致
device_id: "sim-ur5e-001"      # 设备标识
client_id: "sim-edge-001"
endpoints: []                  # 留空自动发现，或填 Router 地址
mode: "peer"                   # peer 或 client
protocol: "zenoh"

编写仿真机器人硬件配置

hardware.type: "ros2"，配置主体为r2c_ur5e.yaml（详见四、配置文件逐项详解）。按仿真侧实际话题名/消息类型调整。

启动并验证

source /opt/ros/${ROS_DISTRO}/setup.bash
# 保险起见先用 dry_run 验证链路，再真正驱动
python -m r2c_sdk.cloudroboclient \
  --client-config config/client_config.yaml \
  --robot-config r2c_ur5e.yaml \
  --log-level INFO

启动后应看到日志：

• Connecting ROS2 hardware adapter / ROS2 adapter connected (subscriptions=.., publishers=..)。
• 观测正常发布、被云端接收并回推Actions。
• init_joints将机械臂/夹爪摆到初始位。

runtime：运行/控制循环

hardware：ROS2硬件适配器

hardware:
  type: "ros2"
  config:
    node_name: "r2c_ur5e_ros"     # ROS2 节点名（与其他节点不重名）
    spin_timeout_sec: 0.05        # spin_once 超时（秒）
    auto_spin: True               # 是否自动启动 spin 线程

hardware.config.init_joints：启动自摆位

连接成功、发布器就绪后，主动下发初始位（把机械臂/夹爪摆到安全初位）。_publish_init_joints 在 connect() 末尾调用。

init_joints:
  enabled: true            # 是否启用
  delay_sec: 3.0           # 连接后延迟多少秒再下发
  entries:
    - publisher: arm       # 对应 command_publishers 的一个发布器
      message:             # 直接构造该发布器类型消息
        data: [0.0, -1.9373155, 1.204277, -0.9075712, 4.694936, -0.0872665]
    - publisher: hand
      message:
        data: [0.0, 0.0]

hardware.config.subscriptions：观测订阅（上行）

每个订阅项把一个ROS2 Topic拉进streams。一个典型订阅项如下所示：

joint_states:                     # 订阅流名称（任意起名，用于 store_as）
  topic: /joint_states
  msg_type: sensor_msgs.msg.JointState
  qos: 10
  max_update_hz: 10               # 限频，避免高频洪泛
  store_as: joint_states          # 在 streams 中的键名
  include_fields: ["name", "position", "velocity", "effort"]
  field_aliases:
    name: names                    # 字段重命名 name > names
  transforms:                      # 订阅级转换链（可选）
    - select_joints_by_name:
        names: [... 8 个关节名 ...]

相机订阅示例（UR5e）：

head:
  topic: /head_camera/camera_image_color
  msg_type: sensor_msgs.msg.Image
  qos: 10
  store_as: head
  store_raw_message: true      # 保留 Image 对象，供下游 ros_image_to_jpeg 使用

hardware.config.command_publishers：命令发布（下行）

每个发布项把一个R2C命令映射到ROS2Topic：

command_publishers:
  arm:                             # 发布器名称（供 target/init_joints 引用）
    topic: "/arm_position_controller/commands"
    msg_type: std_msgs.msg.Float64MultiArray
    qos: 10
  hand:
    topic: "/hand_position_controller/commands"
    msg_type: std_msgs.msg.Float64MultiArray
    qos: 10
default_command_publisher: arm     # 未显式指定时的默认发布器
action_targets:                    # 语义 target > 发布器名
  arm: arm
  hand: hand

下行通道：

Topic 发布器（推荐，低延迟）：command_publishers。

translator：数据翻译层

type: "configurable"，由device_to_r2c（ROS2 > R2C）与r2c_to_device（R2C > ROS2）两组映射构成。

device_to_r2c： 组R2C观测

关节位置：

- target_key: "joint_states.names"            # 目标标准字段
  default: ["shoulder_pan_joint", "shoulder_lift_joint", "elbow_joint",
            "wrist_1_joint", "wrist_2_joint", "wrist_3_joint", "gripper"]
- target_key: "joint_states.position"         # 来自订阅 streams
  source: streams.joint_states.position
  transforms:
    - array_to_list
    - slice: { start: 0, end: 6 }             # 前 6 维 = 机械臂
- target_key: "joint_states.position"         # 第 7 维 = 夹爪行程
  target_index: 6
  source: streams.joint_states.position
  transforms:
    - array_to_list
    - slice: { start: 6, end: 8 }             # 夹爪两指
    - my_gripper_fingers_to_stroke            # 两指求和 > 行程（米）

相机图像：

- target_key: "images.color.head"
  source_path: "streams.head"                 # 原始 Image 对象（store_raw_message）
  transforms: ros_image_to_jpeg               # 编码为 JPEG 字节
- target_key: "images.color.external"
  source_path: "streams.external"
  transforms: ros_image_to_jpeg

device_to_r2c映射项的字段：

target_key与task一起构成最终Observations（云端策略所需字段详见R2C观测模型）。

r2c_to_device：生成ROS2命令

机械臂（前6维 > arm发布器）：

- target: "commands_by_publisher.arm.data"    # 写入哪个发布器的哪个字段
  source: "joint_states.position"
  use_assign_dotted: true                     # 用点号路径赋值
  required: true
  transforms:
    - slice: { start: 0, end: 6 }             # 6 维机械臂
    - list_to_ros_float64_multi_array         # 组装 Float64MultiArray

夹爪（第7维行程 > 展开两指 > hand发布器）：

- target: "commands_by_publisher.hand.data"
  source: "joint_states.position"
  source_index: 6
  use_assign_dotted: true
  required: true
  transforms:
    - my_gripper_stroke_to_fingers            # 行程 > [S/2, S/2] 两指
    - list_to_ros_float64_multi_array

r2c_to_device映射项字段：

最终翻译器输出commands_by_publisher（或commands_by_service/commands）给adapter.send_action()，由适配器按发布器名路由并发布到对应 Topic。

自定义转换器：r2c_to_device里可引用自定义转换器（如SO101的so101_gripper_value_to_joint）。参考Transformer使用指导。