System Architecture¶

This document provides a comprehensive overview of the AirStack autonomy system architecture, data flow, and module interactions.

Overview¶

AirStack follows a layered autonomy architecture where data flows through hierarchical processing stages from low-level sensor data to high-level mission execution.

graph TB
    Hardware[Robot Hardware / Simulation] --> Interface

    subgraph "Autonomy Stack"
        Interface[Interface Layer]
        Sensors[Sensors Layer]
        Perception[Perception Layer]
        Local[Local Layer]
        Global[Global Layer]
        Behavior[Behavior Layer]

        Interface --> Sensors
        Sensors --> Perception
        Perception --> Local
        Perception --> Global
        Global --> Local
        Local --> Interface
        Behavior --> Local
        Behavior --> Global
    end

    Interface --> Hardware

Node Types: Perpetual vs Task Executor¶

AirStack nodes fall into two categories that differ in lifecycle, activation, and interface:

Perpetual Nodes¶

Perpetual nodes start at launch and run continuously until shutdown. They receive data over topics and publish results immediately — there is no external activation step. Most of the autonomy stack consists of perpetual nodes.

Examples: state estimator, VDB mapper, disparity expander, trajectory controller, behavior tree tick loop.

Task Executors¶

Task executors are ROS 2 action servers that only do work when an action client sends them a goal. They have a well-defined lifecycle:

stateDiagram-v2
    [*] --> Idle: node starts
    Idle --> Active: goal accepted
    Active --> Idle: succeed / abort
    Active --> Idle: cancel accepted

Property	Perpetual Node	Task Executor
Activation	Always running	On demand via action goal
Interface	ROS topics	ROS 2 action (goal / feedback / result)
Cancellation	N/A	Caller can cancel mid-flight
Progress reporting	N/A	Feedback streamed ~1 Hz
Completion condition	Never	Time limit, area covered, object found, etc.
Typical layer	Perception, Control, World Models	Global/Local Planning

All task action servers are remapped to /{robot_name}/tasks/{task_name} by convention.

Task Cascade¶

High-level tasks (sent by the behavior layer) cascade down through the stack:

graph TD
    BE[behavior_executive] -->|ExplorationTask| RW[random_walk_planner]
    RW -->|NavigateTask| DG[droan_gl]
    DG -->|trajectory_segment_to_add| TC[trajectory_controller]

    style BE fill:#cce5ff
    style TC fill:#cce5ff
    style RW fill:#d4edda
    style DG fill:#d4edda

Blue = perpetual node, green = task executor.

The global-layer task executor (e.g. random_walk_planner) decides where to go and delegates the actual flying to the local-layer task executor (droan_gl or droan_local_planner) via a NavigateTask action, which feeds trajectory segments to the perpetual trajectory controller.

See Task Executors for the full list of task action types and their interfaces.

Layer Architecture¶

Hierarchical Organization¶

The autonomy stack is organized into six layers, each with specific responsibilities:

Layer	Responsibility	Input	Output
Interface	Hardware abstraction, safety monitoring	Commands from control	Robot state, raw sensor data
Sensors	Sensor processing, calibration	Raw sensor data	Processed sensor data
Perception	State estimation, environment understanding	Sensor data	Odometry, depth, features
Local	Reactive planning and control	Odometry, local sensors, global plan	Local trajectories, control commands
Global	Strategic planning and mapping	Global map, robot pose, goals	Global plans, map updates
Behavior	Mission execution, decision making	Mission commands, autonomy state	High-level goals, mode changes

Data Flow Diagram¶

graph LR
    subgraph "Upward Flow (Sensing)"
        HW[Hardware/Sim] -->|Raw Data| IF[Interface]
        IF -->|Sensor Streams| SEN[Sensors]
        SEN -->|Processed Data| PER[Perception]
        PER -->|Odometry| LOC[Local]
        PER -->|Pose| GLO[Global]
    end

    subgraph "Downward Flow (Acting)"
        BEH[Behavior] -->|Goals| GLO
        GLO -->|Global Plan| LOC
        LOC -->|Trajectory| CTRL[Controller]
        CTRL -->|Commands| IF
        IF -->|Actuator Commands| HW
    end

