Newcomer Learning Path¶

This guide provides a structured day-by-day approach to learning the FiveAges Sim ecosystem. Follow it sequentially to build understanding from fundamentals to advanced topics.

Overview¶

Stage	Goal	Time Estimate
Day 0	Map the stack	1-2 hours reading
Day 1	First motion in sim	2-4 hours
Day 2	Switch robots	1-2 hours
Day 3	Gazebo / Isaac	2-4 hours
Day 4	Python interface	2-3 hours
Day 5	Teleoperation	2-4 hours
Day 6	Real hardware	Varies
Day 7+	Add a robot	Project-dependent

Real Hardware for External Users

ARX Lift 2S is the full-body ARX (方舟无限) mobile manipulator (including chassis). Acone / AC One is dual-arm, not Lift 2S. HighTorque Panthera HT (高擎) is a dual-arm manipulator. Prefer the dedicated how-to pages. You don’t need internal access for those open-deploy-ws branches.

Day 0: Map the Stack¶

Goal: Understand the ecosystem structure and choose your entry path.

Tasks:

Read this Overview section
Study the Architecture diagram
Decide: Public path (open-deploy-ws) or Internal path (fa-deploy-ws)
Review the Repository Map

Outcome: You can explain the five layers and know which workspace to start with.

Day 1: First Motion in Simulation¶

Goal: Install the environment, then run a robot demo (hardware default mock_components).

Tasks:

Install Environment — Ubuntu 24.04, ROS 2 Jazzy + rosdep. On a bare host: add the ROS apt source, then ros-jazzy-desktop / ros-dev-tools (fishros is optional). Workspace entry is ./init_repo.sh, then source install/setup.bash.

Clone open-deploy-ws and run the official init script:

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

Build the workspace:
```
colcon build --symlink-install
```
Launch the demo (defaults: robot:=cr5, hardware:=mock_components — omit both; there is no hardware:=mock):
```
source install/setup.bash
ros2 launch ocs2_arm_controller demo.launch.py
```

Primary sources: open-deploy-ws, arms_ros2_control

Outcome: RViz opens with the OCS2 demo; FSM starts in HOLD. See Quick Demo.

Day 2: Switch Robots¶

Goal: Change the robot model and understand the description system.

Tasks:

Prefer ./init_repo.sh so nested modules under src/robot-descriptions/ match submodules_visibility.conf (do not recursive-init).
Rebuild the packages you need, then source install/setup.bash.
Launch with the new robot (omit hardware:= to keep mock_components):
```
ros2 launch ocs2_arm_controller demo.launch.py robot:=arx_acone
```
arx_acone is Acone (dual-arm), not Lift 2S. Full-body ARX Lift 2S uses the arx-lift2s branch scripts — see ARX Lift 2S.

Primary sources: robot_descriptions, brand-specific READMEs

Outcome: You can switch between Dobot CR5, Acone (dual-arm), Galbot, etc.

Day 3: Gazebo and Isaac Simulation¶

Goal: Run physics simulation instead of mock hardware.

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 pairs NVIDIA Isaac Sim high-fidelity simulation with the same ROS 2 运控 stack as the real robot, so motion matches hardware while the sim supplies ground truth. Assets: FaSim-Isaac (one-click USD + scene pull), robot_usds.

FaSim-Isaac scripts

Use FaSim-Isaac ./init.sh then ./run.sh. Default Isaac path is ISAACSIM_DIR (~/isaacsim); override in config/fa_sim.local.conf. Version for the optional ROS 2 workspace comes from the init menu (fallback list in config/fa_sim.conf), not a hardcoded minor version in these docs.

Install NVIDIA Isaac Sim (default directory ~/isaacsim, or set ISAACSIM_DIR).

Clone and initialize FaSim-Isaac:

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

Start Isaac (./run.sh menu: PhysX / Newton / Headless Streaming):
```
./run.sh
```

In another terminal, launch the ROS 2 side with Isaac hardware:

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

Primary sources: FaSim-Isaac, robot_usds

Outcome: Physics-based simulation with Gazebo, or FaSim (Isaac + ROS 2 运控, matching real-robot motion plus ground truth).

Day 4: Python Interface¶

Goal: Control the robot programmatically.

Tasks:

Install 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

Write a simple script:

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()

Primary sources: fa-py-libraries, ros2_robot_interface

Outcome: You can script robot motions in Python.

Day 5: Teleoperation¶

Goal: Control the robot via VR or isomorphic teleop.

VR Teleoperation¶

Supported headsets: Pico Enterprise (recommended; USB 网络共享, Enterprise App), Pico consumer (different App), and Meta Quest. Backends: WebXR (./run.sh vr) or XRoboToolkit (./run.sh vr-xrt).

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

Pico Enterprise vs consumer

Pico Enterprise and Pico consumer are different SKUs: Enterprise supports USB 网络共享 and uses a different App. Install the App that matches the headset edition.

Isomorphic Teleop (HighTorque Panthera HT)¶

Master–slave isomorphic teleop (同构遥操作). On the panthera-ht branch, real-robot teleop is ./teleop_start.sh — see HighTorque Panthera HT. Mock (package 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

Primary sources: VR pose publisher, drag_teleop_controller

Outcome: Real-time control via VR headset or master–slave isomorphic teleop.

Day 6: Real Hardware¶

Goal: Deploy to physical robots.

Public Path (ARX Lift 2S, Acone, HighTorque Panthera HT)¶

Use the matching branch README and ./quick_start.sh. Acone / AC One is dual-arm; Lift 2S is the full-body platform.

ARX Lift 2S — full-body including chassis: git clone -b arx-lift2s … then ./init_repo.sh / ./quick_start.sh
Acone / AC One — dual-arm; same arx-lift2s workspace, pick ACone in quick_start for co-debug
HighTorque Panthera HT — dual-arm: git clone -b panthera-ht … then ./init_repo.sh / ./quick_start.sh

Internal Path (FA Robots)¶

Internal Access Required

FA robots (W2, W2R, S2, S2R, dual-arm CCS) require access to fa-deploy-ws. Contact your team lead for repository access and hardware allocation.

Tasks:

Clone fa-deploy-ws and run the init / quick-start scripts named in that repository’s README (not public). Flags and robot IDs are documented only there.
Follow fa-deploy-ws Setup.

Safety: Verify in mock_components (or that workspace’s documented sim path) before hardware:=real.

Day 7+: Add a Robot¶

Goal: Integrate a new robot into the ecosystem.

Tasks:

Create a description package with URDF/xacro
Add ros2_control hardware-interface YAML
Configure OCS2 controller parameters
Test progression: mock → simulation → real hardware

See the Developer Guide for detailed instructions.

Optional: Synthetic data (Isaac)¶

Goal: Understand the Isaac datagen path (not Gazebo): USD scene → ROS2RobotInterface → composer task_queue → LeRobot dataset on disk.

Follow Synthetic Data. Documented composer/lerobot branches are feature/dex-grasp-generator and feature/sim-grasp-datagen. Stop at recording/export; skip training.

After the beginner path¶

Continue by role in More applications: field commissioning (现场调试), classical algorithm (传统方案算法工程师), VLA collect / train / deploy (VLA 采训推), simulation (仿真工程师).

Tips for Success¶

Don’t skip mock mode — Always verify behavior in mock before simulation or real hardware
Read the warnings — The stack logs helpful messages about configuration issues
Use lean branches — open-deploy-ws offers dobot-cr5, arx-lift2s, and panthera-ht
Ask questions — File issues on the relevant repository for bugs or unclear documentation