Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

The agent installs with a single command. It detects your board, installs dependencies, configures systemd services, and starts everything automatically.
Mission Control’s Flash Tool surfaces this install command automatically. See Install paths for the recommended flow per board class.

​
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, Rich, 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 update command: 
ados update
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]"

# Check the CLI surface
ados --help
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 install the package on macOS for development and packaging checks. It will not have systemd, WFB-ng, or hardware GPIO, so hardware behavior must be verified on Linux hardware. 
pip install ados-drone-agent
Or with pipx for an isolated install: 
pipx install ados-drone-agent

​
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)

/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 service and setup status
ados status

# Open the terminal status page and setup URL list
ados
ados shows the local setup webapp URL, service state, MAVLink state, video state, network URLs, and remote access state. Open the setup URL in a browser to finish onboarding.

​
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