新手学习路径

本指南按天提供结构化学习路径，帮助你掌握 FiveAges Sim 生态系统。请按顺序学习，从基础概念过渡到进阶主题。

概述

阶段

目标

预估时间

第 0 天

梳理技术栈

阅读 1–2 小时

第 1 天

仿真中的首次运动

2-4 小时

第 2 天

切换机器人

1-2 小时

第 3 天

Gazebo / Isaac

2-4 小时

第 4 天

Python 接口

2-3 小时

第 5 天

遥操作

2-4 小时

第 6 天

真实硬件

因情况而异

第 7 天及以后

添加机器人

视项目而定

外部用户的真实硬件

方舟无限 Lift 2S 是全身移动操作臂（含底盘）。Acone / AC One 是 双臂，不是 Lift 2S。高擎 Panthera HT 是双臂操作臂。请优先看对应操作指南。使用这些 open-deploy-ws 分支不需要内部权限。

第 0 天：梳理技术栈

目标： 理解生态系统结构，并选择你的入口路径。

任务：

  1. 阅读本概述章节

  2. 学习架构图

  3. 做出选择：公开路径（open-deploy-ws）或内部路径（fa-deploy-ws）

  4. 查阅仓库地图

预期结果： 你能说明五个层级，并知道该从哪个工作空间开始。

第 1 天：仿真中的首次运动

目标： 先安装环境，再运行机器人演示（hardware 默认为 mock_components）。

任务：

  1. 环境安装 — Ubuntu 24.04、ROS 2 Jazzy + rosdep。裸机上：先加 ROS apt 源，再装 ros-jazzy-desktop / ros-dev-tools（fishros 可选）。工作区入口是 ./init_repo.sh，然后 source install/setup.bash。

  2. 克隆 open-deploy-ws 并运行官方初始化脚本：

    git clone https://github.com/fiveages-sim/open-deploy-ws.git
cd open-deploy-ws
./init_repo.sh

  3. 编译工作空间：

    colcon build --symlink-install

  4. 启动演示（默认：robot:=cr5、hardware:=mock_components — 两者都可省略；没有 hardware:=mock）：

    source install/setup.bash
ros2 launch ocs2_arm_controller demo.launch.py

主要来源： open-deploy-ws、arms_ros2_control

结果： RViz 打开 OCS2 演示；FSM 从 HOLD 开始。见 快速演示。

第 2 天：切换机器人

目标： 更换机器人模型，并理解描述系统。

任务：

  1. 优先用 ./init_repo.sh，让 src/robot-descriptions/ 下的嵌套模块与 submodules_visibility.conf 一致（不要递归 init）。

  2. 重建所需软件包，然后 source install/setup.bash。

  3. 用新机器人启动（省略 hardware:= 以保持 mock_components）：

    ros2 launch ocs2_arm_controller demo.launch.py robot:=arx_acone

    arx_acone 是 Acone（双臂），不是 Lift 2S。全身方舟无限 Lift 2S 使用 arx-lift2s 分支脚本 — 见 方舟无限 Lift 2S。

主要来源： robot_descriptions、各品牌 README

预期结果： 你可以在 Dobot CR5、Acone（双臂）、Galbot 等机型之间切换。

第 3 天：Gazebo 与 Isaac 仿真

目标： 运行物理仿真，而不是 mock 硬件。

Gazebo Harmonic

# Install Gazebo packages (if not already)
sudo apt install ros-jazzy-gz-*

# Launch with Gazebo
ros2 launch ocs2_arm_controller demo.launch.py hardware:=gz

Isaac Sim（FaSim）

FaSim 把 NVIDIA Isaac Sim 高保真仿真与真机同一套 ROS 2 运控叠在一起：运动能力对齐硬件，仿真再提供真值。资产：FaSim-Isaac（一键拉取 USD 与场景）、robot_usds。

FaSim-Isaac 脚本

使用 FaSim-Isaac 的 ./init.sh，再运行 ./run.sh。默认 Isaac 路径是 ISAACSIM_DIR（~/isaacsim）；在 config/fa_sim.local.conf 中覆盖。可选 ROS 2 工作空间的版本来自 init 菜单（回退列表见 config/fa_sim.conf），不要在文档里写死某个次版本号。

  1. 安装 NVIDIA Isaac Sim（默认目录 ~/isaacsim，或设置 ISAACSIM_DIR）。

  2. 克隆并初始化 FaSim-Isaac：

    git clone git@github.com:fiveages-sim/FaSim-Isaac.git
cd FaSim-Isaac
./init.sh

  3. 启动 Isaac（./run.sh 菜单：PhysX / Newton / Headless Streaming）：

    ./run.sh

  4. 在另一个终端中，以 Isaac 硬件启动 ROS 2 侧：

    ros2 launch ocs2_arm_controller demo.launch.py hardware:=isaac

