feat(a1z): add real hardware adapter

[TomCC7]

Problem

DimOS already has the Galaxea A1Z planning model and mock blueprints, but current main has no real-hardware adapter or reproducible host bring-up path.

Solution

• add a registered, fixed six-axis galaxea_a1z adapter with staged safe startup, feedback validation, E-stop handling, position/servo-position modes, teaching/free-drive behavior, and G1Z gripper support
• use immutable validated A1ZConfig, A1ZGripperConfig, and A1ZTeachingConfig objects instead of a broad adapter constructor
• auto-select Linux SocketCAN or macOS userspace gs_usb, with transport mechanics isolated in gs_usb_bus.py
• add concrete vendor SDK stubs and typed robot/kinematics lifecycle state
• expose host setup as dimos a1z setup and dimos a1z can-setup, requesting sudo only for privileged Linux operations
• retain detailed Linux HHS/Jetson driver remediation in the A1Z documentation
• keep simulation on mock hardware and resolve the G1Z LFS model lazily at hardware connection time

How to test

uv sync --locked --inexact --group galaxea-a1z
dimos a1z setup --sdk-only

uv run pytest -q \
  dimos/hardware/manipulators/galaxea_a1z \
  dimos/robot/manipulators/a1z/test_config.py \
  dimos/robot/manipulators/a1z/test_setup.py \
  dimos/hardware/test_adapter_registries.py \
  dimos/hardware/manipulators/test_adapter_lifecycle.py

uv run pytest -q dimos/robot/test_all_blueprints.py -k a1z
uv run pytest -q dimos/robot/test_all_blueprints_generation.py

Validation completed:

• 82 focused adapter, registry, configuration, CLI, transport, and lifecycle tests passed
• 3 A1Z blueprint import tests passed
• blueprint registry generation passed
• focused Ruff and mypy checks passed
• pinned vendor SDK verification passed through dimos a1z setup --sdk-only
• repository fast suite: 3582 passed, 31 skipped; 3 unrelated existing control-coordinator E2E tests failed in untouched code
• all available pre-commit hooks passed; deno fmt could not run because deno is not installed locally

Hardware acceptance still required

• Linux HHS adapter through native SocketCAN
• macOS HHS adapter through userspace gs-usb
• staged position-mode enable/disable with the arm physically supported
• teaching/free-drive activation
• G1Z gripper feedback and commands

The PR remains a draft until physical acceptance is rerun after the cleanup.

AI assistance

Codex with GPT-5 performed the extraction, current-main adaptation, cleanup, tests, and validation. The implementation was ported from the existing Adventure X branch and narrowed to A1Z hardware support only.

Checklist

• I have read and approved the CLA.

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
dimos/cli/hardware/a1z.py	44.71%	103 Missing and 12 partials ⚠️
dimos/hardware/manipulators/galaxea_a1z/adapter.py	69.35%	84 Missing and 26 partials ⚠️
...os/hardware/manipulators/galaxea_a1z/gs_usb_bus.py	75.80%	25 Missing and 5 partials ⚠️
.../hardware/manipulators/galaxea_a1z/test_adapter.py	96.76%	8 Missing and 3 partials ⚠️
dimos/hardware/manipulators/galaxea_a1z/config.py	81.81%	2 Missing and 2 partials ⚠️
dimos/robot/manipulators/a1z/config.py	80.00%	1 Missing and 2 partials ⚠️

@@            Coverage Diff             @@
##             main    #3303      +/-   ##
==========================================
+ Coverage   75.47%   75.52%   +0.04%     
==========================================
  Files        1157     1166       +9     
  Lines      111292   112602    +1310     
  Branches    10073    10190     +117     
==========================================
+ Hits        83998    85040    +1042     
- Misses      24404    24624     +220     
- Partials     2890     2938      +48     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	69.59% <79.30%> (+0.11%)	⬆️
OS-ubuntu-latest	71.61% <79.30%> (+0.08%)	⬆️
Py-3.10	71.61% <79.30%> (+0.08%)	⬆️
Py-3.11	71.61% <79.30%> (+0.08%)	⬆️
Py-3.12	71.60% <79.30%> (+0.08%)	⬆️
Py-3.13	71.61% <79.30%> (+0.08%)	⬆️
Py-3.14	71.61% <79.30%> (+0.09%)	⬆️
Py-3.14t	71.60% <79.30%> (+0.07%)	⬆️
SelfHosted-Large	29.55% <23.96%> (-0.05%)	⬇️
SelfHosted-Linux	35.82% <23.96%> (-0.11%)	⬇️

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