Detailed Layer Architecture¶

Interface Layer¶

Purpose: Abstract hardware/simulation and provide safety monitoring.

graph TB
    MAVROS[MAVROS Interface]
    Safety[Safety Monitor]
    RobotIF[Robot Interface]

    PX4[PX4 Flight Controller] --> MAVROS
    MAVROS --> Safety
    Safety --> RobotIF

    RobotIF -->|State| Perception
    RobotIF -->|Safety Status| Behavior

    Control[Trajectory Controller] -->|Commands| MAVROS
    MAVROS -->|Actuator Commands| PX4

Key Modules:

mavros_interface: MAVLink communication with flight controller
drone_safety_monitor: Safety checks and emergency handling
robot_interface: High-level robot state abstraction

Topics:

Published:
- /[robot]/interface/mavros/state
- /[robot]/interface/mavros/local_position/pose
- /[robot]/interface/battery_state
Subscribed:
- /[robot]/trajectory_controller/cmd_vel

Sensors Layer¶

Purpose: Process and calibrate sensor data.

graph LR
    Camera[Camera Sensors] --> ImgProc[Image Processing]
    Stereo[Stereo Cameras] --> Disparity[Disparity Computation]
    Gimbal[Gimbal] --> Stabilizer[Gimbal Stabilizer]

    ImgProc --> Perception
    Disparity --> Perception
    Stabilizer --> Camera

Key Modules:

camera_param_server: Camera calibration management
gimbal_stabilizer: Gimbal control and stabilization
Sensor drivers and processors

Topics:

Published:
- /[robot]/sensors/[sensor_name]/image
- /[robot]/sensors/[sensor_name]/camera_info
- /[robot]/sensors/front_stereo/disparity

Perception Layer¶

Purpose: Estimate robot state and understand environment.

graph TB
    subgraph "State Estimation"
        VIO[Visual-Inertial Odometry]
        Fusion[Sensor Fusion]
    end

    subgraph "Environment Perception"
        Depth[Depth Estimation]
        Features[Feature Detection]
        Tracking[Object Tracking]
    end

    Sensors -->|Images + IMU| VIO
    Sensors -->|Multi-sensor| Fusion
    VIO --> Odometry[Odometry Output]
    Fusion --> Odometry

    Sensors -->|Stereo| Depth
    Sensors -->|Images| Features
    Features --> Tracking

    Odometry --> Local
    Odometry --> Global
    Depth --> Local

Key Modules:

macvo_ros2: Visual-inertial odometry system

Topics:

Published:
- /[robot]/odometry - Primary state estimate
- /[robot]/perception/macvo/depth
- /[robot]/perception/macvo/features
Subscribed:
- /[robot]/sensors/*/image
- /[robot]/sensors/*/camera_info
- /[robot]/interface/mavros/imu

Local Layer¶

Purpose: Reactive obstacle avoidance and trajectory control.

The local layer has three sub-layers:

graph TB
    subgraph "Local World Models"
        Disparity[Disparity Expansion]
        Graph[Disparity Graph]
        CostMap[Cost Map]

        Disparity --> Graph
        Graph --> CostMap
    end

    subgraph "Local Planners"
        DROAN[DROAN Planner]
        TakeoffLanding[Takeoff/Landing]

        CostMap --> DROAN
    end

    subgraph "Controllers"
        TrajControl[Trajectory Controller]
        AttControl[Attitude Controller]

        DROAN --> TrajControl
        TakeoffLanding --> TrajControl
        TrajControl --> AttControl
    end

    Perception -->|Odometry| DROAN
    Perception -->|Disparity| Disparity
    Global -->|Global Plan| DROAN

    AttControl -->|Commands| Interface

Key Modules:

World Models:
- disparity_expansion: Obstacle detection from stereo
- disparity_graph: Graph-based obstacle representation
- disparity_graph_cost_map: Cost map generation
Planners:
- droan_local_planner: DROAN obstacle avoidance
- takeoff_landing_planner: Specialized maneuvers
- trajectory_library: Trajectory generation utilities
Controllers:
- trajectory_controller: Trajectory tracking
- attitude_controller: Attitude control

