Skip to main content

​
Installation

The agent installs with a single command. It detects your board, installs dependencies, configures systemd services, and starts everything automatically.

​
Quick install

SSH into your companion computer and run: 
curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash
That is it. The script handles everything from there.
The install script requires root access. It installs to /opt/ados/, creates config at /etc/ados/, and registers systemd services. On boards without systemd (rare), it sets up a process manager fallback.

​
What the install script does

1

Detect the board

Reads /proc/device-tree/model and matches against the 17 built-in board profiles. Sets the tier and enables the right features for your hardware.
2

Install system packages

Installs Python 3.11+, pip, virtualenv, and any board-specific packages (like the RTL8812EU DKMS driver for WFB-ng). Uses apt on Debian/Ubuntu systems.
3

Create the virtual environment

Sets up a Python venv at /opt/ados/venv/ and installs the ados-drone-agent package from PyPI along with all dependencies (pymavlink, FastAPI, uvicorn, paho-mqtt, structlog, Textual, and more).
4

Generate device identity

Creates a unique device ID at /etc/ados/device-id using a chained fallback: Python uuid, OpenSSL random, or hostname-timestamp-pid. This ID is used for cloud pairing and mDNS.
5

Write default config

Creates /etc/ados/config.yaml with defaults tuned for your detected board. Serial port, baud rate, video resolution, and tier are all pre-filled.
6

Install systemd services

Copies service unit files to /etc/systemd/system/ and enables them. The supervisor service starts at boot and manages all child services.
7

Start the agent

Runs systemctl start ados-supervisor which brings up the full service tree: MAVLink proxy, REST API, video pipeline (if a camera is detected), cloud relay, health monitor, and everything else your tier supports.

​
Install with pairing

If you have a pairing code from ADOS Mission Control, include it during install: 
curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --pair YOUR_CODE
This pairs the agent to your cloud account during installation. The drone will appear in your Mission Control dashboard as soon as it connects.

​
Install a specific branch

For development or testing a feature branch: 
curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --branch feature-name

​
Upgrade an existing installation

To upgrade to the latest version without losing your config: 
curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --upgrade
Or use the built-in OTA command: 
ados upgrade
Both methods preserve /etc/ados/config.yaml and your pairing state.

​
Install from source

For contributors and developers who want to modify the agent code: 
# Clone the repo
git clone https://github.com/altnautica/ADOSDroneAgent.git
cd ADOSDroneAgent

# Create a virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run the agent
ados start
For deployment on actual hardware, always use the install script instead of pip install -e. The install script catches packaging bugs (missing data files, broken entry points) that editable installs skip silently. Editable installs are for local development on your laptop only.

​
Install on macOS (for development)

You can run the agent on macOS for development and testing. It will not have systemd, WFB-ng, or hardware GPIO, but the REST API, demo mode, CLI, and TUI all work. 
pip install ados-drone-agent
Or with pipx for an isolated install: 
pipx install ados-drone-agent
Then start in demo mode: 
ados demo
Demo mode generates simulated telemetry so you can test the GCS connection, REST API, and TUI without a flight controller.

​
Uninstall

On Linux (removes services, binary, and data, keeps config): 
ados uninstall
To remove everything including config: 
ados uninstall --purge
On macOS: 
ados uninstall
The CLI auto-detects whether you installed with pip, pipx, or uv and uses the matching uninstall command.

​
Directory layout after install

/opt/ados/                  # Installation root
  venv/                     # Python virtual environment
  models/                   # Vision engine models (if Tier 4)

/etc/ados/                  # Configuration
  config.yaml               # Main config file
  device-id                 # Unique device identifier
  pairing.json              # Cloud pairing state
  certs/                    # TLS certificates (if enabled)
  suites/                   # Suite YAML manifests

/var/ados/                  # Runtime data
  scripts/                  # User Python scripts
  recordings/               # Video recordings
  logs/flights/             # Flight log archive

/run/ados/                  # Unix domain sockets (tmpfs)
  mavlink.sock              # Binary MAVLink IPC
  state.sock                # JSON telemetry IPC

/usr/local/bin/ados         # CLI symlink

​
Verifying the installation

After install, check that everything is running: 
# Check the agent version
ados version

# Check service status
ados status

# Full diagnostics dump
ados diag
The ados diag command prints board detection results, system resources, service states, FC connection status, network interfaces, and installed dependency versions. This is the first thing to run if something looks wrong.

​
Requirements

RequirementMinimumRecommended
OSDebian 11+ or Ubuntu 22.04+ (arm64/armv7l)Debian 12 or Ubuntu 24.04
Python3.113.11 or 3.12
RAM64 MB (Tier 1)2 GB+ (Tier 3/4)
Storage500 MB4 GB+
NetworkSerial UART to FC+ WiFi/Ethernet/4G