RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms

[andrewjong]

RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms

Companion to RFC #379: Modular AirStack. #379 defines how modules are packaged, distributed, and tested (small manifests, stack folders of standard ROS 2 launch files, interface conventions, generated wiring.md, doctor --live, conformance marks, registry); this RFC builds on that machinery to configure heterogeneous deployments, at three scales:

1. Within a platform class — vehicle types and units (big vs. small drone: tuning, sensor suites, URDF) — §1
2. Across a fleet — heterogeneous multi-robot (different hardware and/or software per robot) with a direct mapping to simulation, plus the top-level configuration surface — §2–4
3. Across platform classes — embodiments (quadrupeds, wheeled robots, humanoids) reusing autonomy modules — §5–8, future work

Scales 1–2 land with #379's Phase 3 (they consume stack folders and the conventions spec defined there). Scale 3 is sequenced only after #379's phases 1–4 are proven. A visual companion, #385: Directory Atlas, shows the resulting directory layouts for every repo shape both RFCs define.

The problem at scales 1–2: today three env vars blur these concerns (URDF_FILE, NUM_ROBOTS, ISAAC_SIM_SCRIPT_NAME) and compose deploy.replicas can only stamp out identical containers. The hierarchy that untangles them: platform class (code) → vehicle type (data) → vehicle unit (calibration) → robot instance → fleet. Every level is a readable file; a robot in a fleet is the composition vehicle × stack folder × unit, with hardware, software, and placement heterogeneity as independent axes.

1. Vehicle types and units

# vehicle: quad_small
platform: px4_multirotor
airframe: {base_xacro: quad_330.xacro, mass: 1.2, tuning: tuning/quad_small.yaml}
sensors:
  - {type: stereo_cam, id: front_stereo, mount: mounts/front.yaml,   # extrinsics
     driver: {module: realsense_driver}, sim: {pegasus: stereo_prim}}
  - {type: lidar_2d, id: down_lidar, mount: mounts/belly.yaml}
sim_asset: quad_330.usd

