AirStack 0.20.0

• Pre-release versioning terminology: -alpha.N → -dev.N. The
  development line on develop now uses X.Y.Z-dev.N pre-release versions
  (first: 0.21.0-dev.0) instead of X.Y.Z-alpha.N. The
  check-version-increment PR gate accepts exactly dev, beta, rc
  (ordering dev < beta < rc < release); the main→develop sync workflow
  rolls develop forward to the next minor's -dev.0 after a release. Docs,
  skills, and the PR template were updated to match. Existing -alpha.N
  versions in git history and in declared module-compat ranges remain valid
  historical references.

• Single, revamped repo README. The repo now has one README.md (at the
  root — docs/README.md was removed), rewritten around the redesigned docs
  home page: quickstart, one-command bring-up, sim-to-real parity, CI flight
  campaigns, and agent-driven workflows.

• Module-catalog sync automation + drift alarm. Registering a module is
  two merges (registry PR to
  airstack-modules-index

  • trunk fixture/catalog sync), and the docs deploy regenerates the
    published catalog from the live registry — so a missed half used to
    drop the module from the site silently. Now the develop docs deploy
    raises a docs-catalog-drift issue whenever the committed catalog and
    the live registry disagree, and the new sync-modules-index workflow
    (daily + manual dispatch) opens the trunk sync PR automatically
    (.github/workflows/scripts/registry_sync.py).

• Trustworthy system-test outcomes. A red system-tests run now always
  means the code under test got worse, never that CI infrastructure hiccuped:
  run_meta.json (schema v2) classifies every failure as
  assertion / infrastructure / collection / ci_integrity, and CI fails
  only on those — comparable numeric metric deltas (Hz, CPU, error metrics)
  are advisory in the report and no longer fail the PR. Metric
  comparisons only happen between fingerprint-identical campaigns (same
  tests and same behavior-changing CLI config: sim, robot count,
  trajectories, velocities, tolerances), with the baseline selected from
  recent base-branch artifacts by fingerprint instead of "newest artifact of
  any shape". Bring-up/readiness failures fail fast when the simulator
  process dies (instead of burning the full /clock timeout on an ephemeral
  GPU pod) and capture a bounded, secret-free diagnostics/ bundle before
  the pod is destroyed. Maintainers can dispatch focused flight campaigns
  (trajectory_types, takeoff_velocities) from workflow_dispatch. New
  airstack up --config-only: dry-run restricted to logical launch-config
  contracts (no Docker/credentials/image/submodule prerequisites).

• CI un-redded: Metrics Report and Unit Tests fixed. Every PR had been
  failing since ~2026-08-20 for reasons unrelated to the code under test.
  The system-tests Metrics Report job installed only tabulate, so
  tests/parse_metrics.py (which imports the tests/harness package)
  crashed with ModuleNotFoundError: No module named 'yaml' — and the crash
  was misreported as "Metric regression detected"; the job now installs
  tests/requirements.txt, and the regression verdict additionally requires
  a written report.md so a parser crash can never masquerade as a metric
  regression. The Unit Tests workflow ran the tests/meta/ contract
  suite on a checkout with no submodules and no omni_pass.env, so every
  airstack up --dry-run --sim isaac contract hard-failed preflight and the
  docs-catalog contract missed the submodule-resident vdb_mapping_ros2
  README; the workflow now checks out submodules recursively and provisions
  the same guest omni_pass.env stub that module-system-tests.yml uses
  (preflight itself stays strict).

• New reference stack full_mighty + registered mighty module. The
  MIGHTY Hermite-spline local planner (MIT ACL, RA-L 2026) with its
  acl-mapping voxel world model and a NavigateTask/trajectory_controller
  bridge, packaged as the external
  asm_mighty module (pinned at
  v0.1.1 in the stack's modules.repos; repo private until the AirStack
  agent study concludes). full_mighty
  is full_default with only the local-planner include swapped — the
  module-swap demonstration for the modular architecture. Registered in the
  module catalog; validated on Isaac Sim (44/44
  vendored gtests, empty-world route flight, 7/7 pillar-field traversals,
  5/5 judged obstacle-route flights at 1.59–1.65 m min clearance vs a 1.0 m
  gate).

• Fixed: the docs search dropdown rendered behind the nav-tabs bar and the
  version-selector text (custom z-indexes inside the header's stacking
  context); the search subtree is now lifted above both.

Documentation overhaul (Diátaxis restructuring). The docs site was
audited against the Diátaxis framework and
reorganized; page URLs are preserved (moves are covered by redirects):