Topics:

Subscribed:
- /[robot]/odometry
- /[robot]/global_plan
- /[robot]/sensors/front_stereo/disparity
Published:
- /[robot]/trajectory_controller/trajectory_segment_to_add
- /[robot]/trajectory_controller/look_ahead
- /[robot]/trajectory_controller/tracking_point
- /[robot]/local/cost_map

Global Layer¶

Purpose: Strategic path planning and global mapping.

graph TB
    subgraph "Global World Models"
        VDBMap[VDB Mapping]
        Occupancy[Occupancy Grid]
    end

    subgraph "Global Planners"
        RandomWalk[Random Walk Explorer]
        Ensemble[Ensemble Planner]
    end

    Perception -->|Pose| VDBMap
    Sensors -->|Point Clouds| VDBMap
    VDBMap --> Occupancy

    Occupancy --> RandomWalk
    Occupancy --> Ensemble
    Behavior -->|Goals| RandomWalk
    Behavior -->|Goals| Ensemble

    RandomWalk --> GlobalPlan[Global Plan]
    Ensemble --> GlobalPlan
    GlobalPlan --> Local

Key Modules:

World Models:
- vdb_mapping_ros2: VDB-based 3D mapping
Planners:
- random_walk: Random exploration planner
- ensemble_planner: Multi-planner coordination

Topics:

