Add a Robot

How a new robot enters this stack. Copy an existing description package and the launch/xacro patterns already in the repo. There is no hardware:=mock. Launch files and config names are those listed in that package’s README.

Source of truth

1. ROS description package

Public brand trees live as submodules under robot_descriptions (common, manipulator/ARX, manipulator/Dobot, …). In open-deploy-ws the same tree is src/robot-descriptions/ after ./init_repo.sh. Do not recursive-init.

Copy a real package. Acone (from that repo) looks like:

arx_acone_description/
├── CMakeLists.txt
├── package.xml
├── README.md
├── xacro/
│   ├── robot.xacro
│   ├── arm_mount.xacro
│   ├── component.xacro
│   └── ros2_control/          # hardware plugin branches
├── config/
│   ├── ocs2/                  # task .info (controller loads these, not a separate ocs2_arm_config.yaml)
│   └── ros2_control/          # optional {hardware}.yaml overlay
└── meshes/

Launch key is robot:=<key> where the package is {key}_description (robot_common_launch). demo.launch.py default is cr5.

hardware:= values that exist in Acone xacro / common launch: mock_components (default), gz, isaac, real. There is no hardware:=mock. Plugins: ros2_control in This Stack. Use the plugin class from that robot’s xacro/ros2_control/*.xacro or an existing vendor HI README (arx-ros2-control for ARX hardware:=real).

OCS2 files the controller actually loads: {robot_pkg}/config/ocs2/<info>.info (ocs2_arm README). Planning URDF comes from the same xacro via robot_common_launch, not a static urdf/*.urdf.

EEF / FT / TCP: type / left_type / right_type (not gripper:=).

Chassis / swerve / collider:=simple (feature/agilex skill)

On feature/agilex only, the skills index currently lists one skill: split-chassis-glb (SKILL.md). Canonical example in that skill: rokae_inex_description.

What it does (overview; follow the skill for the full procedure):

  • Split one assembled chassis GLB into chassis / steer / wheel meshes with joint-ready origins

  • Write swerve xacro (reuse one steer + one wheel at fl fr rl rr; right modules yaw 180°, no mesh reflect)

  • Add collider:=simple boxes from glTF-node AABBs (not raw accessor min/max)

How to add more skills under .cursor/skills/: the same skills README (folder .cursor/skills/). The index currently lists only split-chassis-glb.

Package layout / submodules: README on main for the shared submodule table (common, manipulator/ARX, …). Use the README on feature/agilex when the robot is newer AgileX or Rokae INEX. That branch currently tables (paths as written there):

Kind

Path on feature/agilex

Mobile manipulator

manipulator/AgileX/cobot_magic_v1_description (Cobot Magic V1)

Mobile manipulator

manipulator/AgileX/split_aloha_description (Split Aloha)

Mobile manipulator

manipulator/AgileX/cobot_magic_v2_description (Cobot Magic V2)

Manipulator

manipulator/AgileX/piper_description (Piper; also on main)

Manipulator

manipulator/AgileX/nero_description (Nero)

Manipulator

manipulator/AgileX/open_nero_description (Open Nero)

Wheel humanoid

humanoid/Rokae/rokae_inex_description (INEX; split-chassis-glb canonical)

main still lists AgileX Aloha at manipulator/AgileX/agilex_aloha_description and does not have the .cursor/skills directory.

Taku (Dyna / DVT1) is also in-tree on feature/agilex at humanoid/Dyna/taku_description. Visualize with robot_common_launch humanoid.launch.py robot:=taku. Control is split_body.launch.py / full_body.launch.py with robot:=taku (package README §3.1 / §3.2) — not demo.launch.py. Public mock is split_body.launch.py; full_body.launch.py needs the private ocs2_wbc_controller submodule. It is not a row in that branch’s README brand tables. There is no lean open-deploy-ws Taku branch — open-deploy-ws Setup.

2. Wire it into a deploy workspace

In open-deploy-ws:

  1. ./init_repo.sh so nested modules match submodules_visibility.conf.

  2. If you added a new nested submodule: add the Git submodule on the parent, then one pipe line parent_dir|relative_path|public or private — Submodules Visibility.

  3. colcon build --symlink-install. Lean branches (arx-lift2s, panthera-ht): prefer ./quick_start.sh (it sources install/setup.bash after a successful build). On main, after colcon, source install/setup.bash in the launch terminal (standard ROS overlay; no extra env script).

robot-descriptions-arx README also shows adding the brand repo as src/robot-descriptions-arx or git submodule update --init manipulator/ARX under the umbrella. Prefer the deploy-ws init script when you are in open-deploy-ws.

Controllers already in arms_ros2_control: ocs2_arm_controller demo.launch.py / split_body.launch.py / full_body.launch.py, plus basic_joint_controller. Example from the Acone README (after the workspace overlay):

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

Launch files and hardware-interface class names come from the package you copied and its vendor HI README.

3. Isaac USD (FaSim-Isaac skill)

Isaac import is still the FaSim-Isaac skill isaac-urdf-usda-ocs2 (not the description-side split-chassis-glb skill):

What that skill covers (overview; follow the skill for the full procedure):

  1. Split / expand URDF or xacro; record mount poses.

  2. Isaac 5: Import URDF → USD. Isaac 6: Asset Transformer → USDA.

  3. Robot Assembler (child → parent; one articulation root).

  4. Root variantSets + local adapter payloads (payloads/Physics/{none,physics,physx,mujoco}.usda, …).

  5. PhysX vs Newton/MuJoCo layers kept separate; host side topic_based_ros2_control + hardware:=isaac.

Asset layout: robot_usds README (robots/manipulators/…, robots/mobile_manipulator/…). FaSim-Isaac checkout: ./init.sh (submodules + optional Isaac ROS 2 workspace), then ./run.sh. See Isaac Sim.