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 ground station problems and their fixes. If your issue is not listed here, check the agent logs or ask in the Discord community.
For mesh-specific failures (relays not pairing, batman-adv not coming up, partition recovery, gateway selection), see Mesh Troubleshooting. The entries below cover single-node issues.

​
No video from the drone

Symptom: The ground station is running, your laptop is connected, but the video feed is black or shows “No video.”
Possible causeHow to checkFix
Drone not pairedOLED Link screen shows “No drone”Run the pairing flow from the setup webapp or OLED menu
Drone powered off or out of rangeOLED Link screen shows RSSI ”---“Power on the drone or move closer
Wrong WFB-ng channelDrone and ground on different channelsMatch channels in the Radio config on both sides
RTL8812EU not plugged inlsusb does not show RTL8812Plug in the USB WiFi adapter
DKMS driver not built`dmesggrep 8812` shows errorsReinstall with install.sh --upgrade
MediaMTX not runningsystemctl status ados-mediamtx-gs shows failedCheck logs with journalctl -u ados-mediamtx-gs -n 50
# Quick diagnostic commands
ados status              # Check all services
journalctl -u ados-wfb-rx -n 30  # WFB-ng receiver logs

​
WiFi AP not broadcasting

Symptom: Your phone or laptop cannot find the ADOS-GS-XXXX network.
Possible causeHow to checkFix
AP service not startedsystemctl status ados-wifi-apCheck if the ground-station profile was detected. Run ados status
WiFi AP disabledOLED Net screen shows “AP: off”Press B2 long-press to toggle AP, or enable via setup webapp
WiFi radio conflictiw dev shows no AP interfaceMake sure hostapd is installed. Run install.sh --upgrade
5 GHz selected on Pi 4BPi 4B 5 GHz AP mode is unreliableSwitch to 2.4 GHz in the Radio config

​
Laptop cannot reach the ground station after joining WiFi

Symptom: You joined the AP but http://192.168.4.1:4000 does not load.
1

Check your IP

Make sure your laptop got an IP on the 192.168.4.x subnet. If it has a 169.254.x.x address, dnsmasq is not running.
# On the ground station
systemctl status dnsmasq
2

Check the agent API

Try pinging the ground station:
ping 192.168.4.1
If ping works but the browser does not load, try http://192.168.4.1:8080/api/v1/status to see if the REST API is responding.
3

Check Mission Control

If the REST API responds but port 4000 does not, Mission Control may not be installed locally on the ground node. Use http://192.168.4.1:8080/ (the agent API) or http://setup.ados.local/ (the setup webapp) instead.

​
USB tether not working

Symptom: You plugged in a USB-C cable but no new network interface appeared on your laptop.
Possible causeHow to checkFix
Power-only cableTry a known data cableReplace with a cable explicitly rated for USB data
USB gadget service not runningsystemctl status ados-usb-gadgetCheck that dtoverlay=dwc2 is in /boot/firmware/config.txt and reboot
Old Windows 10 buildDevice Manager shows yellow exclamationInstall the RNDIS driver from the setup webapp help page
Laptop providing insufficient powerGround Agent brownouts under loadUse a separate wall adapter or USB-C power bank
If USB tether works while idle but drops when video starts, test with separate power before changing network settings. See Power and Runtime.

​
OLED is blank

Symptom: The ground station is running but the OLED shows nothing.
Possible causeHow to checkFix
I2C not enabledsudo i2cdetect -y 1 shows no device at 0x3CEnable I2C in raspi-config > Interface Options > I2C, then reboot
Wiring issuesudo i2cdetect -y 1 shows nothingCheck SDA, SCL, VCC (3.3V), and GND connections
Wrong I2C addressDevice shows at 0x3D instead of 0x3CEdit /etc/ados/config.yaml to set oled.address: 0x3D
OLED service not runningsystemctl status ados-oledCheck logs with journalctl -u ados-oled -n 20

​
Profile detected incorrectly

Symptom: The agent started in drone (air) profile instead of ground-station, or vice versa. Check the fingerprint snapshot: 
cat /etc/ados/profile.conf
This shows the detected profile, the ground and air scores, and which signals contributed. Common causes of wrong detection:
  • A flight controller is plugged into the SBC via USB (raises the air score)
  • No OLED or buttons wired (lowers the ground score)
  • Ambiguous setup (both FC and OLED present)
To force the correct profile: 
sudo ados profile set ground-station
sudo reboot

​
Android shows “No internet” and disconnects

Symptom: After joining the WiFi AP, Android keeps dropping the connection or showing “no internet” warnings. The ground station serves 204 No Content responses to Android’s connectivity probes. If Android still complains:
  1. Tap “Stay connected” or “Use without internet” on the notification
  2. In Android WiFi settings, tap the network > Advanced > “Use this network” or disable “Auto-switch to mobile data”
  3. If the captive portal page does not appear automatically, open Chrome and navigate to http://192.168.4.1/
On some Android devices, you may need to disable “Smart network switch” or “Wi-Fi assistant” in WiFi settings to prevent Android from preferring mobile data over a network without internet.

​
High video latency

Symptom: Video works but has noticeable delay (more than 150 ms).
Possible causeFix
WiFi AP congestion (many clients)Reduce to 1-2 video viewers, or switch to USB tether
2.4 GHz interferenceMove to a less crowded channel, or use 5 GHz AP on supported boards
Ground station CPU overloadedCheck ados status and the setup webapp System page. Lower video resolution to 720p
Browser hardware decode not enabledIn Chrome, check chrome://gpu for “Video Decode: Hardware accelerated”
WFB-ng packet lossCheck the OLED Link screen for FEC lost packets. Reposition antennas

​
HDMI kiosk shows a blank screen

Symptom: Monitor is connected but shows nothing or a black screen.
Possible causeFix
No display device detectedCheck that /dev/dri/card0 exists. Make sure HDMI is plugged in before boot
Cage compositor not installedRun sudo apt install cage chromium and reboot
Mission Control not installed locallyThe kiosk needs a local MC build. Run install.sh --upgrade to install it
Resolution mismatchSSH in, open the setup webapp, and try setting resolution to 720p

​
Factory reset

If nothing else works, you can reset the ground station to factory defaults:
  • OLED: Hold B4 for 10 seconds, confirm by holding B4 again for 3 seconds
  • Setup webapp: Advanced > Factory Reset
This erases pairing keys, network config, and all custom settings. The ground station reboots to the first-boot state. You will need to pair with your drone again.

​
Getting help

  • Agent logs: journalctl -u ados-supervisor -n 100 shows the supervisor log. Replace ados-supervisor with any service name.
  • Status JSON: ados status --json captures setup, services, network, MAVLink, video, and remote access state. Attach it when reporting bugs.
  • Discord: discord.gg/uxbvuD4d5q for community support
  • GitHub Issues: github.com/altnautica/ADOSDroneAgent/issues for bug reports