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.

​
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.
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 from the setup webapp MAVLink page or Mission Control Hardware tab, then restart the MAVLink service if prompted.
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 status shows video stopped or 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
If the agent is not paired, open the setup URL and 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 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. 
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:
Use the setup webapp Video or Ground Station page to confirm both sides are
on the same channel.
</Accordion>

<Accordion title="Check key match">
Both sides need the same WFB-ng encryption key:
```bash
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 status --json 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