Repository navigation
Description
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:
- Canonical C9 units: joint positions in
rad, joint velocities inrad/s, lift position inm, base velocities inm/sandrad/s. Every OpenAMRobot capture profile uses them. - 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 unitrad, target unitdegree, factor 180/pi from its declared conversion table), never in a consumer. - Schema: a vector feature whose
profileis notlerobot-v0.6.1-bi-openarm-positionrejects a dimension unit ofdegree,degrees,deg,deg/sordegree/s. The adapter profile keeps its degree descriptors unchanged. - 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, branchsatya/capture-conversion-benchmark, head9643da1): writes the sidecarprofilefromnative_profile_idorprofile_id, and units from the capture profile channels. Its synthetic fixture uses the adapter profile withradsource anddegreetarget, 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): requiresdegreefor 16-channel data ("C9 adapter profile requires degree-valued channels");docs/c11/state_action_mapping.mdstates 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-aidocs/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/elseand 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
mainand the new fixtures,validate_schemasfails 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
BotshareAI commentedon Nov 19, 2026
Implementing draft PR (Proposed): #42 at head 288a7f3. The lift-source correction for #39 is a separate suggestion: #39 (comment)
Generated by Claude Code
BotshareAI commentedon Nov 19, 2026
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:
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.