Aerie Architecture

What is Aerie?

Aerie is a REST/WebSocket API that wraps MAVSDK-Python in a FastAPI server. It lets you control a drone (real or simulated) over HTTP — arm, takeoff, fly to coordinates, run missions, stream telemetry — with auto-generated OpenAPI documentation.

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.

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.

The physics and rendering are separate concerns. The "headless" Docker image runs physics without rendering. Our custom image enables both.

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). It's a standard X11 display server, just without physical hardware.
2. x11vnc — captures the virtual framebuffer and serves it over the VNC protocol (port 5900). VNC is a decades-old remote desktop protocol that transmits screen updates as compressed image rectangles.
3. noVNC + websockify — noVNC is a JavaScript VNC client that runs in a browser. websockify translates between VNC's raw TCP protocol and WebSocket, which browsers can connect to. This is served on port 6080.

So the chain is: Gazebo → Xvfb (fake screen) → x11vnc (capture) → websockify (TCP→WebSocket) → your browser.

Aerie API Server

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

• REST endpoints for commands: arm, takeoff, land, goto, missions
• REST endpoints for telemetry polling: position, battery, health
• WebSocket endpoint for real-time telemetry streaming at configurable Hz
• MAVSDK-Python handles the MAVLink protocol details

The API uses a DroneManager singleton that holds the MAVSDK System instance. All routes depend-inject this via FastAPI's Depends().

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
./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
#    (Settings > General > "Use the WSL 2 based engine")

# 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
docker compose up -d --build

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

Then open:

• http://localhost:8000/ — Aerie control panel
• http://localhost:6080/vnc.html — Gazebo 3D view

Note: The Docker container runs Linux (ARM64/AMD64). Docker Desktop handles the translation layer automatically. If you're on an AMD64/Intel machine, remove platform: linux/arm64 from docker-compose.yml or change it to linux/amd64.

Linux

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

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

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

Aerie — MAVSDK REST API for drone control