架构¶

本页说明 FiveAges Sim 生态系统的分层架构，以及各组件之间的依赖关系。

层级图¶

        flowchart TB
  subgraph entry [Entry Workspaces]
    ODW["open-deploy-ws<br/>public quick-start"]
    FDW["fa-deploy-ws<br/>private FA robots"]
    DCW["dexcap_teleop_ws<br/>DexCap teleop"]
    FAI["FaSim-Isaac<br/>Isaac asset + jazzy_ws"]
  end

  subgraph L1 [L1 Descriptions]
    RD["robot_descriptions<br/>public umbrella"]
    RDC["robot-descriptions-common"]
    FA["humanoid/FiveAges/*<br/>private gitlinks"]
    BRAND["brand desc:<br/>dobot / arx / galbot / ht / quadruped<br/>tianji / rokae / ubtech / …"]
  end

  subgraph L2 [L2 Hardware Interfaces]
    HI["*-ros2-control<br/>public + private HIs<br/>nested under arms_ros2_control"]
  end

  subgraph L3 [L3 Controllers + MPC]
    ARMS["arms_ros2_control<br/>ocs2_arm / teleop / gripper"]
    WBC["ocs2-wbc-controller<br/>private"]
    OH["ocs2-humanoid / ocs2_wheel_humanoid<br/>private"]
    OCS2["legubiao/ocs2_ros2<br/>deb ros-jazzy-ocs2"]
  end

  subgraph L4 [L4 Simulation]
    GZ["Gazebo Harmonic<br/>via arms launches"]
    USD["robot_usds + gitmodules<br/>Gen1/2/3 · Galbot · Ubtech"]
    ENV["FaSim: fiveages-env-usds<br/>+ fa-project-usd sibling"]
  end

  subgraph L5 [L5 Teleop / Apps / Python]
    PY["fa-py-libraries<br/>interface · viser · vr_pose_publisher"]
    TEL["isomorphic / DexCap / wuji glove / vive / teleop-joint-mapper"]
    APP["lerobot_ros2 · robot_action_composer · HUG"]
  end

  ODW --> ARMS
  ODW --> RD
  ODW --> OCS2
  FDW --> FA
  FDW --> ARMS
  FDW --> OCS2
  RD --> RDC
  RD --> BRAND
  RD --> FA
  ARMS --> HI
  ARMS --> WBC
  ARMS --> OH
  ARMS --> OCS2
  FAI --> USD
  FAI --> ENV
  ARMS --> GZ
  ARMS --> USD
  PY --> ARMS
  TEL --> ARMS
  APP --> PY
  DCW --> TEL

层级说明¶

入口工作空间¶

以下是编译并运行该技术栈的起点：

工作空间	用途	可见性
`open-deploy-ws`	公开快速入门，含 mock/仿真演示	公开
`fa-deploy-ws`	面向 FA 机器人的内部工作空间	私有
`dexcap_teleop_ws`	DexCap 遥操作部署	私有
`FaSim-Isaac`	Isaac Sim 资源及可选的 jazzy_ws	公开

L1：描述¶

机器人描述定义 URDF/xacro 模型、可视化网格以及 ros2_control 硬件配置：

robot_descriptions — 聚合各品牌专用软件包的公开总仓
robot-descriptions-common — 共用夹爪、灵巧手、传感器与 launch 工具
humanoid/FiveAges — 该伞形仓下的私有 gitlink 包（不是独立的 robot-descriptions-fiveages 仓库）。路径：FiveAges 机器人描述
品牌软件包 — 按厂商划分的描述（dobot、arx、galbot 等）

L2：驱动层¶

与实体或仿真硬件通信的 ROS 2 驱动层（ros2_control Hardware Interface）：

公开：arx-ros2-control、dobot-cr-ros2-control、unitree-ros2-control 等。
私有：rokae-ros2-control、eyou-ros2-control、wuji-ros2-control 等。

控制器 vs 驱动层 vs 分体/全身：术语对照、本栈中的 ros2_control、驱动层、分体控制 vs 全身控制。

L3：控制器 + MPC¶

运动规划与控制算法：

arms_ros2_control — Basic Joint Controller、OCS2 Arm Controller、Adaptive Gripper Controller、遥操作命令节点
ocs2_ros2 — OCS2 MPC 库（GitHub Release .deb：ros-jazzy-ocs2）
OCS2 WBC Controller（ocs2-wbc-controller）— 面向轮臂人形的全身控制（私有）
ocs2-humanoid — 轮臂人形专用库（私有）

L4: 仿真¶

仿真后端与资源：

Gazebo Harmonic — 通过 arms_ros2_control 中的 launch 文件集成
FaSim — Isaac Sim 高保真 + 与真机同一套 ROS 2 运控，外加仿真真值。一键工作空间：FaSim-Isaac
robot_usds — 用于 Isaac Sim 的 USD 资源（Gen1/2/3、Galbot、Ubtech）
FaSim 环境 — 通过 fiveages-env-usds 与 fa-project-usd 提供的场景资源

L5：遥操作 / 应用 / Python¶

高层应用与遥操作：

fa-py-libraries — Python 工具集，含 ros2_robot_interface、viser、vr_pose_publisher
遥操作系统 — 同构遥操作、DexCap、Wuji 手套、Vive tracker
应用 — lerobot_ros2、robot_action_composer、HUG

依赖经验法则¶

Descriptions (URDF + ros2_control YAML)
    ↓
Hardware Interface plugins
    ↓
Controllers (arm MPC / WBC)
    ↓
Simulation backends OR Real hardware
    ↓
Teleop / Apps (same topic/FSM contracts)

添加新机器人时：

创建或扩展描述包
确保驱动层插件已存在
配置控制器参数
Test in mock → simulation → real hardware