How kestr31/px4-sitl-runner works
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.