Skip to content

[CONTRACT] Proposed: C9 joint units in radians (rad/s for rates); degrees only at the LeRobot adapter boundary #41

Open

Description

@BotshareAI

Status: Proposed. Nothing is accepted by this request. The software lead (panthera-momagdii) decides; the implementing draft PR stays Proposed until then.

Plan item

C9 whole-body capture / LeRobotDataset contract (follows #18); Baseline 1 AI capture (openamr-upperbody-sw #91).

Contract or interface

openamrobot-interfaces: docs/c9-lerobot-dataset-contract.md and schemas/json/c9-lerobot-dataset.schema.json (the unit of each observation.state and action dimension).

Decisions register entry

none. The units decision of 17 Nov 2026 (openamr-upperbody-sw #79) is not in decisions.yaml. Proposed follow-up: one register entry (for example DATASET-JOINT-UNITS) through the register process, owned by the software lead.

Change class

Change the meaning, units, defaults, or validity of an existing value; version bump and consumer review required.

The version question is for the software lead: the change only removes degrees outside one named adapter profile, and no recorded C9 sidecar outside that profile is known (see consumers). This request proposes keeping contract_version: 1 because the v1 shape is unchanged; a bump to 2 is the alternative.

Problem and proposed change

Current problem:

  • The decision on upperbody-sw #79 (17 Nov 2026): joint angles are radians everywhere, /joint_states, gripper commands, MoveIt, Gazebo, MuJoCo, Isaac and recorded datasets (C9).
  • C9 v1 says the direct dataset representation of the current OpenArm/LeRobot adapter profile (lerobot-v0.6.1-bi-openarm-position) uses 16 positions in degrees (LeRobot's Damiao adapter), and the schema accepts any unit string in any profile. So a C9 dataset can be in degrees or radians, and only the dimension descriptors tell which.
  • The Proposed C9 component profile (C9: proposed additive component mapping and model compatibility checks #39, mobile-lift-qpos-v1-proposed) and the Baseline 1 candidate capture profile (upperbody-sw #91) already use radians, so today two C9 representations of the same joints exist.

Proposed change:

  1. Canonical C9 units: joint positions in rad, joint velocities in rad/s, lift position in m, base velocities in m/s and rad/s. Every OpenAMRobot capture profile uses them.
  2. Degrees appear in exactly one place: the LeRobot bi-OpenArm adapter profile lerobot-v0.6.1-bi-openarm-position, for interoperability with upstream LeRobot policies and datasets. A converter that writes that profile converts at the adapter boundary, explicitly (source unit rad, target unit degree, factor 180/pi from its declared conversion table), never in a consumer.
  3. Schema: a vector feature whose profile is not lerobot-v0.6.1-bi-openarm-position rejects a dimension unit of degree, degrees, deg, deg/s or degree/s. The adapter profile keeps its degree descriptors unchanged.
  4. Fixtures: the existing valid fixture (adapter profile, degrees) stays valid; a new valid fixture with a canonical radian profile; a new invalid fixture with degrees under a non-adapter profile.

Producers and consumers

Producers:

  • openamrobot-embodied-ai oa-convert-bag (SatyaA27, branch satya/capture-conversion-benchmark, head 9643da1): writes the sidecar profile from native_profile_id or profile_id, and units from the capture profile channels. Its synthetic fixture uses the adapter profile with rad source and degree target, which stays valid. The Baseline 1 capture profile (radians, non-adapter id) is valid under the new rule.
  • MuJoCo episodes recorded with the degree-based adapter profile (named in the Baseline 1 brief; no episode writer was found in openamr-upperbody-sw #78 by this search, so the producer location needs to be named by its owner). Episodes under the adapter profile id stay valid; episodes in degrees under another profile id would need regeneration or relabelling as the adapter profile.
  • openamr-upperbody-sw #91 recorder and binding tool: radians already.

Consumers:

  • openamrobot-embodied-ai C11 training (python/oa_embodied_ai/training/dataset.py): requires degree for 16-channel data ("C9 adapter profile requires degree-valued channels"); docs/c11/state_action_mapping.md states the adapter uses degrees. Both stay correct for the adapter profile; a 16-channel radian dataset under a canonical profile is a C11 decision (accept it, or convert at the adapter boundary). Tests: test_c11_training.py (asserts degree units on the adapter fixture), test_conversion_validation.py::test_degrees_radians_explicit.
  • openamrobot-embodied-ai C10 dataset QA: reads the pinned C9 schema asset (87ab8a9); its pin moves only in a reviewed PR.
  • openamrobot-interfaces C9: proposed additive component mapping and model compatibility checks #39 (SatyaA27, Proposed component profile): already rad (lerobot_unit: rad); no change needed for units. A separate lift-source correction is suggested on C9: proposed additive component mapping and model compatibility checks #39.
  • Documentation: docs/c9-lerobot-dataset-contract.md (this repository), embodied-ai docs/c11/state_action_mapping.md, docs/c10/robot-profile-compatibility-v1.md.

Compatibility and migration

  • Old and new definitions coexist for the adapter profile: its documents validate unchanged.
  • A document with degree units under any other profile id becomes invalid. None is known in this organisation; any found is regenerated in radians or relabelled as the adapter profile.
  • Consumers pinned to the current schema SHA keep working until they repin; repinning is a reviewed PR per consumer.
  • Rollback: revert the schema if/else and the two fixtures; no recorded data changes.

Validation and evidence

  • bash tools/verify.sh (schema lint, fixture registry, ROS 2 Jazzy builds) on the implementing PR.
  • Revert run: with the schema from main and the new fixtures, validate_schemas fails with "Invalid fixture unexpectedly accepted: schemas/json/c9-lerobot-dataset-invalid-degrees-outside-adapter-profile.json".
  • Consumer evidence: the embodied-ai synthetic native conversion test (adapter profile) and the Baseline 1 development conversion (radian profile) both validate their sidecars against the changed schema.
  • Simulation and schema evidence only; no physical acceptance.

Safety and operational boundary

None. Dataset metadata only; no motion, power, actuator, safety I/O or readiness effect. The robot's joint interfaces remain authoritative for units on the robot.

Interface review checks

  • I identified every known producer and consumer, including UI, logs, and documentation where applicable. (One producer location, the MuJoCo episodes, is named but not located.)
  • I classified the compatibility impact and will update the contract version when required.
  • I have not treated telemetry as authoritative safety evidence.
  • The implementing PR will update the contract package and its consumers together, or list each consumer PR.

Prepared by Claude Code for Alex Reznichenko. AI disclosure: Claude Code (Claude Opus 5.5) wrote this request from the repositories named above.


Generated by Claude Code

Activity

  1. BotshareAI commented on Nov 19, 2026

    @BotshareAI
    ContributorAuthor

    Implementing draft PR (Proposed): #42 at head 288a7f3. The lift-source correction for #39 is a separate suggestion: #39 (comment)


    Generated by Claude Code

  2. BotshareAI commented on Nov 19, 2026

    @BotshareAI
    ContributorAuthor

    Founder/product decision — approved in principle (19 Nov 2026): canonical C9 joint units

    I confirm the intended OpenAMRobot project policy: joint positions in radians (rad), angular velocities in rad/s, lift position in metres (m), base linear velocity in m/s, and base angular velocity in rad/s. ROS 2 and the canonical C9 observation/action contract should use SI-consistent units. Degree-valued representations are permitted only at an explicitly named and documented interoperability adapter boundary (the existing LeRobot bi-OpenArm adapter profile), with explicit conversion metadata; never an implicit conversion in a model, training consumer or controller.

    This is founder approval of the policy direction, not technical acceptance of PR #42, not permission to merge, and not a change to the live robot interfaces or safety/control paths.

    Before implementing/adopting the contract change, Mohamed as software lead should decide and document:

    1. Whether this is a backward-incompatible semantic change requiring a new contract/profile version; do not assume unchanged JSON shape means unchanged semantics.
    2. Whether the proposed schema actually enforces the canonical units for the relevant dimensions (as opposed to only forbidding five spellings of degrees), and how to validate state/action channel types.
    3. The migration and consumer repinning order (embodied-ai converter, C10 QA, C11 training, C9: proposed additive component mapping and model compatibility checks #39 mapping and any existing degree-based datasets), with positive/negative regression tests.
    4. Exact provenance and auditability for adapter conversions, including how pre-existing datasets are identified.

    Please follow the usual decision-register process and link the resulting approved entry here. Retain draft status until the software lead has completed the technical compatibility review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions