Aerie Architecture

What is Aerie?

Aerie is a REST/WebSocket API that wraps MAVSDK-Python in a FastAPI server. It lets you control multiple drones (real or simulated) over HTTP — arm, takeoff, fly to coordinates, run missions, stream telemetry — with auto-generated OpenAPI documentation. A single Aerie instance manages all drones via a registry, with each drone addressed by a unique ID.

DroneRegistry (replaces the old singleton)

Previously, Aerie used a DroneManager singleton that held a single MAVSDK System instance. The new DroneRegistry holds a dict[str, System] — one MAVSDK connection per drone ID. Each drone is independently connected and controlled.

MAVSDK-Python supports multiple System() instances in one process, each connecting to a different drone via a separate gRPC server. This means no coordinator server is needed — one Aerie instance handles all drones.

API Route Structure

All drone-specific endpoints are namespaced under /api/v1/drones/{drone_id}/...:

POST   /api/v1/drones                           # Register a new drone
GET    /api/v1/drones                           # List all drones
GET    /api/v1/drones/{drone_id}                # Get drone status
DELETE /api/v1/drones/{drone_id}                # Remove a drone

POST   /api/v1/drones/{drone_id}/action/arm     # Arm specific drone
POST   /api/v1/drones/{drone_id}/action/takeoff  # Takeoff specific drone
GET    /api/v1/drones/{drone_id}/telemetry/all   # Telemetry for specific drone
WS     /api/v1/drones/{drone_id}/ws/telemetry    # Real-time stream for specific drone

Adding a Drone (Flow)

1. Operator calls POST /api/v1/drones with {"drone_id": "alpha", "address": "udpin://0.0.0.0:14540"}
2. Aerie creates a new MAVSDK System(), connects to the drone via MAVLink
3. The drone is stored in the registry and immediately available for commands
4. To remove: DELETE /api/v1/drones/alpha

PX4 Autopilot (Flight Controller)

PX4 is open-source flight controller firmware that runs on real drone hardware. In SITL (Software-In-The-Loop) mode, it runs on a normal computer and simulates the flight controller. It exposes a MAVLink interface on UDP port 14540 — the same binary protocol used by real drones.

PX4 receives commands (arm, takeoff, goto) and sends back telemetry (GPS, battery, attitude). It handles all the low-level flight control: PID loops, sensor fusion, safety checks.

For multi-drone simulation, multiple PX4 instances run in the same container, each with a unique PX4_INSTANCE number. Instance N listens on port 14540 + N.

Gazebo (Physics Engine + 3D Renderer)

Gazebo serves two roles:

1. Physics simulation — simulates gravity, motor thrust, aerodynamics, collisions. PX4 sends motor commands to Gazebo; Gazebo computes what happens physically and sends back simulated sensor data (GPS, IMU, barometer).
2. 3D rendering — renders the drone and world as a 3D scene. This is what you see in the Gazebo window.

All drones share the same Gazebo world, so you can see them all in the 3D view simultaneously.

VNC (Virtual Network Computing)

The challenge: Gazebo renders a GUI, but it's running inside a Docker container with no monitor. The solution is a 3-layer chain:

1. Xvfb (X Virtual Framebuffer) — creates a fake "monitor" in memory. Gazebo renders to this virtual display (display :99).
2. x11vnc — captures the virtual framebuffer and serves it over the VNC protocol (port 5900).
3. noVNC + websockify — noVNC is a JavaScript VNC client that runs in a browser. Served on port 6080.

So the chain is: Gazebo → Xvfb → x11vnc → websockify → your browser.

Aerie API Server

A Python FastAPI application that translates HTTP requests into MAVLink commands:

• DroneRegistry manages multiple MAVSDK System instances (one per drone)
• REST endpoints for commands: arm, takeoff, land, goto, missions — all scoped to {drone_id}
• REST endpoints for telemetry polling: position, battery, health — per drone
• WebSocket endpoints for real-time telemetry streaming — per drone
• MAVSDK-Python handles the MAVLink protocol details

macOS (current setup)

Requires Docker Desktop for Mac. Everything else runs natively.

# Install
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Run (2 drones by default)
./start.sh

# Or run with a specific number of drones
NUM_DRONES=3 ./start.sh

Windows

Requires Docker Desktop for Windows with WSL2 backend enabled.

# In PowerShell or Windows Terminal:

# 1. Install Docker Desktop and enable WSL2 backend

# 2. Clone the repo and set up Python
python -m venv .venv
.venv\Scripts\activate
pip install -e .

# 3. Build and start the simulation container (2 drones)
set NUM_DRONES=2
docker compose up -d --build

# 4. Wait ~40 seconds for PX4 to initialize, then start Aerie
set PYTHONPATH=src
uvicorn aerie.main:app --host 0.0.0.0 --port 8000

Note: On AMD64/Intel machines, change platform: linux/arm64 to linux/amd64 in docker-compose.yml.

Linux

Same as macOS. Install Docker Engine (not Desktop), Python 3.10+, then:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
NUM_DRONES=3 ./start.sh

On AMD64 Linux, change platform: linux/arm64 to linux/amd64 in docker-compose.yml.

Aerie — MAVSDK REST API for multi-drone control