• The URDF is generated (base xacro + sensor mounts), replacing monolithic hand-built URDFs like iris_with_sensors.pegasus.robot.urdf.
• Each sensor declares its real driver and sim representation in one entry — one source of truth for both worlds. Sensor ids feed the sensors/* topic naming convention (Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §4.2), and wiring snapshots normalize sensor-driver nodes to these ids — the declared driver/sim pairing is what lets a sim-generated wiring.md diff cleanly against a hardware bring-up (Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §4).
• Vehicles are data-only packages, shareable via Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379's module mechanism (type: data). Controller tuning is parameterized by vehicle (like PX4 airframe files), not baked into platform code.
• Unit ≠ type: intrinsics/extrinsics calibration is per-serial-number and field-updated; it lives in a gitignored local overlay (config/local/calibration/<serial>/), so recalibrating never edits the shared package.

2. Fleets

# config/fleets/field_mixed.yaml — hexa mapper + two lite quads with different offload splits
defaults: {vehicle: quad_small, stack: stacks/lite_default}
sim: {scene: forest_clearing.usd}          # used only when sim != none

robots:
  wanda:                                   # Jetson Orin — everything onboard
    vehicle: hexa_big
    unit: SN-0042                          # binds config/local/calibration/SN-0042/
    stack: stacks/full_default
    spawn: [0, 0, 0.5]                     # sim-only; ignored on hardware
    overrides: {takeoff_landing_planner.takeoff_altitude: 8.0}
  vision:                                  # VOXL — offload global planning
    unit: SN-0117
    spawn: [4, 0, 0.5]
    stack: stacks/lite_offload_global      # a SPLIT stack (below)
    hosts: {offboard: gcs}                 # which ground host runs its offboard half
  pietro:                                  # minimal compute — offload perception too
    unit: SN-0118
    spawn: [8, 0, 0.5]
    stack: swarm_stacks/vla_offload        # <alias>/<stack> from an external stack repo declared in airstack.yaml (§3)
    hosts: {offboard: edge_box}

ground:                                    # named ground hosts — not one homogeneous GCS
  gcs:      {stack: stacks/gcs_ui}         # operator UI; also hosts vision's offboard half
  edge_box: {}                             # compute-only host for pietro's heavier offload

network: {domain_policy: auto, gossip_domain: 99}   # auto = robot N → domain N (today's rule)

Key properties:

• A split is a stack shape. A split stack folder (Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §3) carries multiple launch entry points — launch/onboard.launch.xml, launch/offboard.launch.xml — plus a bridge.yaml explicitly listing every topic/action that crosses the machine boundary (name, type, direction). The bridge list feeds DDS-router config generation, and it is the split, readable in source — explicit beats derived. Today's coarse AUTONOMY_ROLE trichotomy (full/onboard/offboard) becomes "which entry point does this host run," derived per robot from hosts:; arbitrary splits replace the one hardcoded two-way split — a third machine is just another launch entry point + bridge section.
• Placement constraints are observational checks — with one enumerated exception. The conventions spec marks the controller and safety executive onboard-only (link loss must leave the robot able to failsafe) and flags latency-sensitive interfaces. doctor errors if control_setpoint or trajectory-group topics appear in any bridge.yaml — this is one of doctor's two enumerated hard gates (Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §4); everywhere else it observes and reports. doctor --live verifies each host's running graph against that host's entry-point subgraph of the stack's single wiring.md (one per stack, nodes grouped by host, bridge edges marked — Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §4) plus the bridge list — a lint over an explicit file, nothing inferred.
• Ground hosts are named entries, plural — an operator GCS and a compute box are different machines with different offboard tenants; airstack fleet generate emits each host's services from the hosts: entries that name it.
• defaults: keeps homogeneous fleets terse (a robot can be one line + serial).
• spawn:/sim.scene feed a generic Isaac fleet spawner (replacing the hardcoded one-/multi-drone launch scripts) and are ignored on hardware — sim vs. real is a deployment mode of the same file. Test harness: --num-robots N becomes --fleet <preset>, and heterogeneous system tests — including split placements — become expressible.
• Per-robot overrides: are leaf values only (ROS params, launch args) — the same anti-variant-explosion logic as shared includable launch files, one level up. A robot needing different topology points at a different stack folder; that division is what keeps fleet files skimmable.
• The existing robot_name_map resolver extends to resolve the whole fleet entry (name, domain, vehicle, stack, hosts). Compose: keep deploy.replicas for homogeneous fleets; airstack fleet generate emits per-robot and per-ground-host services when heterogeneous (required anyway — different stacks mean different composed images, Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §6).
• Doctor's most valuable check is the (vehicle, stack) pair: the stack's wiring.md consumes sensors/front_stereo/* → the vehicle manifest must carry a sensor with id: front_stereo → missing = named error before launch. Plus: a hosts: key naming no ground entry, a robot naming a stack with no matching entry points for its hosts, duplicate domains, a unit with no calibration dir.

3. Top level: airstack.yaml

One file answers "what does this checkout run?" — everything else is derived or pointed to:

release: 0.20                          # a tagged reference-stack set: trunk + pinned module versions (#379 §7)
fleet: config/fleets/field_mixed.yaml
sim: isaacsim                          # isaacsim | msairsim | none (real hardware)
modules:                               # additions beyond the release pins
  dfm2_disturbances: {version: 1.2.0}
  my_planner: {path: modules/my_planner}   # local/in-development
stacks:                                # external stack repos — fleets reference their stacks as <alias>/<stack>
  swarm_stacks: {repo: "git@github.com:airlab-internal/swarm-stacks.git", ref: v1.3}

airstack sync resolves release + modules against the registry and the active stacks' pinned .repos files → writes modules.lock (exact refs + image digest chain), fetches modules/, fetches declared external stack repos into gitignored stacks/.external/<alias>/, generates .env. A fleet's stack: values resolve first as paths in the checkout (stacks/...), then as <alias>/<stack> against the declared stack repos — how a robot points at a stack "wherever it's hosted" without a fork. Config tree:

airstack.yaml            # the one hand-edited entry point
.env, modules.lock       # GENERATED — never hand-edited
modules/                 # gitignored module checkouts
config/
├── fleets/   *.yaml     # who exists, which body, which brain, which hosts
├── vehicles/ <name>/    # in-tree vehicle types (others arrive as data modules)
└── local/               # gitignored: calibration/<serial>/, overrides.yaml
stacks/                  # stack folders (#379 §3) — trunk's references; others live in their own repos
└── .external/           # GITIGNORED — external stack repos fetched by sync, addressed <alias>/<stack>

Module-pin resolution (low → high): release-set defaults → the stack's modules.repos → airstack.yaml modules: entries. Pins resolve per stack: a stack's pins are its tested-together claim, so they beat release defaults for that stack's own composition, and two robots' stacks may legitimately pin the same module differently (each stack's image chain uses its own pins, #379 §6). An airstack.yaml entry overrides both — the checkout owner's deliberate act — but voids the affected stacks' tested-together claim for that run: sync names every deviation it resolves (never silently merges), and modules.lock + effective_config.yaml record the override so the run can't masquerade as the badged set.

Precedence (low → high): release-set defaults → stack/vehicle files → fleet per-robot overrides → config/local/overrides.yaml → CLI/env flags. Rule: CLI/env may select among declared configs and set leaf values, never define new structure — the discipline today's .env lacks. CI configs and developer configs become the same artifact: a failing CI run is reproduced by copying one airstack.yaml.

Migration of today's .env vars: VERSION → release: (.env generated); NUM_ROBOTS → implicit in fleet; ROBOT_NAME_MAP_CONFIG_FILE → absorbed into fleet; AUTONOMY_ROLE → derived from hosts: + the stack's entry points (§2); URDF_FILE → generated from vehicle; ISAAC_SIM_SCRIPT_NAME → gone (fleet spawner).

4. One-off CLI overrides

For quick experiments, a fifth precedence layer with footprints:

airstack up --set robots.wanda.overrides.takeoff_landing_planner.takeoff_altitude=3.0
airstack up --set robots.pietro.stack=stacks/my_experiment
airstack up --robots wanda --sim msairsim --with dfm2_disturbances --without gossip  # sugar

• Overrides feed config resolution before doctor runs — a faster way to edit config, never a bypass; violations fail identically to file edits.
• Every run dumps its fully-resolved config (.airstack/runs/<ts>/effective_config.yaml); airstack config freeze --from-last-run > config/fleets/my_experiment.yaml promotes a one-off to a named preset. No lost incantations.
• Guardrails: a visible banner lists active overrides; metrics.json records the override set so overridden runs can't masquerade as baselines; values-not-structure (defining a new robot inline is refused); nothing persists without freeze.

---

Part 2 — Cross-embodiment (future work)

Generalizing across platform classes: quadrupeds, wheeled robots, humanoids. The narrow-waist conventions from #379 fit, but they force honesty about which conventions are universal and which are secretly multirotor-shaped.

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

The reusability gradient down the stack:

• Tasks (tasks/navigate) — fully portable: "go to this pose" means the same thing to a drone, quadruped, or rover.
• 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; dynamics assumptions hide here (a planner treating "stop and hover" as an always-valid escape plan is multirotor-shaped whether it knows it or not).
• Trajectory/command interface — dialect varies: SE(3) trajectories vs. SE(2)/twist vs. footstep/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 stack shared; make the bottom swappable as a unit.

6. Embodiment = a platform module type

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

name: unitree_go2
type: platform
provides_dialects: [trajectory_se2, twist]      # command interfaces per the conventions spec
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
sim: {isaac_asset: ..., sitl: ...}

A platform module ships the interface + controller + safety-behavior layer and its own reference stack folders — a stack targets a platform by including that platform's bringup launch. Division of labor with §1: a platform module defines a class of machine (code: interface, controller, safety behaviors, command dialects); vehicle configs describe instances within the class; fleet.yaml composes deployments. The current PX4/multirotor stack becomes the reference platform module — a quadruped is just another platform + vehicle once both layers exist.

7. Compatibility by traits, not platform enumeration

Modules declaring embodiments: [multirotor, quadruped, ...] rots the day someone adds a hexapod. Instead, modules declare requirements on traits and doctor matches them against the platform:

• DROAN requires {workspace: se3, hover_capable: true} → rejected 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 are ordinary small modules, wired in by the stack that needs them).
• The waypoint task layer requires only tasks/navigate → runs everywhere.

Payoff: latent assumptions become declared ones — "this planner assumes it can hover" moves from someone's head to a manifest line and a sync-time error. Prior art: ros2_control's hardware-interface abstraction; Nav2 is the cautionary tale of SE(2) assumptions baked in rather than declared. (Traits are the one place a manifest carries semantic claims, and they gate compatibility warnings, never wiring — doctor reports, the stack author decides.)

Two forced generalizations, both healthy:

• Safety floor. 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). Safety logic (state-estimate timeout, GCS override, task timeout) stays shared; only terminal behaviors are platform-supplied.
• Task capability discovery. tasks/takeoff doesn't exist on a rover; behavior trees are composed against the platform's provides_tasks, verified statically by doctor ("this BT calls takeoff; platform doesn't provide it").

8. Testing and migration path

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 become trait-parameterized: waypoint_navigation runs on anything providing tasks/navigate; takeoff_hover_land gates on hover_capable and isn't in a rover's conformance set. Each platform ships its sim integration, so the same harness brings up "platform X + module Y"; platform-compat badges join version badges in the registry.

Migration — do NOT build the trait system speculatively:

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 reveals the real seams — every place the refactor hurts is a hidden multirotor assumption in a "shared" layer.
2. Derive traits + abstract safety states from what that refactor actually uncovers, not speculation.
3. Validate with the cheapest second embodiment — a sim-only wheeled robot — before any 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), revised alongside it (2026-08-19); consistency pass 2026-08-20 (module-pin resolution rule, external stack repos via stacks:, split-stack wiring.md clarified, gate-vs-observe cross-refs — changelog in comments) — earlier drafts and the rejected alternatives are summarized in the design-history comment below. Comments welcome — especially from anyone with quadruped/rover/humanoid integration experience who can pressure-test the trait list, and from anyone running offboard splits who can pressure-test the bridge-list model.

[andrewjong]

Design history: what Rev 1 proposed here, and why it changed

The RFC body above is Rev 2 (2026-08-19), rewritten as a standalone alongside #379's revision — see #379's design-history comment for the full account of the rejected slot/stack.yaml/wiring-resolver design. Rev 1 of this RFC (2026-08-04, full text in the edit history) built on that machinery, so its deployment layer changed accordingly:

• Robots referenced slot-assignment stack.yaml files (with inheritance). Rev 2: a robot references a stack folder of standard launch files — vehicle × stack × unit — and a robot needing different topology points at a different folder, possibly in its owner's own repo.
• split: was a placement annotation over a stack's slots — e.g. split: {offboard: [global_planner, global_world_model], host: gcs} — with a rule that a split is legal iff its boundary cuts only declared rung topics, validated by placement-constraint algebra in doctor, and the DDS-router bridge config derived from the rung annotations. Rev 2: a split is a stack shape — multiple launch entry points (onboard.launch.xml, offboard.launch.xml) plus an explicit bridge.yaml listing every crossing topic/action, which both feeds DDS-router generation and is readable in source. Placement constraints became a lint over that explicit file (doctor rejects control-setpoint/trajectory topics in any bridge list) instead of an algebra over annotations. Explicit beats derived: with a resolver gone from Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379, there were no rung annotations left to derive from — and the bridge file turns out to be the clearer artifact anyway.
• AUTONOMY_ROLE was derived from the split annotation. Rev 2: derived from the fleet's hosts: map + which entry point each host runs. Same outcome (the full/onboard/offboard trichotomy generalizes to arbitrary N-way splits), simpler mechanism.

Unchanged from Rev 1, because they never depended on slots: §1 vehicle types/units (data modules, generated URDF, per-serial calibration overlays), §3 airstack.yaml + the precedence chain, §4 CLI overrides with per-run effective_config.yaml dumps and config freeze, and essentially all of Part 2 (platform modules, traits, abstract safety states, the refactor-multirotor-first migration path) — with traits clarified in Rev 2 as compatibility warnings matched by doctor, never wiring inputs.

[andrewjong]

Changelog: consistency pass (2026-08-20)

Updated in place alongside #379's consistency pass — no design decisions changed. What moved:

• §1 — sensor ids now also name what wiring snapshots normalize sensor-driver nodes to: the declared driver/sim pairing is what lets a sim-generated wiring.md diff cleanly against a hardware bring-up (Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §4).
• §2 — the bridge.yaml placement check is explicitly flagged as one of doctor's two enumerated hard gates (Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §4 now enumerates them); everywhere else doctor observes and reports. The "each half's wiring.md" ambiguity is resolved: one wiring.md per stack, nodes grouped by host; doctor --live diffs each host's entry-point subgraph plus the bridge list.
• §2 — the fleet example's pietro now references swarm_stacks/vla_offload, showing the <alias>/<stack> form for external stack repos.
• §3 — new stacks: section in airstack.yaml: external stack repos are declared there and fetched by sync into gitignored stacks/.external/<alias>/; a fleet's stack: values resolve first as checkout paths, then as <alias>/<stack>. Closes the gap where a robot could point at a stack "wherever it's hosted" with no defined fetch/addressing mechanism.
• §3 — new module-pin resolution rule (low → high): release-set defaults → the stack's modules.repos → airstack.yaml modules: entries, resolved per stack (two robots' stacks may pin the same module differently). An airstack.yaml override wins but voids the affected stacks' tested-together claim for that run; sync names every deviation, and modules.lock + effective_config.yaml record it. Closes the gap where release pins vs. stack pins had no stated winner.

The Directory Atlas (#385) was updated to match.