Troubleshooting

This page covers the most common issues you might hit and how to diagnose them. Start with ados or ados status --json, then work through the relevant section below.

First step: check setup status

ados
ados status --json

The terminal status page shows the local setup URL, service states, MAVLink, video, network, remote access, and the next action. The JSON output is useful for support tickets and scripts.

Flight controller not detected

Symptoms: ados status shows MAVLink is not connected. No telemetry appears in Mission Control.

Check the serial connection

Verify the UART cable is connected between the FC and the companion computer. Make sure TX goes to RX and RX goes to TX (crossover). Check voltage levels (most FCs use 3.3V UART; some use 5V TTL, which can damage a 3.3V SBC input).List available serial ports:

ls /dev/tty{S,AMA,ACM,USB}*

If your FC is connected via USB, it usually appears as /dev/ttyACM0 or /dev/ttyUSB0.

Check baud rate

The agent and FC must use the same baud rate. Common values:

ArduPilot: 57600 (default TELEM1) or 921600
PX4: 115200 or 921600
Betaflight: 115200

Set it from the setup webapp MAVLink page or Mission Control Hardware tab, then restart the MAVLink service if prompted.

Check for serial port conflicts

Another process might be holding the serial port. Check:

sudo fuser /dev/ttyS0

If something else is using the port, stop it or configure the agent to use a different port.

Check MAVLink protocol version

ArduPilot defaults to MAVLink 1 on some ports. The agent works with both MAVLink 1 and 2, but if you see garbled data, verify the FC’s SERIALN_PROTOCOL is set to MAVLink (1 or 2).

FC not sending heartbeats

The agent waits for heartbeat messages to confirm the FC is alive. If the FC is not sending heartbeats, check:

Is the FC powered on?
Is the correct serial port configured on the FC side?
Is the FC in a boot loop? (Check FC LED patterns)

Video frozen or not starting

Symptoms: Video feed is black in Mission Control. ados status shows video stopped or error. MediaMTX shows stopped.

Check if a camera is detected

ls /dev/video*

If no /dev/video* devices exist, the camera is not recognized. For USB cameras, check lsusb. For CSI cameras, check that the ribbon cable is seated properly (gold contacts face the PCB on both ends for Radxa boards).

Check the video service

sudo systemctl status ados-video
sudo journalctl -u ados-video -n 50

Look for error messages about ffmpeg, camera access, or MediaMTX.

Check MediaMTX

curl http://localhost:9997/v3/paths/list

If MediaMTX is running and the stream is active, you should see a path entry for main. If MediaMTX is not responding, check its logs:

sudo journalctl -u ados-video --grep "mediamtx" -n 20

Check cgroup resource limits

The video service has a MemoryMax cgroup limit. If ffmpeg or MediaMTX is being OOM-killed, you will see it in the logs:

sudo journalctl -u ados-video --grep "oom\|killed\|cgroup" -n 20

Also check cgroup throttle stats:

cat /sys/fs/cgroup/system.slice/ados-video.service/memory.events

If max is incrementing, the service is hitting its memory limit.

Camera permission denied

The agent user needs access to /dev/video*. The install script adds the user to the video group, but if you installed manually, you may need to:

sudo usermod -aG video $(whoami)

Then log out and back in.

USB camera enumerates at wrong index

Some boards enumerate cameras at /dev/video1 or higher instead of /dev/video0. The agent scans all /dev/video[0-9]* devices, but if you see “no camera found” in logs while a camera exists, check:

v4l2-ctl --list-devices

Cloud disconnected

Symptoms: Drone does not appear in Mission Control. ados status shows cloud as disconnected. No telemetry in the dashboard.

Check internet connectivity

ping -c 3 8.8.8.8
ping -c 3 your-mqtt.example.com   # your configured MQTT broker host

If pings fail, the board has no internet. Check WiFi, Ethernet, or cellular connection.

Check pairing

ados

If the agent is not paired, open the setup URL and follow the Pairing guide.

Check MQTT connection

