通信协议（Communication Protocol）

如在 快速开始 中通过 client 所介绍的，平台采用 基于 http 的通信机制，用于在仿真控制器和推理模型之间交换结构化数据。 你可以基于 client 的示例扩展，集成自己的模型控制器以进行基准评测。

发送数据（Outgoing Data）

在每个仿真时间步（timestep），系统会通过 http 发送以下结构化数据。 请注意，实际获得的数据中可能包含额外字段——这些字段已被弃用，将在未来版本中移除。

data = {
    "camera_data": camera_data, // 字典类型，摄像头观测数据
    "instruction": instruction, // 字符串，任务指令
    "joint_position_state": joint_position_state, // np.ndarray，当前关节位置
    "ee_pose_state": ee_pose_state, // list[np.ndarray] 或 list[list[np.ndarray]]，末端执行器位姿
    "timestep": step, // 整数，当前仿真步
    "reset": reset, // 布尔值，是否需要重置环境或模型
}

字段定义

字段名	类型	描述
camera_data	dict	由机器人安装的摄像头采集的数据。
instruction	string	给智能体的自然语言命令或任务说明。
joint_position_state	np.ndarray（形状 (9,)）	机械臂的当前关节角状态（例如 Franka）。
ee_pose_state	list[np.ndarray] 或 list[list[np.ndarray]]	机械臂末端执行器（EE）的位姿状态。对于单臂机器人，为两个数组：平移（3D）与姿态（4D，四元数，标量在前）。对于双臂机器人，为左臂与右臂的嵌套列表，每个包含平移与姿态。
timestep	int	当前 rollout 的仿真步索引。
reset	bool	是否重置环境或模型。

模型或控制器接收到这些数据后，需要返回一个结构化的 动作字典（action message）。

摄像头数据结构（Camera Data Structure）

每个摄像头在 camera_data 字典中对应的条目包含以下字段：

字段名	类型	描述
p	np.ndarray（形状 (3,)）	摄像头在世界坐标系中的位置。
q	np.ndarray（形状 (4,)）	摄像头在世界坐标系中的姿态（四元数，标量在前）。
rgb	np.ndarray	RGB 图像数组，分辨率由 configs/cameras/ 中的配置决定。
depth	np.ndarray	深度图像数组。
intrinsics_matrix	np.ndarray（形状 (3, 3)）	摄像头内参矩阵。

---

返回动作（Returned Action）

模型需返回一个 动作字典（action dictionary），可采用 关节控制模式（joint position） 或 末端执行器控制模式（end-effector pose）。

关节控制模式（Joint Position Mode）

当前支持 增量关节角（delta joint position） 输入。 若模型输出 绝对关节角，需转换为增量形式。

你需要在返回的内容中包含 control_type 字段：

{
    "control_type": "joint_position",
    "action": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
}

各机器人支持格式：

• Franka + Panda Hand

  • 数组长度：9
  • 前 7 维：机械臂关节位置增量
  • 后 2 维：夹爪控制
  • [0.04, 0.04] = 完全张开，[0.0, 0.0] = 完全闭合

• Franka + RoboTiq Hand

  • 数组长度：13
  • 前 7 维：机械臂关节位置增量
  • 后 6 维：夹爪控制
  • [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] = 完全张开
  • [0.7853, 0.7853, -0.7853, -0.7853, -0.7853, -0.7853] = 完全闭合

• Aloha

  • 数组长度：16
  • 0:6 与 8:14：左右臂关节位置增量
  • 6:8 与 14:16：夹爪控制
  • [0.05, 0.05] = 完全张开，[0.0, 0.0] = 完全闭合

末端执行器控制模式（End-Effector Pose Mode）

当前支持 增量末端执行器位姿（delta ee pose）。 若模型输出 绝对位姿，需相应转换为增量形式。

你需要在返回的内容中包含 control_type 字段：

{
    "control_type": "ee_pose",
    "action": [
        [0.001, 0.001, 0.001],
        [1.0, 0.0, 0.0, 0.0],
        [0.04, 0.04],
    ]
}

各机器人支持格式：

• Franka + Panda Hand

  • 长度为 3 的 Tuple：

    • 3D 平移向量
    • 4D 四元数姿态（标量在前）
    • 2D 夹爪控制（[0.04, 0.04] = 张开，[0.0, 0.0] = 闭合）

• Franka + RoboTiq Hand

  • 长度为 3 的 Tuple：

    • 3D 平移向量
    • 4D 四元数姿态（标量在前）
    • 6D 夹爪控制（[0.0,...] = 张开，[0.7853,...] = 闭合）

• Aloha

  • 长度为 2 的 Tuple，分别对应左右臂：

    • 每个臂的 Tuple 包含：

      • 3D 平移向量
      • 4D 四元数姿态（标量在前）
      • 2D 夹爪控制（[0.05, 0.05] = 张开，[0.0, 0.0] = 闭合）