Skip to content

DexForce/EmbodiChain / .agents/skills/add-robot

add-robot

Verified

Use when adding a new robot to EmbodiChain — scaffolds a RobotCfg subclass (single-file or package layout) with the _build_defaults hook, build_pk_serial_chain, registration, docs page, and test stub.

FileKindSize
SKILL.mdskill md10.5 KB
agents/openai.yamlconfig88 B
---
name: add-robot
description: Use when adding a new robot to EmbodiChain — scaffolds a RobotCfg subclass (single-file or package layout) with the _build_defaults hook, build_pk_serial_chain, registration, docs page, and test stub.
---

# Add Robot

## When to Use

- Adding a new robot to EmbodiChain.
- Adding a variant to an existing robot (a new version / arm kind / hand brand).
- Scaffolding a `RobotCfg` subclass.

## The RobotCfg Protocol

Every robot config subclasses `RobotCfg` and overrides two hooks:

- `_build_defaults(self, init_dict=None)` — read variant fields from `init_dict`,
  set them on `self`, then populate `urdf_cfg` / `control_parts` / `solver_cfg` /
  `joint_drive_props` / `attrs`.
- `build_pk_serial_chain(self, device=...)` — return `{control_part: pk.SerialChain}`,
  reading the PK URDF from a single `_pk_urdf_path` source.

`from_dict` is a 3-line template (do not reimplement):

```python
cfg = cls()
cfg._build_defaults(init_dict)
return merge_robot_cfg(cfg, init_dict)
```

`to_dict` / `to_string` / `save_to_file` are inherited from `RobotCfg` and round-trip.

## Two Layouts

Concrete configs live in the `embodichain/extensions/robots/` import package, bundled
with the core distribution/version. Generic robot runtime, configuration,
solvers, and composition stay in `embodichain/lab/sim/`.

| Layout | When | Files |
|--------|------|-------|
| Single-file | Model using a vendor-shared archive | `<vendor>/<model>.py` |
| Package | Model-owned assets or versions/calibrations | `<vendor>/<model>/cfg.py`, `assets.py`, optional specifications, lazy `__init__.py` |

## The Contract (read first)

A cfg's `_build_defaults` must populate:

- `uid` (str)
- `urdf_cfg` (URDFCfg) or `fpath`
- `control_parts` (Dict[str, List[str]]; joint names support regex)
- `solver_cfg` (Dict[str, SolverCfg]; keys match `control_parts`)
- `joint_drive_props` (JointDrivePropertiesCfg)
- `attrs` (RigidBodyPhysicsCfg)

Use `arm` / `eef` for default single-arm control groups and `left_arm`,
`right_arm`, `left_eef`, `right_eef` for dual-arm defaults. Add an EEF group
only when the robot has controllable end-effector joints. These names are a
convention: user-defined names remain valid, without automatic aliases or a
reserved-name validator. Keep asset component, link and joint identifiers intact.

`build_pk_serial_chain` must read from `_pk_urdf_path` (a property for
constant-path robots, a method for variant-dependent paths). The PK chain's DOF
must match the matching `control_parts` entry (the test stub asserts this).

## Steps

1. **Pick a vendor/model owner** and a layout from the table above. Keep vendor
   and model initializers lazy. Asset-only imports must not load configurations.
2. **Create the cfg file(s).** Subclass `RobotCfg`. Declare variant fields (enums)
   if using the package layout.
3. **Implement `_build_defaults(self, init_dict=None)`.** Set variant fields from
   `init_dict`, then populate the Contract fields. Single-file template:

   ```python
   def _build_defaults(self, init_dict=None):
       init_dict = init_dict or {}
       self.uid = "MyRobot"
       self.urdf_cfg = URDFCfg(components=[...])
       self.control_parts = {"arm": ["JOINT[1-6]"]}
       self.solver_cfg = {"arm": OPWSolverCfg(end_link_name="link6", root_link_name="base_link")}
       self.joint_drive_props = JointDrivePropertiesCfg(stiffness={"JOINT[1-6]": 1e4})
   ```

   Variant-aware template (reads version / arm_kind):

   ```python
   def _build_defaults(self, init_dict=None):
       init_dict = init_dict or {}
       self.version = MyRobotVersion(init_dict.get("version", "v1"))
       self.arm_kind = MyRobotArmKind(init_dict.get("arm_kind", "default"))
       ...  # then urdf_cfg / control_parts / solver_cfg / joint_drive_props / attrs
   ```

4. **Implement `build_pk_serial_chain`** reading from `_pk_urdf_path`:

   ```python
   @property
   def _pk_urdf_path(self) -> str:
       return get_data_path("MyRobot/arm.urdf")

   def build_pk_serial_chain(self, device=torch.device("cpu"), **kwargs):
       chain = create_pk_serial_chain(
           urdf_path=self._pk_urdf_path, device=device,
           end_link_name="link6", root_link_name="base_link",
       )
       return {"arm": chain}
   ```