Subscribed:
- /[robot]/odometry
- /[robot]/sensors/*/pointcloud
- /[robot]/behavior/mission_goal
Published:
- /[robot]/global_plan
- /[robot]/global/map
- /[robot]/global/occupancy

Behavior Layer¶

Purpose: High-level mission execution and decision making.

graph TB
    Mission[Mission Manager] -->|Goals| BT[Behavior Tree]
    BT -->|Evaluate| Conditions{Conditions}
    Conditions -->|True| Actions[Actions]
    Conditions -->|False| Fallback[Fallback]

    Actions -->|Global Goals| Global
    Actions -->|Local Commands| Local
    Actions -->|Mode Changes| Interface

    subgraph "Behavior Tree Components"
        BT
        Conditions
        Actions
        Fallback
    end

    GCS[Ground Control Station] -->|Commands| Mission
    Autonomy[Autonomy State] --> BT

Key Modules:

behavior_tree: Behavior tree framework
behavior_executive: Mission execution engine
rqt_behavior_tree_command: GUI for behavior tree control

Topics:

Subscribed:
- /[robot]/odometry
- /[robot]/interface/mavros/state
- /[robot]/trajectory_controller/trajectory_completion_percentage
Published:
- /[robot]/global/goal
- /[robot]/trajectory_controller/trajectory_override
- /[robot]/behavior/mission_state

Complete Data Flow¶

Autonomous Flight Scenario¶

Here's the complete data flow for an autonomous flight with obstacle avoidance:

sequenceDiagram
    participant BEH as Behavior
    participant GLO as Global Planner
    participant LOC as Local Planner
    participant CTL as Controller
    participant IF as Interface
    participant HW as Hardware/Sim

    Note over BEH: Mission: Navigate to waypoint
    BEH->>GLO: Goal Position
    GLO->>GLO: Plan global path
    GLO->>LOC: Global Plan

    loop Obstacle Avoidance
        HW->>IF: Sensor Data
        IF->>LOC: Disparity Image
        LOC->>LOC: Detect obstacles
        LOC->>LOC: Generate local trajectory
        LOC->>CTL: Trajectory Segment
        CTL->>CTL: Compute control commands
        CTL->>IF: Velocity Commands
        IF->>HW: Actuator Commands
    end

    Note over CTL: Waypoint reached
    CTL->>BEH: Completion notification
    BEH->>BEH: Next waypoint or mission complete

Module Communication Patterns¶

Standard Communication Flow¶

graph LR
    subgraph "Publish-Subscribe Pattern"
        Producer[Producer Module] -->|Publish| Topic[ROS Topic]
        Topic -->|Subscribe| Consumer[Consumer Module]
    end

    subgraph "Service Pattern"
        Client[Client Module] -->|Request| Service[ROS Service]
        Service -->|Response| Client
    end

    subgraph "Action Pattern"
        ActionClient[Action Client] -->|Goal| ActionServer[Action Server]
        ActionServer -->|Feedback| ActionClient
        ActionServer -->|Result| ActionClient
    end

Topic Remapping Strategy¶

Modules use generic topic names internally, which are remapped in launch files:

<!-- In module code: subscribe to "odometry" -->
<!-- In launch file: remap to actual topic -->
<remap from="odometry" to="/$(env ROBOT_NAME)/odometry" />

This enables:

Flexibility: Easy to swap modules
Multi-robot: Each robot has its own namespace
Testing: Mock different topic sources

Coordinate Frames¶

Frame Hierarchy¶

graph TB
    World[world] --> Map[map]
    Map --> Odom[odom]
    Odom --> BaseLink[base_link]
    BaseLink --> BaseLinkStab[base_link_stabilized]
    BaseLinkStab --> Camera[camera_link]
    BaseLinkStab --> Lidar[lidar_link]
    BaseLink --> LookAhead[look_ahead_point]

Standard Frames:

world: Fixed world frame
map: Global map frame (may drift from world)
odom: Odometry frame (continuous, may drift)
base_link: Robot body frame
base_link_stabilized: Stabilized body frame (yaw-only)
camera_link: Camera sensor frame
look_ahead_point: Trajectory tracking reference

Performance Characteristics¶

Typical Update Rates¶

Layer	Module	Rate	Latency
Interface	MAVROS	50 Hz	<5 ms
Sensors	Camera	30 Hz	<10 ms
Sensors	Disparity	15 Hz	<30 ms
Perception	VIO	30 Hz	<20 ms
Local Planner	DROAN	10 Hz	<50 ms
Local Controller	Trajectory	50 Hz	<10 ms
Global Planner	Path	1 Hz	<500 ms
Behavior	BT Tick	10 Hz	<5 ms

Resource Usage (Typical)¶

Component	CPU	Memory	GPU
Full Stack	60-80%	4-6 GB	20-40%
Perception	15-20%	500 MB	10-20%
Local Planning	10-15%	300 MB	5-10%
Global Planning	5-10%	200 MB	0%
Simulation	30-40%	2-3 GB	60-80%

Module Integration Guidelines¶

When adding a new module, follow these integration patterns:

1. Determine Layer Placement¶

Place module in appropriate layer based on its function:

Real-time obstacle avoidance? → Local planning
State estimation? → Perception
Path planning? → Global planning
Mission logic? → Behavior

2. Define Interfaces¶

Specify input and output topics:

Use standard topics when available
Create custom topics with appropriate namespaces
Document expected message rates and latencies

3. Configure Launch Integration¶

Add module to layer bringup with:

Topic remapping
Namespace configuration
Parameter loading
Conditional launching (if needed)

4. Test Integration¶

Verify:

Topics connect correctly
Data flows as expected
Performance meets requirements
Works with other modules

See Integration Checklist for detailed steps.

Multi-Robot Architecture¶

Robot Namespacing¶

Each robot operates in its own namespace:

/robot_1/
  ├── odometry
  ├── global_plan
  ├── trajectory_controller/...
  └── sensors/...

/robot_2/
  ├── odometry
  ├── global_plan
  ├── trajectory_controller/...
  └── sensors/...

Inter-Robot Communication¶

Robots can share information through:

Shared topics (e.g., /team/formation)
ROS 2 Domain Bridge
DDS Router for cross-domain communication

Domain Isolation¶

graph TB
    subgraph "Domain 0 (GCS)"
        GCS[Ground Control Station]
    end

    subgraph "Domain 1 (Robot 1)"
        R1[Robot 1 Stack]
    end

    subgraph "Domain 2 (Robot 2)"
        R2[Robot 2 Stack]
    end

    Router[DDS Router]

    GCS <--> Router
    R1 <--> Router
    R2 <--> Router

References¶

Integration Checklist - Module integration guidelines
AI Agent Guide - Guide for AI agents
Layer Documentation - Detailed layer descriptions
Skills:
- add-ros2-package - Creating packages
- integrate-module-into-layer - Integration workflow