feat(manipulation): add OpenYAM Damiao adapter

[TomCC7]

Contribution path

• Linked design discussion: feat(manipulation): add OpenYAM Damiao adapter #3129
  closes DIM-1311

Problem

DimOS lacked a direct OpenYAM integration for its six Damiao arm motors and gripper. Modeling them as separate manipulator adapters did not match the shared upstream robot lifecycle, shared CAN topology, or normalized gripper interface. The driver also needed gravity compensation without hiding the robot topology in runtime configuration.

Solution

• Add a generic DamiaoWholeBodyAdapter that uses the upstream Robot, Arm, and Gripper interfaces directly. It supports named CAN buses, multiple arm/gripper groups, normalized gripper commands and feedback, one synchronized command tick, and URDF-based gravity compensation.
• Add OpenYamDamiaoAdapter as the concrete OpenYAM topology: six arm joints and one gripper on the openyam logical bus. The gravity URDF remains lazy until hardware connection.
• Register real and mock whole-body adapters and wire the gripper into the standard OpenYAM coordinator, planner, and keyboard-teleoperation blueprints.
• Expose CAN setup through dimos can setup and move the Piper command out of the robot package.
• Add focused behavior tests for dual-arm command routing, gripper normalization, lifecycle rollback, gravity torque composition, adapter registration, CAN CLI execution, and import-time LFS isolation.

The generic HardwareComponent.address remains a single-address compatibility field. Damiao whole bodies configure one or more physical CAN interfaces through DamiaoRuntimeConfig.bus_addresses instead.

How to Test

Configure the physical CAN interface, then start the default OpenYAM teleoperation stack:

dimos can setup can0
dimos run keyboard-teleop-openyam

Automated validation:

uv run pytest dimos/hardware/whole_body dimos/hardware/test_adapter_registries.py dimos/cli/test_can.py

The implementation was validated with mock/in-memory CAN and unit tests. Physical OpenYAM motion was not tested by the AI assistant.

AI assistance

OpenAI Codex with GPT-5 assisted throughout design review, implementation, test development, debugging, and documentation. The author reviewed and approved the design decisions interactively.

Checklist

• I have read and approved the CLA.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟢 Ready	View Preview	Jul 21, 2026, 11:39 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[codecov]

Codecov Report

❌ Patch coverage is 97.54190% with 22 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/hardware/whole_body/damiao/adapter.py	95.21%	8 Missing and 3 partials ⚠️
dimos/hardware/whole_body/damiao/test_adapter.py	97.00%	5 Missing and 5 partials ⚠️
...imos/hardware/whole_body/openyam_damiao/adapter.py	94.73%	1 Missing ⚠️

@@            Coverage Diff             @@
##             main    #3129      +/-   ##
==========================================
+ Coverage   75.46%   75.61%   +0.15%     
==========================================
  Files        1157     1166       +9     
  Lines      111276   112068     +792     
  Branches    10073    10118      +45     
==========================================
+ Hits        83971    84740     +769     
- Misses      24417    24434      +17     
- Partials     2888     2894       +6     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	69.65% <97.54%> (+0.19%)	⬆️
OS-ubuntu-latest	71.69% <97.54%> (+0.18%)	⬆️
Py-3.10	71.68% <97.54%> (+0.17%)	⬆️
Py-3.11	71.69% <97.54%> (+0.18%)	⬆️
Py-3.12	71.68% <97.54%> (+0.17%)	⬆️
Py-3.13	71.69% <97.54%> (+0.18%)	⬆️
Py-3.14	71.69% <97.54%> (+0.17%)	⬆️
Py-3.14t	71.68% <97.54%> (+0.18%)	⬆️
SelfHosted-Large	29.61% <32.73%> (+0.01%)	⬆️
SelfHosted-Linux	35.89% <32.73%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/cli/can.py	100.00% <100.00%> (ø)
dimos/cli/dimos.py	64.47% <100.00%> (+0.15%)	⬆️
dimos/cli/test_can.py	100.00% <100.00%> (ø)
dimos/control/test_control.py	95.95% <100.00%> (+0.06%)	⬆️
dimos/control/tick_loop.py	70.37% <100.00%> (+0.27%)	⬆️
.../core/coordination/blueprint_config/test_parser.py	97.32% <100.00%> (+0.07%)	⬆️
dimos/hardware/test_adapter_registries.py	95.78% <100.00%> (+2.10%)	⬆️
dimos/hardware/whole_body/damiao/config.py	100.00% <100.00%> (ø)
dimos/hardware/whole_body/mock/_registry.py	100.00% <100.00%> (ø)
dimos/hardware/whole_body/mock/adapter.py	100.00% <100.00%> (ø)
... and 12 more

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟡 Building	–	Jul 21, 2026, 11:39 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Greptile Summary

The PR adds a generic Damiao whole-body adapter and an OpenYAM topology with shared CAN lifecycle, normalized gripper control, gravity compensation, mock support, CLI CAN setup, and updated OpenYAM blueprints.

• Registers real and mock whole-body adapters for the six-joint OpenYAM arm and gripper.
• Routes arm, planner, keyboard, and gripper commands through one coordinator hardware component.
• Adds CAN management commands, dependency wiring, model assets, and focused lifecycle/routing tests.

Confidence Score: 4/5

The stale hardware-feedback path should be fixed before merging because an idle OpenYAM can publish frozen joint state and gravity compensation can use an older pose.

The new adapter reads cached SDK arrays without refreshing the robot, while its periodic tick occurs only after a command write; therefore feedback stops updating whenever no task writes and command-time gravity uses the preceding snapshot.

Files Needing Attention: dimos/hardware/whole_body/damiao/adapter.py

Important Files Changed

Filename	Overview
dimos/hardware/whole_body/damiao/adapter.py	Adds the shared Damiao lifecycle and gravity/gripper command path, but state reads do not refresh the upstream snapshot.
dimos/hardware/whole_body/openyam_damiao/adapter.py	Declares the OpenYAM CAN topology, motor IDs, gripper calibration, and lazy gravity model.
dimos/robot/manipulators/openyam/config.py	Selects real or mock whole-body hardware and consistently maps the six arm joints plus normalized gripper.
dimos/robot/manipulators/openyam/blueprints/teleop.py	Adds working keyboard gripper routing and combined teleoperation/planner configurations.
dimos/cli/can.py	Adds argument-vector-based Linux CAN status, setup, up, and down commands with explicit failure reporting.
pyproject.toml	Adds the Linux Damiao SDK and keyboard dependency with a corresponding lockfile update.

Comments Outside Diff (1)

1. dimos/hardware/whole_body/damiao/adapter.py, line 1615-1623 (link)

   State reads use stale snapshots

   When the arm moves while no control task emits commands, read_motor_states() reads the SDK's cached arrays without refreshing the robot, causing published joint state to remain frozen. During command cycles, gravity compensation is also calculated from the preceding snapshot because Robot.tick() runs only after command composition.

   Knowledge Base Used: Control Coordinator and Control Tasks

_{Reviews (1): Last reviewed commit: "feat: nest CAN commands under hardware" | Re-trigger Greptile}