5. **Keep `from_dict` as the 3-line template** — do not reimplement it.
6. **Add `__all__` and register** the class in
   `embodichain/extensions/robots/_catalog.py`, then add its lazy export to
   `embodichain/extensions/robots/__init__.py` (`_EXPORTS` and `__all__`):

   ```python
   # Catalog entry; importing the catalog must not import the robot module.
   "MyRobot": {"class_path": "embodichain.extensions.robots.my_vendor.my_robot:MyRobotCfg"}
   ```

   The main wheel already advertises this catalog through `embodichain.robots`.
   Gym, workspace CLI, and dual-arm composition use its shared resolver.
   Variant defaults belong in the catalog. Concrete robots use only the
   canonical package; no core compatibility module or CLI class map is needed.
   Supply optional control metadata when known: `dof` counts unique independent
   default control joints, excluding mimic followers; `control_parts` records
   raw per-part counts. `mimic_joints` maps followers to leaders, and
   `control_part_mimics` records follower membership by group. Overlapping groups
   must not inflate DOF. Declare `supports_dual_arm` only for a compatible default
   single-arm URDF/control-part/solver contract. Families may declare `variants`
   with control profiles and a `default_variant`; flat preset IDs use `variant_of`.
   Add explicit `vendor`, `morphology` and `arm_count` metadata when known;
   unknown fields stay `None`. Variant classification inherits parent values
   unless explicitly overridden. Keep the catalog free of runtime imports.
   Put model-owned asset classes in `assets.py` (shared archives at vendor level)
   and register their unchanged asset IDs, class paths and categories in
   `_asset_catalog.py`. The `embodichain.assets` entry point connects them to
   the core resolver and data CLI; listing must not construct datasets.

7. **Add documentation:** create
   `docs/source/resources/robot/<vendor>/<model>.md`, matching the source
   namespace. Include the model in its vendor's `index.rst` and the Supported
   Robots overview. Add an index for a new vendor and link it from
   `docs/source/resources/robot/index.rst`. Community projects with an unknown
   manufacturer use their project namespace; keep generic composition separate.
8. **Add a test stub** with a `__main__` smoke test + the DOF drift guard. Use
   `/add-test` for full test scaffolding; the guard snippet is:

   ```python
   chains = cfg.build_pk_serial_chain()
   for part, chain in chains.items():
       assert len(chain.get_joint_parameter_names()) == len(cfg.control_parts[part])
   ```

9. **Verify:** `preview-asset` CLI + `RobotCfg.from_dict(cfg.to_dict())` round-trip.

## Parallel-jaw hands

Use `ParallelJawGripperCfg` for a separately controllable two-finger model.
Place its pure `get_gripper_defaults(variant=None)` beside its model assets and
reuse it in full Cfg construction; register its `description_path` in the
existing robot catalog. The pure provider must not import Lab, read assets or
initialize geometry/backends. Physical geometry/contact frames and complete
native commands and `grasp_generators` support declarations belong to that
provider and the flat Cfg fields. Do not introduce a second physical model Cfg.
GraspKit receives scalar opening bounds and numerical geometry; simulation
asset adaptation belongs to `lab/sim/utility/gripper_geometry.py`. Provide explicit left/right variants where source hands
differ. Do not fill unknown hardware with a generic grasp model.

Embodiment bindings reuse mounted or existing hand definitions and generate
effective solver TCPs. Preserve all native mimic commands and use assembler
name mapping. Check standalone preview/open-close, config round trips and pure
provider imports. Full physics validation is separate from metadata resolution.

## Reusable embodiment handoff

`RobotCfg` owns simulation construction, control parts, solvers, and physical
properties, plus optional mounted camera configurations in `sensors`.
Use robot-local parent link names and stable sensor UIDs. Standalone simulation
creates these cameras only with `enable_sensor=True`; Gym overrides that
switch with its environment acquisition setting. An explicit sensor list
replaces defaults and `sensors: []` clears them. Keep independent cameras,
task declarations and Task Program skill profiles outside the robot class.

If the user also wants the robot selectable from task deployments, invoke
`$add-embodiment-component` after the robot config passes its own tests. That
component selects the robot, declares additional independent sensors, and maps stable
logical resources/endpoints/capabilities/commands into `skill_profile`.
Do not copy those semantic declarations into the robot class.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| `all` instead of `__all__` | Use `__all__` — lowercase `all` breaks `import *`. |
| `solver_cfg` set twice | Set it once in `_build_defaults` only. |
| PK URDF drifts from sim URDF | Route PK through `_pk_urdf_path`; keep the DOF guard. |
| Reimplementing `from_dict` | Keep the 3-line template; put logic in `_build_defaults`. |
| `root_link_name` as a tuple | It must be a `str`. |
| Calling a nonexistent `validate` | Don't call methods that don't exist. |

## Quick Reference

| Parameter | Type | Description |
|-----------|------|-------------|
| `uid` | str | Unique robot identifier |
| `urdf_cfg` | URDFCfg | URDF file and components |
| `control_parts` | Dict[str, List[str]] | Joint groups for control |
| `solver_cfg` | Dict[str, SolverCfg] | IK solver configurations |
| `joint_drive_props` | JointDrivePropertiesCfg | Joint drive, limits, friction, and armature |
| `attrs` | RigidBodyPhysicsCfg | Rigid-body physics attributes |
| variant fields | enum / str / bool | Optional subclass fields |
| `_pk_urdf_path` | property or method → str | URDF for the FK/IK serial chain |

**File locations:**

- Config: `embodichain/extensions/robots/<vendor>/<model>.py` or `<vendor>/<model>/`
- Catalog / lazy exports: `embodichain/extensions/robots/_catalog.py`, `embodichain/extensions/robots/__init__.py`
- Shared resolver: `embodichain/robot_registry.py`
- Docs: `docs/source/resources/robot/<vendor>/<model>.md` and the owning index
- Tests: `tests/sim/objects/test_robot_cfg.py`
- Base class: `embodichain/lab/sim/cfg/robot.py` (`RobotCfg`)
- Guide: `docs/source/guides/add_robot.rst` · Tutorial: `docs/source/tutorial/add_robot.rst`
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall