Troubleshooting

Start with the health check:

~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn status --live

If it reports Overall: OK, the services and basic system checks are healthy. If it reports WARN or FAIL, use the matching section below.

Service will not start

Check the service state:

sudo systemctl status aero-pi-ogn-rf.service aero-pi-ogn-decode.service --no-pager

Check recent logs:

sudo journalctl -u aero-pi-ogn-rf.service -u aero-pi-ogn-decode.service -n 100 --no-pager

Restart the receiver:

sudo systemctl restart aero-pi-ogn-receiver.target

Verify again:

~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn status --live

If the services still fail, validate and render the configuration again:

sudo /home/$(whoami)/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn config validate --config /etc/aero-pi-ogn-receiver/config.yaml
sudo /home/$(whoami)/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn config render --config /etc/aero-pi-ogn-receiver/config.yaml --output /etc/aero-pi-ogn-receiver/rtlsdr-ogn.conf
sudo systemctl restart aero-pi-ogn-receiver.target

RTL-SDR USB receiver is missing

Check USB detection:

lsusb

Check receiver health:

~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn status --live

A missing USB receiver normally appears as:

usb receiver        FAIL     no RTL-SDR USB device found

Try these checks:

• Re-seat the RTL-SDR dongle.
• Try another USB port.
• Remove unneeded USB devices.
• Reboot the Pi.
• Test with a powered USB hub if the Pi power supply is marginal.

Power or throttling issues

The RTL-SDR dongle is powered by the Raspberry Pi USB port. A weak power supply can cause USB resets, RF service restarts, high temperature, or unstable decoder behavior.

Check the current and historical Pi power state:

vcgencmd get_throttled
vcgencmd measure_temp

Useful get_throttled bits:

0x1      under-voltage is currently detected
0x2      ARM frequency is currently capped
0x4      system is currently throttled
0x10000  under-voltage has occurred since boot
0x20000  ARM frequency capping has occurred since boot
0x40000  throttling has occurred since boot

Historical bits stay set until reboot. For a clean comparison, record the value, reboot, run the receiver for a representative period, then check again.

Status is OK but no aircraft appear

Run these checks:

~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn status --live
~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn aircraft --watch 5
~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn logs traffic --follow

This pattern usually means the software is alive but the receiver is not decoding useful traffic:

status --live      Overall: OK
aircraft --watch   No aircraft currently tracked by the local decoder.
logs traffic       APRS status repeatedly reports 0/0Acfts[1h]

Possible causes:

• No FLARM-equipped aircraft are nearby.
• The antenna is disconnected or not suitable for 868 MHz.
• The coax, adapter, or connector is damaged.
• The antenna location is shielded or too low.
• An active antenna or LNA is not powered correctly.
• radio.bias_tee is wrong for the connected hardware.

Confirm with a known nearby aircraft when possible.

Antenna or RF-path problem

Follow the RF logs:

~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn logs rf --follow

Example RF noise line:

BkgNoise = 4.1dB, Gain = 49.6dB [28]

Interpretation:

Very low or flat BkgNoise + no aircraft
  Possible disconnected antenna, broken coax, bad adapter, or wrong antenna.

Very high or unstable BkgNoise + no/few aircraft
  Possible overload, bad LNA, active antenna power issue, local interference, or wrong bias tee setting.

Only very close aircraft appear
  Possible poor antenna placement, damaged antenna, lossy cable, water ingress, bad ground plane, or antenna not tuned for 868 MHz.

The practical field test is to run aero-pi-ogn aircraft --watch 5 while a known nearby aircraft with working FLARM is transmitting.

Configuration errors

Validate the YAML file:

sudo /home/$(whoami)/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn config validate --config /etc/aero-pi-ogn-receiver/config.yaml

Edit the file:

sudo nano /etc/aero-pi-ogn-receiver/config.yaml

Render the native OGN config again:

sudo /home/$(whoami)/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn config render --config /etc/aero-pi-ogn-receiver/config.yaml --output /etc/aero-pi-ogn-receiver/rtlsdr-ogn.conf

Restart the receiver:

sudo systemctl restart aero-pi-ogn-receiver.target

Package or dependency issues

Reinstall the Python package:

sudo systemctl stop aero-pi-ogn-receiver.target
~/aero-pi-ogn-receiver-venv/bin/python -m pip install --upgrade --force-reinstall git+https://github.com/CaenFalaisePlaneurs/aero-pi-ogn-receiver.git
sudo /home/$(whoami)/aero-pi-ogn-receiver-venv/bin/python -m aero_pi_ogn_receiver.setup.setup
sudo systemctl start aero-pi-ogn-receiver.target

Verify health:

~/aero-pi-ogn-receiver-venv/bin/aero-pi-ogn status --live

For normal service commands, see Maintenance. For deeper traffic and RF checks, see Advanced Usage.