# Add New Robot This guide explains how to add a new robot to SPIDER, covering both dexterous hands and humanoid robots. ## Overview Adding a new robot involves: 1. Converting/preparing robot model (URDF/MJCF) 2. Configuring default settings 3. Setting up collision geometry 4. Adding trace and tracking sites 5. Configuring actuators 6. Testing the integration ## Prerequisites - Robot URDF or MJCF model - Basic understanding of MuJoCo XML format - Robot specifications (joint limits, actuator parameters) ## Add Dexterous Hand ### Step 1: Convert URDF to MJCF (Optional) If you have a URDF file, convert it to MuJoCo XML: ```xml ``` Then use MuJoCo's compiler: ```bash # Using MuJoCo command-line tool python -c "import mujoco; mujoco.MjModel.from_xml_path('robot.urdf').save('robot.xml')" ``` ### Step 2: Add Default Settings Add default simulation parameters to your XML: ```xml ``` **Parameter explanations:** - `density="800"`: Material density (kg/m³) - `kp="300"`: Position controller stiffness - `dampratio="1.0"`: Critical damping - `armature="1.0"`: Joint inertia ### Step 3: Add Assets Include textures and materials: ```xml ``` ### Step 4: Clean Up Joint Properties Remove incompatible joint properties from the URDF-converted file: ```xml ``` ### Step 5: Rename Bodies and Geoms Change mesh names to avoid conflicts (especially for bimanual setups): ```xml ``` ::: tip Naming Convention - Bodies: `{side}_{finger}_{part}` (e.g., `left_index_proximal`) - Visual geoms: `{side}_{name}_visual` - Collision geoms: `collision_hand_{side}_{finger}_{part}` ::: ### Step 6: Add Collision Geometry Create simplified collision geometry using primitives: For each finger, in different parts, the collision index start from 0 and increase in each new body. ```xml ``` **Naming convention for collision geoms:** ``` collision_hand_{side}_{finger}_{part} ``` Where: - `side`: `left` or `right` - `finger`: `thumb`, `index`, `middle`, `ring`, `pinky`, `palm` - `part`: `0`, `1`, `2`, `3`, ... (from tip to base) **Collision geom guidelines:** - Use primitives (`box`, `sphere`, `cylinder`, `capsule`) instead of meshes - Set `group="3"` for collision geoms - Set `rgba="0 1 0 1"` (green) for visibility - Keep collision geoms simple for performance ### Step 7: Add Trace Sites Add trace sites for fingertip visualization: ```xml ``` **Naming convention:** `trace_hand_{side}_{finger}_tip` ### Step 8: Add IK Tracking Sites Add tracking sites for end-effector control: ```xml ``` **Required sites:** - `{side}_palm`: Palm center with proper orientation - `{side}_thumb_tip`, `{side}_index_tip`, `{side}_middle_tip` - `{side}_ring_tip`, `{side}_pinky_tip` **Palm site orientation:** - Z-axis: pointing forward (finger direction) - X-axis: pointing down (toward ground) ![Base Definition](/figs/base_def.png) Optional: Add contact tracking sites for contact tracking. ```xml ``` ### Step 9: Add Actuators Define position actuators for all joints: ```xml ``` **Important notes:** - Base DOFs use higher `kp` (e.g., 1000) for stability - Finger joints inherit `kp` from `` section - **Actuator order must match joint order** (SPIDER uses joint positions as control) ### Step 10: Example Complete Hand XML Here's a minimal example structure: ```xml ``` ## Add Humanoid Robot Humanoid robots have similar requirements but with additional considerations. ### Step 1: Performance Optimization Reduce solver iterations for faster simulation: ```xml ``` ### Step 2: Default Settings ```xml ``` ### Step 3: Add Collision Geoms for Feet Add collision spheres to feet (4 contact points per foot): ```xml ``` ### Step 4: Add Collision Geoms for Hands ```xml ``` ### Step 5: Add Trace Sites ```xml ``` ### Step 6: Add Contact Pairs Define explicit contact pairs: ```xml ``` ### Step 7: Use Position Actuators ```xml ``` ::: warning Important Actuator order must match joint order in the model definition! ::: ### Step 8: Setup Scene Add white background and tracking camera: ```xml ``` ## Testing Your Robot ### Step 1: Visualize in MuJoCo ```python import mujoco import mujoco.viewer # Load model model = mujoco.MjModel.from_xml_path('my_robot.xml') data = mujoco.MjData(model) # Launch viewer mujoco.viewer.launch(model, data) ``` Check: - [ ] Model loads without errors - [ ] All joints move freely - [ ] Collision geometry looks correct (green geoms) - [ ] Trace sites are visible - [ ] Tracking sites are positioned correctly ### Step 2: Test with SPIDER Create a simple test scene: ```bash # Test IK (for hands) uv run spider/preprocess/ik.py \ --robot-type=my_hand \ --task=test_task \ --dataset-name=test \ --data-id=0 \ --embodiment-type=right # Test physics optimization uv run examples/run_mjwp.py \ robot_type=my_hand \ task=test_task \ max_sim_steps=100 ``` ### Step 3: Verify Output Check that: - [ ] Trajectory is saved successfully - [ ] Joint positions are within limits - [ ] No collision warnings - [ ] Video renders correctly ## Common Issues ### Issue 1: Model Doesn't Load **Error:** `XML parse error` **Solutions:** - Check XML syntax - Validate with MuJoCo's `simulate` tool - Remove incompatible URDF attributes ### Issue 2: Unstable Simulation **Symptoms:** Robot falls through floor, explodes **Solutions:** ```xml