Robot description files

This page lists every file in a robot description directory, robot_description/robots/<model_id>/, with its fields, units and the rules the loaders enforce. For what a description is and how its identity is used, read Robot description and coordinate frames first.

Check every description in the repository:

python3 robot_description/tools/manifest.py --check
# manifest: rosie_1400_v3 ok, <n> files   (one line per model)

Loaders and tools#

robot_description_manifest.json#

{
  "schema": "rosie.robot-manifest.v1",
  "model_id": "rosie_1420_v1",
  "files": ["config.json", "meshes/link_1.dae", "robot.srdf", "robot.urdf", "rtcore_definition.json", "spheres.json"]
}

Rules for files, applied by DescriptionFiles:

• No empty, absolute or backslash path, no . or .. segment, no duplicates.
• The manifest cannot list itself.
• It cannot list machine_planning_calibration.json. That name belongs to the cell's own file, which is served beside the description.
• Every entry must be a regular file.

manifest.py registers robot.urdf, robot.srdf, config.json, spheres.json and rtcore_definition.json when present, plus every file in meshes/. Everything else in the directory is provenance.

Identity algorithm#

The identity is a domain-separated SHA-256 over the manifest and every registered file:

1. Build the entry list: the manifest itself, plus every file in files. Each entry is its path and the SHA-256 of its bytes.
2. Sort the entries by path (byte order).
3. Hash, in order:
   • the ASCII domain rosie.robot-description.identity.v1 followed by one 0x00 byte
   • the entry count, as a big-endian uint64
   • for each entry: the path length as a big-endian uint64, the path bytes, then the 32-byte file digest
4. Write the result as sha256: followed by 64 lowercase hex digits.

Because the manifest is an entry, removing a name from it changes the identity even if the file stays on disk.

robot.urdf and robot.srdf#

Standard URDF and SRDF, with these constraints:

• The URDF <robot name> must equal the model id.
• Every movable joint needs bounded <limit lower upper>. Revolute limits are in rad and velocity in rad/s.
• Mesh references use package://.../meshes/<file>, and each named mesh must be registered.
• The SRDF defines a manipulator group for Tesseract. On the Rosie models it also defines a home group state with every joint at 0.

config.json#

Schema rosie.robot-config.v1. Unknown fields are rejected. A description with no config.json still loads, with zero correction caps (no cell correction can be accepted).

Every joint named in planning.joints, axes and reset_pose must be a revolute joint in the URDF. Do not restate a number the URDF already holds: state only what the URDF cannot.

rtcore_definition.json#

Schema rosie.robot-definition.v1. It tells rt-core how each joint maps to a drive. The annotated template is rt-core/config/templates/robot.json, where every field has a _doc sibling with its unit, range and default.

Every numeric robot fact needs a <field>_source or <field>_unverified sibling that says where the number came from. Duplicate JSON keys and unexpected fields are rejected.

spheres.json#

The arm's collision spheres, used by the weld planner's screen. The verifier re-checks results against the exact meshes.

A URDF or mesh change that leaves provenance stale is caught by the planner's provenance test. Refit or restamp with weld_planner/v1/tools/fit_spheres.py (see Add a robot model).

machine_planning_calibration.json#

Per cell, not in the repository. Schema rosie.machine-planning-calibration.v1. A machine config pins it with robot.machine_planning_calibration{path, sha256, source}, and the compiled configuration serves it beside the description. Unknown fields are rejected.

{
  "schema": "rosie.machine-planning-calibration.v1",
  "model_id": "rosie_1420_v1",
  "limits": {
    "speed_ceiling_rad_s": 2.0,
    "joints": { "J1": { "lower_rad": -3.0, "upper_rad": 3.0, "velocity_rad_s": 1.5 } },
    "held": {}
  },
  "kinematics": { "J2": { "xyz_m": [0.0005, 0, 0], "rpy_rad": [0, 0.001, 0] } }
}

A correction composes onto the URDF joint origin as T' = T_origin · Trans(xyz) · R(rpy), where R follows URDF convention Rz(yaw)·Ry(pitch)·Rx(roll).

The empty document#

A cell with no calibration serves this exact document for its model, and planners hash it the same way:

{"schema":"rosie.machine-planning-calibration.v1","model_id":"<model_id>"}

followed by one newline (\n).

Calibration identity#

The identity is the SHA-256 of the file's exact bytes, never a re-serialisation. Planners and program headers write it sha256:<hex>. The machine config pin (robot.machine_planning_calibration.sha256) is the same digest as 64 bare lowercase hex digits.

Program header identities#

A dense program's robot_cell header block carries these fields, which OLP Load compares with the cell:

See Load refusals and Dense trajectory format.