Files with missing lines	Coverage Δ
dimos/cli/dimos.py	64.47% <100.00%> (+0.15%)	⬆️
dimos/cli/hardware/test_a1z.py	100.00% <100.00%> (ø)
dimos/cli/hardware_cli.py	100.00% <100.00%> (ø)
...mos/hardware/manipulators/galaxea_a1z/_registry.py	100.00% <100.00%> (ø)
...rdware/manipulators/galaxea_a1z/test_gs_usb_bus.py	100.00% <100.00%> (ø)
dimos/hardware/test_adapter_registries.py	93.68% <ø> (ø)
dimos/robot/manipulators/a1z/blueprints/basic.py	100.00% <100.00%> (ø)
dimos/robot/manipulators/a1z/blueprints/teleop.py	100.00% <100.00%> (ø)
dimos/robot/manipulators/a1z/config.py	90.90% <80.00%> (+0.43%)	⬆️
dimos/hardware/manipulators/galaxea_a1z/config.py	81.81% <81.81%> (ø)
... and 4 more

... and 4 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	🟢 Ready	View Preview	Jul 31, 2026, 7:02 PM

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
dimensional	🟡 Building	–	Jul 31, 2026, 7:01 PM

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

[greptile-apps]

Greptile Summary

Adds a real-hardware Galaxea A1Z integration.

• Registers a six-axis adapter with staged startup, lifecycle management, E-stop enforcement, teaching mode, and G1Z gripper support.
• Adds Linux SocketCAN and macOS userspace gs_usb transports.
• Adds validated hardware configuration, A1Z blueprints, host diagnostics, setup commands, SDK stubs, tests, and documentation.

Confidence Score: 5/5

The PR appears safe to merge with respect to the previously reported issue.

The gripper command path now rejects requests while the robot's soft E-stop is latched, so no blocking failure remains from the prior review thread.

Important Files Changed

Filename	Overview
dimos/hardware/manipulators/galaxea_a1z/adapter.py	Implements the A1Z hardware lifecycle, safe startup, feedback validation, E-stop handling, control modes, teaching behavior, and gripper integration; the previously reported gripper E-stop path is now guarded.
dimos/hardware/manipulators/galaxea_a1z/gs_usb_bus.py	Implements the macOS userspace gs_usb CAN transport with continuous receive draining, stale-frame flushing, echo filtering, and shutdown handling.
dimos/hardware/manipulators/galaxea_a1z/config.py	Defines immutable validated adapter, gripper, and teaching configuration objects.
dimos/cli/hardware/a1z.py	Adds A1Z dependency diagnostics and privileged Linux CAN configuration.
dimos/robot/manipulators/a1z/blueprints/basic.py	Connects the real A1Z hardware configuration to planner and coordinator blueprints.

Sequence Diagram

sequenceDiagram
    participant Runtime as DimOS Runtime
    participant Adapter as GalaxeaA1ZAdapter
    participant Transport as SocketCAN / gs_usb
    participant SDK as A1Z SDK
    participant Arm as A1Z + G1Z Hardware
    Runtime->>Adapter: connect()
    Adapter->>Transport: open selected CAN transport
    Adapter->>SDK: construct robot
    SDK->>Arm: open CAN communication
    Runtime->>Adapter: activate()
    Adapter->>SDK: staged safe startup / teaching startup
    SDK->>Arm: enable motors and control loop
    Runtime->>Adapter: joint or gripper command
    Adapter->>SDK: validated actuation command
    SDK->>Arm: CAN command
    Arm-->>SDK: motor feedback
    SDK-->>Adapter: joint and gripper state
    Runtime->>Adapter: write_stop()
    Adapter->>SDK: latch soft E-stop
    Adapter-->>Runtime: reject subsequent actuation
    Runtime->>Adapter: deactivate() / disconnect()
    Adapter->>SDK: stop and disable motors
    SDK->>Transport: close CAN bus

Loading

_{Reviews (8): Last reviewed commit: "fix(cli): keep hardware commands in name..." | Re-trigger Greptile}