RFC: Cross-embodiment AirStack — platform modules and trait-based compatibility

[andrewjong]

RFC: Cross-embodiment AirStack — platform modules and trait-based compatibility

This RFC extends RFC: Modular AirStack (#379) to a future goal: AirStack generalizing across form factors — different multirotors with different sensors, quadrupeds, wheeled robots, humanoids — while reusing autonomy modules across embodiments. It depends on the modularity framework's concepts (rungs, slots, module.yaml, stack.yaml, doctor, conformance marks, the registry); read #379 first. It is split out so the modularity RFC stays focused; nothing here blocks or changes the plan in #379 — this is what that plan enables later.

The rung/ladder model from #379 fits this problem, but it forces honesty about which rungs are universal and which are secretly multirotor-shaped.

1. What varies by embodiment vs. what doesn't

Walking the ladder top to bottom, the reusability gradient is clear:

• Tasks (tasks/navigate) — fully portable. "Go to this pose" means the same thing to a drone, a quadruped, and a rover. The most embodiment-neutral rung.
• Global planning / mapping / perception — mostly portable, with a workspace caveat (SE(3) free space vs. 2.5D terrain vs. SE(2)).
• Local planning — partially portable; this is where dynamics assumptions hide (a planner that treats "stop and hover" as an always-valid escape plan is multirotor-shaped whether it knows it or not).
• Trajectory/command rung — dialect varies: SE(3) trajectories vs. SE(2)/twist vs. footstep or gait commands.
• Controller + hardware interface + safety behaviors — almost entirely embodiment-specific: MAVROS/PX4 vs. ros2_control vs. vendor SDKs (Unitree, Spot); "land" vs. "stop" vs. "sit."

Design goal: keep the top of the ladder shared; make the bottom of the ladder swappable as a unit.

2. Embodiment = a platform module type

The platform is a first-class module in the #379 framework — the biggest one, but structurally just another module:

name: unitree_go2
type: platform
fills: [platform_interface, controller]
provides_rungs: [trajectory_se2, twist]
provides_tasks: [tasks/navigate, tasks/sit, tasks/stand]
traits: {workspace: se2_terrain, holonomic: false, can_stop_in_place: true, hover_capable: false}
safety_map: {SAFE_STOP: sit, RTB: walk_home, KILL: motor_cut}
description_pkg: go2_description        # URDF, sensor mounts, frames
sim: {isaac_asset: ..., sitl: ...}

stack.yaml gains a top-level platform: key, and everything else composes against it. The current PX4/multirotor stack — MAVROS interface, trajectory controller, takeoff/landing tasks, hover-based safety monitor — becomes the reference platform module.

3. Compatibility by traits, not platform enumeration

The wrong move is modules declaring embodiments: [multirotor, quadruped, ...] — that list rots the day someone adds a hexapod. Instead, modules declare requirements on traits and doctor matches them against the platform's declarations:

• DROAN requires {workspace: se3, hover_capable: true} → doctor rejects it on the rover, with a reason.
• A 2D costmap planner requires {workspace: se2*} → runs on rover and quadruped; on a drone only via an adapter (a fixed-altitude SE(2)→SE(3) shim — adapters being ordinary small modules).
• The waypoint task layer requires nothing but tasks/navigate → runs everywhere.

The payoff: latent assumptions become declared ones. Today "this planner assumes it can hover" lives in someone's head and fails in the field; under traits it's a manifest line and a sync-time error. Prior art: ros2_control's hardware-interface abstraction for the bottom layer; Nav2 is the cautionary tale of what happens when SE(2) assumptions are baked in rather than declared.

Two generalizations this forces, both healthy:

• Safety floor generalizes. Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379's "commands flow through the trajectory controller" becomes "commands flow through the platform's safety executive." Trunk defines abstract safety states (SAFE_STOP, RTB, KILL); each platform maps them to concrete behaviors (hover/land vs. stop vs. sit). The safety logic (state-estimate timeout, GCS override, task timeout) stays shared; only the terminal behaviors are platform-supplied.
• Task capability discovery. tasks/takeoff doesn't exist on a rover, so behavior trees are composed against the platform's provides_tasks, which doctor verifies statically ("this BT calls takeoff; platform doesn't provide it").

4. Testing transfers better than expected

tests/waypoint_checker.py is already embodiment-neutral — it judges an odometry track against corridors and tolerances, indifferent to whether the track was flown, walked, or driven. Conformance marks therefore become parameterized by trait: waypoint_navigation runs on anything providing tasks/navigate; takeoff_hover_land gates on hover_capable and simply isn't in a rover platform's conformance set. Each platform module ships its sim integration (Isaac asset + SITL/controller), so the same harness brings up "platform X + module Y" — and platform-compat badges slot into the registry alongside version badges.

5. Migration path — same forcing-function trick as #379

Do NOT build the trait system speculatively for robots we don't have. Sequencing (this is "Phase 5" relative to #379's plan — only after its phases 1–4 are proven):

1. Refactor the multirotor into a platform module while it's still the only platform. Extracting MAVROS + trajectory controller + takeoff/land + hover-safety into platform: px4_multirotor is what reveals the real seams — every place the refactor hurts is a hidden multirotor assumption in a "shared" layer.
2. Introduce traits + abstract safety states as part of that refactor, deriving trait names from the assumptions the refactor actually uncovers, not from speculation.
3. Validate with the cheapest second embodiment — a sim-only wheeled robot — before any new hardware. Two platforms is the minimum to know the boundary is real; one platform with a speculative abstraction is worse than none.

---

Split out from the design session behind #379 (2026-08-04) to keep that RFC focused on modularity. Comments welcome — especially from anyone with quadruped/rover/humanoid integration experience who can pressure-test the trait list.