# kestr31/px4-sitl-runner architecture

> Architecture diagram of the GitHub repository kestr31/px4-sitl-runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kestr31/px4-sitl-runner
- Repository: https://github.com/kestr31/px4-sitl-runner

## Overview

Step 1. Identify Project Type and Purpose
- This is a “Containerized PX4 SITL Simulation & Development Script Tools” project.
- Purpose: Provide a set of Docker-Compose definitions, environment settings, and wrapper scripts to spin up PX4 “Software In The Loop” (SITL) simulations with supporting components (Gazebo Classic, AirSim, QGroundControl, ROS 2 bridges, DDS, etc.).
- Target users: drone/autopilot developers who need repeatable, containerized simulation environments.

Step 2. Analyze the File Structure
- Top‐level:
- compose.yml – Docker Compose manifest orchestrating multiple containers
- envs/ – environment variable files per component (airsim.env, gazebo-classic.env, px4.env, qgc.env, ros2.env, common.env)
- scripts/ – bash scripts grouped by component (px4/, gazebo-classic/, airsim/, ros2/, qgc/) and utility scripts (run.sh, stop.sh, clean.sh, initial-setup.sh)
- Patterns:
- Each component has its own folder of build/debug/launch scripts.
- Common functions and environment setup centralized under scripts/include/.
- Docker Compose binds together multiple “service” containers using those env files.

Step 3. Examine README for Additional Insights
- Confirms: uses Docker, Docker Compose, NVIDIA GPU support, QGroundControl, ROS 2, uXRCE‐DDS.

