add-robot

name	add-robot
description	Bring a custom robot into the Genie Sim RT Engine — author / fix a xacro / URDF in `genie_sim_robot_model`, prep meshes with the offline tools (`normalize_obj_names.py`, `diagnose_urdf.py`, `recompute_inertia.py`, `fix_dae_units.py`, `copy_dae_material.py`), stage assets into the AS3 layout (`robot.usda` + `payloads/Physics/{physics,physx,mujoco}.usda`) that the engine consumes, and wire the result into a `scene_*.yaml`. Trigger: When the user asks to "add a new robot", "import a robot", "support <vendor> in geniesim", names a URDF / xacro not currently in `genie_sim_robot_model/urdf/`, or wants to convert a third-party mesh pack into AS3-ready USD.
license	MPL-2.0
metadata	{"author":"genie-sim","version":"1.0"}
prerequisites	["geniesim_ros:build-workspace"]
inputs	[{"name":"urdf_path","desc":"Path to the URDF / xacro file to integrate","required":true},{"name":"robot_name","desc":"Robot name in `<vendor>_<model>[_<gripper>]` form","required":true},{"name":"mesh_dir","desc":"Directory containing the robot's meshes (for the mesh-prep tools)","required":false}]
outputs	[{"desc":"URDF passes `diagnose_urdf.py`; new `scene_flat_<robot>.yaml`; the engine stages AS3 USD layout on first launch"}]

When to Use

• User wants to run an off-tree robot on the RT Engine.
• User has a URDF / xacro that fails to import (missing inertia, unit mismatch, DAE materials lost, OBJ names colliding) and needs the offline mesh-prep tools.
• User wants to add the new robot to a scene_*.yaml and launch it via the launch-scene skill.

Do not use for:

• Tweaking an existing Genie G2 variant → just edit the relevant URDF / xacro and rebuild via build-workspace.
• Authoring a MoveIt config for the new robot → that's a separate, larger job (port SRDF + coupled_constraints.yaml).
• Adding a benchmark task that uses the new robot → run-benchmark in geniesim_benchmark/skills/.

Critical Patterns

1. Tier 1 only validates Genie G2. Reference robots (Franka, UR5, Aloha, ARX, Agilex) have correct URDFs and import cleanly, but scene yamls and physics tuning may be stale. Treat them as starting points, not certified configs.
2. AS3 layout is mandatory. The engine expects the per-robot directory robot.usda + payloads/Physics/{physics,physx,mujoco}.usda regardless of which backend is active — switching physics never rewrites the asset.
3. Fix the URDF before importing. diagnose_urdf.py catches missing inertia, zero-mass links, collision/visual mismatches, and bad OBJ name collisions — every one of these breaks the URDF→USD importer downstream.
4. Mesh names must be unique. USD's flat namespace will silently merge two meshes that share an OBJ name. normalize_obj_names.py rewrites names to be prefix-unique.
5. Mimic joints handled at runtime. Don't model gripper mimics inside the URDF — the engine bridges them via the controller layer (see 86308f040 in git history). URDF stays plain.
6. Robots live in genie_sim_robot_model, not in geniesim_assets. Meshes can move to geniesim_assets once stabilised, but URDFs + xacros stay in the ROS package.

Workflow

Step 1 — Stage the URDF / xacro

Drop the file under source/geniesim_ros/src/ros_ws/src/genie_sim_robot_model/urdf/ next to the reference robots. Name follows the convention <vendor>_<model>[_<gripper>].urdf.