sudo journalctl -u ados-cloud -n 50

Look for MQTT connection errors. Common issues:

DNS resolution failure (check /etc/resolv.conf)
TLS certificate errors (clock skew on the SBC can cause this)
Auth failure (API key mismatch)

Check clock synchronization

MQTT over TLS requires accurate time. If the SBC clock is off by more than a few minutes, TLS handshakes fail:

date

Fix with NTP:

sudo timedatectl set-ntp true

Check server mode

ados status --json

If remote access is disabled, open the setup webapp Remote Access page and enable the cloud or tunnel path you want to use.

WFB-ng not working

Symptoms: No video link, setup status shows video inactive, ground station sees no signal.

Check the WiFi adapter

lsusb | grep -i realtek

You should see an RTL8812EU device. If not, check the USB connection.

Check the DKMS driver

dkms status

Look for the 88x2eu or rtl8812eu module. If it shows an error, rebuild:

sudo dkms autoinstall

Check channel match

The air unit and ground station must use the same WFB-ng channel. Use the setup webapp Video or Ground Station page to confirm both sides are on the same channel.

Check key match

Both sides need matching WFB-ng keys. The drone transmits with tx.key and the ground station receives with rx.key:

# On the drone
cat /etc/ados/wfb/tx.key

# On the ground station
cat /etc/ados/wfb/rx.key

With auto-bind these are exchanged automatically. If you pair manually, the keys must match across the link.

Agent not starting

Symptoms: ados status returns “Agent is not running.”

Check systemd

sudo systemctl status ados-supervisor
sudo journalctl -u ados-supervisor -n 50

Check Python and venv

/opt/ados/venv/bin/python --version
/opt/ados/venv/bin/pip list | grep ados

If the venv is broken, reinstall:

curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --force

Check disk space

df -h /

If the disk is full, the agent cannot start. Clean up old recordings or logs:

sudo rm -rf /var/ados/recordings/*.mp4
sudo journalctl --vacuum-size=100M

High CPU or temperature

Check which service is using resources

ados status
top -b -n 1 | head -20

If ffmpeg is using high CPU, the video encoder may not be using hardware acceleration. Check that hw_video_codecs in your board profile includes h264_enc.

Thermal throttling

cat /sys/class/thermal/thermal_zone0/temp

Divide by 1000 for Celsius. If above 80C, the SoC is throttling. Add a heatsink or fan. Reduce video resolution or FPS as a software workaround.

High control latency

Symptoms: Manual control feels laggy. Mission Control shows a high or climbing controlRttMs on the drone card.

Check which path the GCS is using

controlRttMs is the round-trip time of the control link, measured against the agent’s GET /api/ping echo. A few tens of milliseconds is a healthy LAN link. Hundreds of milliseconds points to the MQTT relay or a busy network. Seconds means the GCS is on the cloud command-queue poll path, which is fine for monitoring but too slow for hands-on flying.For low-latency manual control, connect over the LAN: serve the GCS on plain HTTP (http://localhost:4000 or http://<lan-ip>:4000) and pair the agent by IP, so the GCS uses the direct WebSocket path instead of the cloud poll.

Confirm the agent is reachable directly

From the GCS machine, check the agent responds quickly:

curl -s -o /dev/null -w "%{time_total}\n" http://<agent-ip>:8080/api/ping

A small number (well under a second) confirms a healthy direct link. If this is slow or times out while the cloud path works, the GCS is correctly falling back to the relay; fix the LAN reachability to get the fast path back.

Getting help

If the troubleshooting steps above do not solve your problem:

Run ados status --json and save the output
Collect relevant service logs: sudo journalctl -u ados-* --since "1h ago" > /tmp/ados-logs.txt
Open an issue on GitHub with the diagnostics output and logs
Join the Discord community for real-time help

​Troubleshooting

​First step: check setup status

​Flight controller not detected

​Video frozen or not starting

​Cloud disconnected

​WFB-ng not working

​Agent not starting

​High CPU or temperature

​High control latency

​Getting help