• The nav is now organized by document kind — Tutorials / How-to Guides /
  Reference / Concepts tabs — replacing the difficulty-tier
  ("Beginner/Intermediate/Advanced Tutorials") buckets, which contained no
  tutorials. The doc-authoring standards (Documentation Guide, mkdocs
  skills) now prescribe the quadrant taxonomy and include a decision tree.
• 18 verified doc/code mismatches fixed, including: a phantom
  --recreate flag and missing --scene in the CLI reference; phantom
  ROBOT_LAUNCH_PACKAGE/ROBOT_LAUNCH_FILE env vars (real: LAUNCH_PACKAGE);
  nonexistent airstack_msgs/TrajectorySegment/TrajectoryOverride types in
  doc templates (real: TrajectoryXYZVYaw); the MS-AirSim tmux window
  ordering (bridges launch before PX4) and MAVLink port math; the Getting
  Started Foxglove step (layout now auto-seeds; manual import retired).
• Removed superseded pages with redirects: the Ascent-era scene-setup pair,
  the pre-harness testing-frameworks page, the orphaned tutorials index and
  two stale duplicate pages (development_environment, airstack-cli index).
  The git-hooks docker-versioning READMEs are now deprecation notices — the
  hook they described conflicts with the semver check-version-increment
  gate (note: airstack config git-hooks still installs it; CLI removal is
  a follow-up).
• Pages that documented never-built or fabricated behavior were rewritten
  from the code: global planning (the unimplemented Global-Manager/
  PlanRequest protocol is gone), the robot interface page (state flows via
  odometry_conversion), robot configuration, HITL (now uses the
  gcs-real hitl profile and Foxglove verification), rosbags, and the
  robot-side data-offloading page (now points at the storage-tools
  workflow).
• Hybrid pages split by audience: system_architecture.md (explanation
  core; drifted topic tables replaced with links into the interface
  conventions spec), CI/CD (new Using CI how-to), GCS Foxglove (new
  Extending the Visualizer), Isaac Sim docker (new Container
  Workflows). Duplicated hot tables (topics, CLI flags, pytest marks,
  requirements) now live in one canonical home each.
• Previously off-site references added to the nav: the vehicle.yaml and
  module.yaml schemas, local calibration contract, the RViz tasks/waypoint
  panel manuals, the LiDAR point-cloud filter README, and the OSMO lab-admin
  guide. New reference pages: the complete .env schema, the
  airstack_msgs interface reference, the trajectory-library YAML format,
  and a supported-platform matrix. New/rewritten onboarding: Deploying to
  Hardware and Operating the GCS.
• The Interface Conventions Specification was bumped to v1.0.1: §8 now
  lists all eight task_msgs actions (added tasks/coverage and
  tasks/chat, both defined with no shipped executor).
• Six new how-to guides: Adding a State Estimator, Adding a Planner,
  Creating a Multi-Agent Coordination Algorithm (grouped under a new
  How-to → Autonomy section), Creating a Custom Stack Topology, Adding a
  Vehicle Type/Unit/Platform, and Getting the Most out of Your Coding
  Agent (the feature-notebook workflow). Each presents the in-tree
  package vs airstack module create --in-tree module-scaffolding
  choice. The Concepts tab now sits directly after Tutorials, and the
  UE→Isaac export tutorial was refreshed (new walkthrough video, export
  as Z-up in meters, note that UE Decals — paint markings, dirt,
  puddles — do not export).