主要来源： FaSim-Isaac、robot_usds

预期结果： 基于物理的仿真，可用 Gazebo，或 FaSim（Isaac + ROS 2 运控，运动对齐真机并带仿真真值）。

第 4 天：Python 接口

目标： 以编程方式控制机器人。

任务：

  1. 安装 fa-py-libraries：

    cd ~/
git clone https://github.com/fiveages-sim/fa-py-libraries.git
cd fa-py-libraries
./init.sh all    # Python 3.12 env; installs ros2_robot_interface and related submodules

  2. 编写一个简单脚本：

    from ros2_robot_interface import ROS2RobotInterface, ROS2RobotInterfaceConfig

interface = ROS2RobotInterface(ROS2RobotInterfaceConfig())
interface.connect()
joint_state = interface.get_joint_state()
pose = interface.left_arm_handler.get_pose()

主要来源： fa-py-libraries、ros2_robot_interface

预期结果： 你可以用 Python 编写机器人运动脚本。

第 5 天: 遥操作

目标： 通过 VR 或同构遥操作控制机器人。

VR 遥操作

支持的头显： Pico 企业版（推荐；USB 网络共享、企业版 App）、Pico 消费版（不同 App）和 Meta Quest。后端：WebXR（./run.sh vr）或 XRoboToolkit（./run.sh vr-xrt）。

cd fa-py-libraries
./run.sh vr

Pico 企业版与消费版

Pico 企业版 与 Pico 消费版 是不同 SKU：企业版支持 USB 网络共享，并使用不同的 App。不要为两者安装同一个 App。

同构遥操作（高擎 Panthera HT）

主从 同构遥操作。在 panthera-ht 分支上，真机遥操作是 ./teleop_start.sh — 见 高擎 Panthera HT。模拟（软件包 README）：

ros2 launch drag_teleop_controller drag_teleop_controller.launch.py \
  role:=master hardware:=mock_components
ros2 launch drag_teleop_controller drag_teleop_controller.launch.py \
  role:=slave hardware:=mock_components

主要来源： VR 位姿发布器、drag_teleop_controller

预期结果： 通过 VR 头显或主从同构遥操作进行实时控制。

第 6 天：真实硬件

目标： 部署到实体机器人。

公开路径（方舟无限 Lift 2S、Acone、高擎 Panthera HT）

使用对应 分支 README 和 ./quick_start.sh。Acone / AC One 是 双臂；Lift 2S 是全身平台。

  • 方舟无限 Lift 2S — 全身含底盘：git clone -b arx-lift2s … 然后 ./init_repo.sh / ./quick_start.sh

  • Acone / AC One — 双臂；同一 arx-lift2s 工作空间，在 quick_start 中选 ACone 做联调

  • 高擎 Panthera HT — 双臂：git clone -b panthera-ht … 然后 ./init_repo.sh / ./quick_start.sh

内部路径（FA 机器人）

需要内部访问权限

FA 机器人（W2、W2R、S2、S2R、双臂 CCS）需要访问 fa-deploy-ws。请联系团队负责人申请仓库权限并分配硬件。

任务：

  1. 克隆 fa-deploy-ws，并运行该仓库 README（非公开）中写明的 init / quick-start 脚本。参数和机器人 ID 只写在那里。

  2. 见 fa-deploy-ws 配置。

安全： 先在 mock_components（或该工作区文档中的仿真路径）验证，再使用 hardware:=real。

第 7 天及以后：添加机器人

目标： 将新机器人集成到生态系统中。

任务：

  1. 用 URDF/xacro 创建描述包

  2. 添加 ros2_control 驱动层 YAML

  3. 配置 OCS2 控制器参数

  4. 测试进阶顺序：mock → 仿真 → 真实硬件

详细说明请参阅开发者指南。

可选：合成数据（Isaac）

目标： 弄清 Isaac 数据采集路径（不是 Gazebo）：USD 场景 → ROS2RobotInterface → composer task_queue → 磁盘上的 LeRobot 数据集。

见 合成数据。文档对应的 composer/lerobot 分支是 feature/dex-grasp-generator 与 feature/sim-grasp-datagen。停在录制/导出；跳过训练。

新手路径之后

按 角色 继续看更多应用：现场调试、传统方案算法工程师、VLA 采训推、仿真工程师。

实用建议

  1. 不要跳过 mock 模式 — 在进入仿真或真实硬件之前，务必先在 mock 中验证行为

  2. 阅读警告信息 — 技术栈会记录有助于排查配置问题的日志

  3. 使用精简分支 — open-deploy-ws 提供 dobot-cr5、arx-lift2s 和 panthera-ht

  4. 提出问题 — 遇到缺陷或文档不清时，请在相应仓库提交 issue