a. Main Components
1. Host Machine
- Ubuntu (Linux), NVIDIA drivers, Docker Engine & NVIDIA Container Toolkit
2. Docker Compose Orchestrator (compose.yml)
3. Containers (services):
- PX4 SITL Container
- Gazebo Classic Simulator Container
- AirSim Simulator Container
- QGroundControl (QGC) Container
- ROS 2 Container (with uXRCE‐DDS bridge)
4. Shared Resources:
- Environment Variables (envs/*.env)
- Common volume mounts (X11 socket, GPU device nodes)
- Networking (Docker networks, exposed ports)
b. Relationships & Interactions
- PX4 SITL ↔ Gazebo Classic: MAVLink telemetry over UDP (ports 14540/14557).
- PX4 SITL ↔ AirSim: SITL-AirSim plugin over TCP/UDP.
- PX4 SITL ↔ ROS 2: via uXRCE-DDS bridge (ROS 2 → MAVLink).
- PX4 SITL ↔ QGC: Telemetry port for Ground Control UI.
- All containers share the same Docker network; data flows via mapped ports.
c. Architectural Patterns & Key Principles
- Container-per-component (microservices-like) for isolation.
- Environment-injection via .env files for parameterizing each service.
- Wrapper scripts to abstract Docker commands (build, run, debug).
- Single Compose file to manage multi-container workflow.
d. Relevant Technologies
- Docker & Docker Compose
- NVIDIA Container Toolkit
- PX4 SITL (C++ autopilot)
- Gazebo Classic (C++ physics sim)
- AirSim (Unreal Engine)
- QGroundControl (Qt)
- ROS 2 + micro-ROS bridge (uXRCE-DDS)

- Separation of concerns:
- “Compute” containers (PX4 SITL, ROS 2)
- “Visualization/Sim” containers (Gazebo Classic, AirSim, QGC)
- Common networking backbone and shared GPU/Display mounts.
- Bootstrap flow: initial-setup.sh → docker-compose up → individual component startup scripts.

Step 6. Diagramming Guidelines
- Annotate:
- Ports (e.g., UDP:14540↔14557)
- Mounted volumes (e.g., /dev/nvidia0, /tmp/.X11-unix).
- Environment variables loaded per service.

Step 7. Don’t Overthink—Be Detailed
- Break each container into sub-components if needed (e.g., within PX4 SITL: SITL binary, Gazebo plugin).
- Wrapper script layer (scripts/*.sh) feeding into Compose.
- Every top-level directory (envs/, scripts/) is represented in the workflow.

- At the top: Host OS & Docker Engine.
- Middle: Docker Compose control plane.
- Below: five service containers, each labeled with its role and key ports.
- Side annotations: env files, bind mounts, GPU/Display passthrough.

This layout will clearly capture the containerized simulation architecture and the relationships among PX4 SITL, Gazebo Classic, AirSim, QGC, and ROS 2.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Host and Docker
    Host["Host OS & Docker Engine"]:::host
    Host --> Compose["Docker Compose Orchestrator"]:::orchestrator

    %% Wrapper Utility Scripts feeding Compose
    subgraph "Wrapper Utility Scripts"
        direction TB
        InitialSetup["initial-setup.sh"]:::wrapper
        Run["run.sh"]:::wrapper
        Stop["stop.sh"]:::wrapper
        Clean["clean.sh"]:::wrapper
        Reset["reset.sh"]:::wrapper
    end
    InitialSetup --> Compose
    Run --> Compose
    Stop --> Compose
    Clean --> Compose
    Reset --> Compose

    %% Shared Environment Variables
    EnvCommon["common.env"]:::env
    EnvCommon --> Compose

    %% Common Script Includes
    subgraph "Common Script Includes"
        direction TB
        CommonEnv["commonEnv.sh"]:::script
        CommonFcn["commonFcn.sh"]:::script
        SITLControl["sitlControl.sh"]:::script
    end
    CommonEnv --> Compose
    CommonFcn --> Compose
    SITLControl --> Compose

    %% Containers Layer
    subgraph "Containers" 
        direction TB

        subgraph "Compute (Blue)" 
            direction TB
            PX4["PX4 SITL Container"]:::compute
            ROS2["ROS 2 Container"]:::compute
        end

        subgraph "Simulation Engines (Green)"
            direction TB
            Gazebo["Gazebo Classic Simulator"]:::simulation
            AirSim["AirSim Simulator"]:::simulation
        end

        subgraph "Visualization/UI (Orange)"
            direction TB
            QGC["QGroundControl Container"]:::ui
        end
    end

    %% Compose to Containers
    Compose --> PX4
    Compose --> Gazebo
    Compose --> AirSim
    Compose --> ROS2
    Compose --> QGC

    %% Environment and Scripts for PX4
    PX4Env["px4.env"]:::env
    PX4Scripts["scripts/px4/"]:::script
    PX4Env --> PX4
    PX4Scripts --> PX4

    %% PX4 interactions
    PX4 <-->|UDP:14540/14557 MAVLink| Gazebo
    PX4 <-->|TCP/UDP SITL-AirSim| AirSim
    PX4 <-->|uXRCE-DDS bridge| ROS2
    PX4 <-->|Telemetry port| QGC

    %% Environment and Scripts for Gazebo
    GazeboEnv["gazebo-classic.env"]:::env
    GazeboScripts["scripts/gazebo-classic/"]:::script
    GazeboEnv --> Gazebo
    GazeboScripts --> Gazebo

    %% Environment and Scripts for AirSim
    AirSimEnv["airsim.env"]:::env
    AirSimScripts["scripts/airsim/"]:::script
    AirSimEnv --> AirSim
    AirSimScripts --> AirSim

    %% Environment and Scripts for ROS2
    ROS2Env["ros2.env"]:::env
    ROS2Scripts["scripts/ros2/"]:::script
    ROS2Env --> ROS2
    ROS2Scripts --> ROS2

    %% Environment and Scripts for QGC
    QGCEnv["qgc.env"]:::env
    QGCScripts["scripts/qgc/"]:::script
    QGCEnv --> QGC
    QGCScripts --> QGC

    %% Network and Resources Annotation
    subgraph "Shared Resources"
        direction TB
        GPU["/dev/nvidia0"]:::resource
        Display["/tmp/.X11-unix"]:::resource
        Network["Docker Network & Ports"]:::resource
    end
    GPU -.-> PX4
    GPU -.-> Gazebo
    GPU -.-> AirSim
    Display -.-> Gazebo
    Display -.-> AirSim
    Network -.-> PX4
    Network -.-> Gazebo
    Network -.-> AirSim
    Network -.-> ROS2
    Network -.-> QGC

    %% Click Events
    click Compose "https://github.com/kestr31/px4-sitl-runner/blob/main/compose.yml"
    click EnvCommon "https://github.com/kestr31/px4-sitl-runner/blob/main/envs/common.env"
    click PX4Env "https://github.com/kestr31/px4-sitl-runner/blob/main/envs/px4.env"
    click PX4Scripts "https://github.com/kestr31/px4-sitl-runner/tree/main/scripts/px4/"
    click GazeboEnv "https://github.com/kestr31/px4-sitl-runner/blob/main/envs/gazebo-classic.env"
    click GazeboScripts "https://github.com/kestr31/px4-sitl-runner/tree/main/scripts/gazebo-classic/"
    click AirSimEnv "https://github.com/kestr31/px4-sitl-runner/blob/main/envs/airsim.env"
    click AirSimScripts "https://github.com/kestr31/px4-sitl-runner/tree/main/scripts/airsim/"
    click QGCEnv "https://github.com/kestr31/px4-sitl-runner/blob/main/envs/qgc.env"
    click QGCScripts "https://github.com/kestr31/px4-sitl-runner/tree/main/scripts/qgc/"
    click ROS2Env "https://github.com/kestr31/px4-sitl-runner/blob/main/envs/ros2.env"
    click ROS2Scripts "https://github.com/kestr31/px4-sitl-runner/tree/main/scripts/ros2/"
    click CommonEnv "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/include/commonEnv.sh"
    click CommonFcn "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/include/commonFcn.sh"
    click SITLControl "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/include/sitlControl.sh"
    click InitialSetup "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/initial-setup.sh"
    click Run "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/run.sh"
    click Stop "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/stop.sh"
    click Clean "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/clean.sh"
    click Reset "https://github.com/kestr31/px4-sitl-runner/blob/main/scripts/reset.sh"

    %% Styles
    classDef host fill:#EEEEEE,stroke:#333,stroke-width:1px;
    classDef orchestrator fill:#FFD966,stroke:#333,stroke-width:1px;
    classDef compute fill:#A4C2F4,stroke:#333,stroke-width:1px;
    classDef simulation fill:#B6D7A8,stroke:#333,stroke-width:1px;
    classDef ui fill:#F9CB9C,stroke:#333,stroke-width:1px;
    classDef middleware fill:#C9C9FF,stroke:#333,stroke-width:1px;
    classDef env fill:#D9D9D9,stroke:#333,stroke-width:1px;
    classDef script fill:#FFF2CC,stroke:#333,stroke-width:1px;
    classDef wrapper fill:#F4CCCC,stroke:#333,stroke-width:1px;
    classDef resource fill:#EAD1DC,stroke:#333,stroke-width:1px;
```