• Five new beginner tutorials completing the learning path: Fly a Mission
  from the GCS, Change a Parameter (the edit→relaunch loop; config YAML is
  symlink-installed from the bind-mounted source, so no rebuild), Write
  Your First Module (airstack module create --in-tree scaffold, with a
  fix-it note for the scaffold's double-namespace stub), Your First Fleet
  (two-robot fleet file, per-robot Foxglove tabs), and Build and Fly Your
  Own Scene (GUI stage → scene catalog → --scene flight → baked
  *.scene.usd). New how-to: Adding a Controller (verified
  trajectory_controller → pid_controller → interface command chain);
  Adding a Planner expanded into Adding a World Model and Planner
  (local world-model/planner matched pairs vs the spec'd global map
  interchange).

This release restructures AirStack from a monolith into modules,
stacks, and fleets, implementing
RFC #379 (Modular AirStack)
scales 1–2 of
RFC #380 (Heterogeneous AirStack),
and the stack-folder anatomy of
RFC #385 (Directory Atlas).
Feature docs deliberately cite none of these — the design sources live here:

• Modules are ...

AirStack 0.19.0

Added

• Intent flags on airstack up — --sim isaac|airsim, --robots N, --headless, --play/--no-play, --no-autolaunch, --wait, --dry-run — deriving the coordinated env-var sets (compose profiles, URDF, single/multi Isaac launch script) as exported leaf values, with a resolved-config banner and a per-run .airstack/runs/<ts>/effective_config.env dump; contract-tested in tests/meta/test_launch_intent_contract.py (unit mark)

• airstack ready (and airstack up --wait): staged flight-readiness gates mirroring the system-test budgets — containers → sim /clock → per-robot sentinel nodes → PX4 MAVROS-connected + local_position/odom streaming (the armable signal) — with per-gate diagnostics and --json for scripts

• Preflight validation in airstack up on resolved configuration (env > --env-file > .env): one-simulator guard no longer bypassed by --env-file; NUM_ROBOTS>1 with the single-drone Isaac script is a named hard error; missing images are listed with an image-pull hint before compose starts an implicit build; missing omni_pass.env / empty Pegasus submodule / Docker < 29 surfaced on the host (AIRSTACK_SKIP_PREFLIGHT=1 downgrades errors to warnings)

• tmux pane output is mirrored to container stdout via shared .tmux.conf hooks, so docker logs / airstack logs now show colcon builds, ros2 launch output, sim loading, and crashes

• Automatic unit-tests.yml PR gate on ubuntu-latest, plus run_meta.json outcome metadata so reports distinguish completed simulation campaigns from collection errors, empty selections, timeouts, and cancellations

• overrides/isaac-optitrack-simulation.env — brings up Isaac Sim with the NatNet emulator and PX4 flying on mocap EKF2 external vision (GPS/baro/range aiding off), i.e. the configuration tests/system/test_optitrack_e2e.py runs, reproducible by hand

• overrides/l4t-optitrack-realrobot.env — deployment override for a real Jetson robot flying on OptiTrack mocap (PX4 EKF2 external vision instead of GPS): the NatNet server/body settings, plus the multi-NIC and FCU-parameter notes that path needs

• Feature notebook workflow (use-feature-notebook skill): every agent-implemented feature gets a local, gitignored notebook/NNN-feature-slug/ entry with a status-tracked design_spec.md (written before coding) and results/ artifacts + self-contained results_summary.md that populate the feature's PR description

• Battery and telemetry display in GCS RQT control panel (voltage and percentage per robot when MAVROS battery topic is bridged)

• TARGET_ARCH build arg (default x86_64) in Dockerfile.robot to arch-parametrize LD_LIBRARY_PATH; docker-compose.yaml passes TARGET_ARCH: aarch64 to the voxl and l4t real-robot image builds

• ros-${ROS_DISTRO}-mavros-extras in the robot image (provides the vision_pose plugin used for external-pose deployments)

• overrides/l4t-px4-realrobot.env — site-agnostic deployment override for a single real PX4 robot on a Jetson (aarch64/l4t)

• integration test tier (tests/integration/, integration mark) with a shared robot_autonomy_stack fixture (robot container, no sim/GPU)

• waypoint_flight system test (tests/system/test_waypoint_flight.py): takeoff → ordered waypoint route via NavigateTask (dispatched as a dense plan) → land, judged on the odometry track by the standalone stdlib-only tests/waypoint_checker.py (in-order corridor arrival within --waypoint-tolerance, final goal within --goal-tolerance, per-waypoint --waypoint-timeout); validated end-to-end in Isaac Sim; serves as the standard acceptance check after integrating or swapping a planner module

• Real-robot PX4 external-vision fusion in natnet_ros2 (OptiTrack mocap → EKF2): mavros_gp_origin (geoid-corrected synthetic GPS origin so local_position.z == OptiTrack z, fixing the ~36 m boot offset), vision_pose_converter, and a PX4 param checker (px4_param_setter, auto_set off by default; on_mismatch warn/halt) — setup guide at docs/robot/px4_external_vision.md

• NatNet server emulator (optitrack.natnet.emulator, protocol core) — pure-Python OptiTrack Motive server emulation so natnet_ros2 can be driven without hardware; host integration tests (tests/integration/natnet/) wire it to the robot client

• Isaac wrapper for the NatNet emulator (USD scene → server) + natnet Pegasus launch scripts, and a dedicated OptiTrack sim e2e test (optitrack mark, tests/system/test_optitrack_e2e.py) that flies a Circle trajectory on mocap EKF2 fusion — GPS, baro and range aiding are disabled for the run, so the OptiTrack stream is the vehicle's only position source and cross-track error scores the whole chain

Changed

• Isaac launch scripts deduplicated onto a shared pegasus_app.PegasusApp base (simulation/isaac-sim/launch_scripts/pegasus_app.py): the six scripts become scenario declarations (~40–170 lines each, net −438 lines) with hooks for NatNet/scene-import extras; behavior verified by full system-test parity (liveliness, sensors, takeoff/hover/land on Isaac). ISAAC_SIM_HEADLESS and ISAAC_SIM_LIVESTREAM now work uniformly in every launch script (previously each was honored by only half of them)

• Launch-workflow docs corrected against actual behavior: ISAAC_SIM_SCENE (nonexistent) replaced by ISAAC_SIM_SCRIPT_NAME/ISAAC_SIM_GUI, getting-started reflects the paused-by-default sim and Foxglove UI, isaac docker.md defaults table matches .env, ms-airsim MAVROS ports/FOV/vehicle naming fixed, AGENTS.md uses the real down/image-build command names

• Unit-test documentation now matches the co-located layout: the add-unit-tests and run-system-tests skills and the testing docs record which runner each language uses (C++ gtests via colcon test under the build_packages mark; Python via the root harness, plus colcon test for ament_python packages), and stop instructing authors to write @pytest.mark.unit by hand — conftest.py applies it by file location

• Ephemeral CI GPU runners spawn via NVIDIA OSMO (not OpenStack); system-tests.yml / docker-build.yml still use airstack-ephemeral

• Default system-test --sim is isaacsim; pass --sim msairsim to opt in to Microsoft AirSim

• -m build_packages CI runs pull cache_* images instead of baking sim images

• docker-build.yml retags unchanged images on VERSION bumps (content fingerprint) instead of always rebuilding; floating cache_* tags still seed PR layer cache

• Automatic OSMO validation runs the pull-only build_packages gate whenever a PR is opened, updated, or reopened; GPU-intensive simulation campaigns (including OptiTrack) are selected through /pytest or workflow_dispatch

• robot-l4t compose service knobs are now env-overridable (AUTONOMY_ROLE, FCU_URL, and the rosbag path via BAG_STORAGE_PATH); FCU_URL unquoted so the literal serial path reaches MAVROS

• zed-l4t image: ZED SDK 4.2 → 5.2 with the coupled ROS deps (zed_msgs 5.2.1, point_cloud_transport(_plugins) 4.x, add backward_ros)

• Unit tests are defined by tests/colcon_unit_test_packages.yaml: conftest.py collects each listed package's co-located test/ dir under --import-mode=importlib and marks it unit (ament lint files are skipped and run under colcon test)

Removed

• Pre-co-location unit-test scaffolding: the six per-layer stub READMEs under tests/robot/ (which instructed authors to add tests in directories tests no longer live in) and tests/sim/motive_emulator/README.md (superseded by simulation/isaac-sim/extensions/optitrack.natnet.emulator/ and tests/integration/natnet/)

Fixed

• barebones_pegasus_launch.py (the documented template script) crashed with NameError: os on construction
• isaac-sim-livestream compose service silently produced a black stream when ISAAC_SIM_SCRIPT_NAME was a multi-drone script (livestream setup existed only in the single-drone scripts)
• NATNET_BODY_NAME/NATNET_TARGET_NAME env overrides documented by the single-drone NatNet script now actually work
• airstack up guards (one-simulator, URDF pairing) validated .env only and were bypassed by --env-file overrides/...; they now check the resolved configuration
• pytest tests/ now collects the co-located unit tests before mark filtering. The old guard skipped injection whenever any path was on the command line, and tests/ is a path — CI collected 97 of 252 items and the Python unit tests ran nowhere. Narrowing (pytest tests/system/test_x.py) still skips injection; repository-root and empty-path collection are rejected
• Empty CI pytest arguments no longer become pytest tests/ "" and recurse through the repository; collection/import, setup/teardown, partial, and interrupted artifacts are reported as non-comparable instead of false 0% simulation-policy results, and metric regression runs only for an identical simulation campaign fingerprint
• Isaac Sim image: PX4 ubuntu.sh no longer fails dpkg configure on the NVIDIA base (ca-certificates / software-properties-common); use --no-nuttx --no-sim-tools like ms-airsim
• Robot image: pin pytest<8.1 and disable launch_testing for colcon unit tests so ROS Jazzy's outdated pytest hook does not abort colcon test
• Robot name resolution now honors a pre-set ROBOT_NAME (e.g. injected via docker compose) instead of always overriding it from the container/hostname mapping (robot/docker/.bashrc)
• Robot name-map catch-all fallback now maps to unknown_robot (valid ROS namespace token) instead of unknown-robot (default_robot_name_map.yaml)
• l4t robot image: replace dustynv's /ros_entrypoint.sh with a passthrough so its prebuilt source-ROS libs (older fastcdr) no longer shadow the apt Jazzy runtime and crash apt-built nodes like MAVROS
• RECORD_BAGS=true never brought the bag recorder up on a robot: logging.launch.xml hardcoded record_bag=false and onboard_autonomy_all.launch.xml includes it with no...

0.18.0

What's Changed

• Add scene_prep utilities and update Isaac Sim launch scripts by @krrishj18 in #324
• Support multi-robot Foxglove port mapping by @krrishj18 in #325
• Update getting started instructions for airstack by @DevRobi in #327
• Introduce ROS2 Actions task executor architecture by @andrewjong in #329
• Integrate Legacy Airsim by @OasisArtisan in #328
• Update AirSim launch instructions and add headless mode support by @OasisArtisan in #331
• Aj/tasks panel by @andrewjong in #332
• Consolidate Tasks, add Chat Task by @andrewjong in #337
• Add airstack test by @andrewjong in #344
• Aj/GitHub ci cd by @andrewjong in #347
• Johnliu/px4 cpu optimization by @JohnYanxinLiu in #348
• Johnliu/rtx lidar update by @JohnYanxinLiu in #351
• Krrish/coord pr by @krrishj18 in #350
• Scene prep bug fix by @krrishj18 in #354

New Contributors

• @DevRobi made their first contribution in #327
• @OasisArtisan made their first contribution in #328

Full Changelog: 0.17.0...0.18.0

0.17.0

What's Changed

• Add battery and telemetry display to GCS control panel by @Rakshitha-Ireddi in #317
• Fixed multi-drone global plan by @krrishj18 in #315
• Enable onboard/offboard autonomy split, and upgrade robot container to ROS2 Jazzy by @andrewjong in #318
• fix docs/tutorials path by @Ph1so in #320
• Add skills and docs by @andrewjong in #321

New Contributors

• @Rakshitha-Ireddi made their first contribution in #317
• @krrishj18 made their first contribution in #315
• @Ph1so made their first contribution in #320

Full Changelog: 0.16.2...0.17.0

0.16.2

Full Changelog: 0.16.1...0.16.2

Fix Isaac Sim paths for 5.1. Create menu now works properly.

0.16.1

What's Changed

• 0.16.1 rc by @andrewjong in #313
• Aj/metrics recording by @andrewjong in #314
• fix lidar sensor hitting propellers by setting min range
• fix standalone mode sensor omnigraph connection

Full Changelog: 0.16.0...0.16.1

0.16.0

What's Changed

• Johnliu/pegasus update by @JohnYanxinLiu in #312
• Isaac Sim and Pegasus upgraded to 5.1.0 on Ubuntu 24. Should now work on NVIDIA rTX 50xx series GPUs
• Docker compose is now dockerized through the AirStack tool, to version 5.x
• KNOWN BUG: scripting mode has a severe drone wobble on takeoff and trajectory following. The wobble is not present in USD mode.

Full Changelog: 0.15.2...0.16.0

0.15.2

What's Changed

• Add change to install nvidia container toolkit by @andrewjong in #309
• Format all documents and add docstrings to DROAN-GL by @andrewjong in #311

Full Changelog: 0.15.1...0.15.2

0.15.1

What's Changed

• configure mavros to just use system time to avoid a bug with its algo… by @jfkeller in #298
• Fixed double isaac-sim launch issue by @JohnYanxinLiu in #300
• Jkeller/droan gl integration by @jfkeller in #301
• Update CMakeLists.txt by @jfkeller in #303
• Jkeller/sudo by @jfkeller in #305
• Jkeller/sudo by @jfkeller in #306
• Jkeller/sudo by @jfkeller in #307

Full Changelog: 0.15.0...0.15.1

0.15.0

What's Changed

Drone dynamics changed to Pegasus.

• Jkeller/rename zed by @jfkeller in #285
• working on real robot as non root by @jfkeller in #289
• Behavior Tree RViz Panel Performance Fix by @andrewjong in #291
• Junbin/planning dev by @YuanJunbin in #290
• updated docker registry to the new airlab-docker.andrew.cmu.edu by @jfkeller in #292
• Jkeller/airlab docker registry by @jfkeller in #293
• Jkeller/airlab docker registry by @jfkeller in #294
• Johnliu/pegasus integration by @JohnYanxinLiu in #295

New Contributors

• @YuanJunbin made their first contribution in #290
• @JohnYanxinLiu made their first contribution in #295

Full Changelog: 0.14.3...0.15.0