> ## 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

> Common problems and how to fix them: FC not detected, video frozen, cloud disconnected.

# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    ls /dev/tty{S,AMA,ACM,USB}*
    ```

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

  <Accordion title="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.
  </Accordion>

  <Accordion title="Check for serial port conflicts">
    Another process might be holding the serial port. Check:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo fuser /dev/ttyS0
    ```

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

  <Accordion title="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).
  </Accordion>

  <Accordion title="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)
  </Accordion>
</AccordionGroup>

## Video frozen or not starting

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

<AccordionGroup>
  <Accordion title="Check if a camera is detected">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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).
  </Accordion>

  <Accordion title="Check the video service">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo systemctl status ados-video
    sudo journalctl -u ados-video -n 50
    ```

    Look for error messages about ffmpeg, camera access, or MediaMTX.
  </Accordion>

  <Accordion title="Check MediaMTX">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo journalctl -u ados-video --grep "mediamtx" -n 20
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo journalctl -u ados-video --grep "oom\|killed\|cgroup" -n 20
    ```

    Also check cgroup throttle stats:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    cat /sys/fs/cgroup/system.slice/ados-video.service/memory.events
    ```

    If `max` is incrementing, the service is hitting its memory limit.
  </Accordion>

  <Accordion title="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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo usermod -aG video $(whoami)
    ```

    Then log out and back in.
  </Accordion>

  <Accordion title="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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    v4l2-ctl --list-devices
    ```
  </Accordion>
</AccordionGroup>

## Cloud disconnected

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

<AccordionGroup>
  <Accordion title="Check internet connectivity">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Accordion>

  <Accordion title="Check pairing">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    ados
    ```

    If the agent is not paired, open the setup URL and follow the [Pairing](/drone-agent/pairing) guide.
  </Accordion>

  <Accordion title="Check MQTT connection">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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)
  </Accordion>

  <Accordion title="Check clock synchronization">
    MQTT over TLS requires accurate time. If the SBC clock is off by more than a few minutes, TLS handshakes fail:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    date
    ```

    Fix with NTP:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo timedatectl set-ntp true
    ```
  </Accordion>

  <Accordion title="Check server mode">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Accordion>
</AccordionGroup>

## WFB-ng not working

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

<AccordionGroup>
  <Accordion title="Check the WiFi adapter">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lsusb | grep -i realtek
    ```

    You should see an RTL8812EU device. If not, check the USB connection.
  </Accordion>

  <Accordion title="Check the DKMS driver">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dkms status
    ```

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

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo dkms autoinstall
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Check key match">
    Both sides need matching WFB-ng keys. The drone transmits with `tx.key` and the ground station receives with `rx.key`:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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.
  </Accordion>
</AccordionGroup>

## Agent not starting

**Symptoms:** `ados status` returns "Agent is not running."

<AccordionGroup>
  <Accordion title="Check systemd">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo systemctl status ados-supervisor
    sudo journalctl -u ados-supervisor -n 50
    ```
  </Accordion>

  <Accordion title="Check Python and venv">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    /opt/ados/venv/bin/python --version
    /opt/ados/venv/bin/pip list | grep ados
    ```

    If the venv is broken, reinstall:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash -s -- --force
    ```
  </Accordion>

  <Accordion title="Check disk space">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    df -h /
    ```

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

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo rm -rf /var/ados/recordings/*.mp4
    sudo journalctl --vacuum-size=100M
    ```
  </Accordion>
</AccordionGroup>

## High CPU or temperature

<AccordionGroup>
  <Accordion title="Check which service is using resources">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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`.
  </Accordion>

  <Accordion title="Thermal throttling">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Accordion>
</AccordionGroup>

## High control latency

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Confirm the agent is reachable directly">
    From the GCS machine, check the agent responds quickly:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Accordion>
</AccordionGroup>

## 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](https://github.com/altnautica/ADOSDroneAgent/issues) with the diagnostics output and logs
4. Join the [Discord community](https://discord.gg/uxbvuD4d5q) for real-time help