Skip to main content

​
Troubleshooting

This page covers the most common issues you might hit and how to diagnose them. Start with ados diag for a full system dump, then work through the relevant section below.

​
First step: run diagnostics

ados diag
This prints board detection, OS info, network interfaces, service states, FC connection, disk usage, RAM, CPU, temperature, and installed dependencies. Read it top to bottom. Most problems show up here.

​
Flight controller not detected

Symptoms: ados status shows FC: False. No telemetry in Mission Control. MAVLink screen in TUI shows “disconnected.”
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.
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 in config:
ados set mavlink.baud_rate 115200
sudo systemctl restart ados-mavlink
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.
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 video shows State: idle or State: error. MediaMTX shows stopped. 
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).
sudo systemctl status ados-video
sudo journalctl -u ados-video -n 50
Look for error messages about ffmpeg, camera access, or MediaMTX.
curl http://localhost:9997/v3/paths/list
If MediaMTX is running and the stream is active, you should see a path entry for cam. If MediaMTX is not responding, check its logs:
sudo journalctl -u ados-video --grep "mediamtx" -n 20
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.
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.
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. 
ping -c 3 8.8.8.8
ping -c 3 mqtt.altnautica.com
If pings fail, the board has no internet. Check WiFi, Ethernet, or cellular connection.
ados pair
If the agent is not paired, it will not connect to the cloud. Follow the Pairing guide.
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)
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

ados config server.mode
If it says disabled, the cloud relay is turned off. Set it to cloud:
ados set server.mode cloud
sudo systemctl restart ados-cloud

​
WFB-ng not working

Symptoms: No video link, ados link shows State: inactive, ground station sees no signal. 
lsusb | grep -i realtek
You should see an RTL8812EU device. If not, check the USB connection.
dkms status
Look for the 88x2eu or rtl8812eu module. If it shows an error, rebuild:
sudo dkms autoinstall
The air unit and ground station must use the same WFB-ng channel:
ados config video.wfb.channel
Make sure both sides are on the same channel (default: 149).
Both sides need the same WFB-ng encryption key:
cat /etc/ados/wfb.key
Compare the key on the air unit and ground station. They must be identical.

​
Agent not starting

Symptoms: ados status returns “Agent is not running.” 
sudo systemctl status ados-supervisor
sudo journalctl -u ados-supervisor -n 50

/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

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

ados health
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.
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.

​
Getting help

If the troubleshooting steps above do not solve your problem:
  1. Run ados diag and save the output
  2. Collect relevant service logs: sudo journalctl -u ados-* --since "1h ago" > /tmp/ados-logs.txt
  3. Open an issue on GitHub with the diagnostics output and logs
  4. Join the Discord community for real-time help