-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
Quick answers to the questions newcomers hit most. Most "it doesn't work" cases are one of two things: dump1090 isn't delivering aircraft, or the observer coordinates / Sun-Moon visibility mean there's simply nothing to predict right now. The checks below isolate which.
Two services are involved, don't confuse them:
dump1090-fa(the ADS-B receiver, servesaircraft.jsonon port 8080) andstp.service(this predictor, serves the web UI on port 8081). "No planes in the UI" is almost always the former.
Three levels, fastest to most thorough:
# 1. Is the service up?
systemctl status dump1090-fa --no-pager # want: Active: active (running)
systemctl is-active dump1090-fa # short form -> "active"
# 2. Is it actually delivering aircraft? (the real test)
curl -s localhost:8080/data/aircraft.json | head -c 400 # JSON with "aircraft":[…]
curl -s localhost:8080/data/aircraft.json | grep -o '"hex"' | wc -l # how many planes right now
# 3. Visual: open the SkyAware map in a browser
# http://<pi-ip>:8080/active (running) only means the process is alive — the count in step 2
is what proves you're receiving. 0 can be perfectly normal at night or with
a poorly placed antenna; try again when planes are likely overhead.
In order of likelihood:
- No planes overhead / night — ADS-B is line-of-sight; an empty sky is empty. Re-check during the day.
- Antenna — needs a clear view of the sky, ideally outdoors or at a window; indoors behind walls kills 1090 MHz.
- USB port — plug the RTL-SDR into a USB-2 port. USB-3 ports are RF-noisy at 1090 MHz and measurably reduce range.
-
Gain — leave the dump1090-fa default first. The log lines
adaptive: … stopping … scan hereare normal auto-gain tuning, not errors.
ADS-B at 1090 MHz is strict line-of-sight — whatever the antenna can see, it receives; whatever blocks the view blocks the planes almost completely. This dominates everything else, so placement matters far more than the antenna model:
- Buildings block signals immediately. A house to your north means little to no aircraft signal from the north — you'll see a lopsided sky with a dead sector in that direction. Nothing's broken; that's the wall.
- Height is everything. A small antenna at ground level realistically reaches ~20–30 km. The same antenna on a rooftop with a clear horizon can reach up to ~500 km; a good all-round target is ~100 km.
- Get it up high with a clear view. The supplied coax is usually long enough to mount the antenna higher than the Pi — a broomstick, a tree branch, or the corner/edge of the house wall all work. Higher + clearer beats expensive every time.
- Keep metal away. Don't surround the antenna with metal (railings, poles, roof flashing, a metal mast right next to it) — it detunes and shadows the antenna. A little clearance in every direction helps.
- Mount it vertical. ADS-B is vertically polarised — the antenna should stand upright (perpendicular to the ground), not tilted or horizontal.
You can see the effect directly on the SkyAware map (http://<pi-ip>:8080/):
a clear horizon gives a roughly circular coverage blob; obstructions show up
as missing wedges pointing at whatever is blocking the sky.
The Linux DVB-T TV driver grabs the stick before dump1090 can. Blacklist it and reboot (the bootstrap installer does this for you):
echo 'blacklist dvb_usb_rtl28xxu' | sudo tee /etc/modprobe.d/blacklist-rtl.conf
sudo rebootAfter the reboot, systemctl status dump1090-fa should show it claiming the device.
No — point the app at your existing feed instead. Install with
bootstrap-pi5.sh … | bash -s -- --no-dump1090 and set adsb.url in
config/service.json to your aircraft.json URL (e.g.
http://192.168.1.50:8080/data/aircraft.json). See
Setup → ADS-B receiver.
systemctl status stp.service --no-pager
journalctl -u stp.service -n 50 --no-pager # recent logA repeating aircraft.json HTTP … or ECONNREFUSED in that log means the
predictor can't reach dump1090 — fix the receiver first (above), or check
that adsb.url points at the right host/port.
- Is the service up?
systemctl is-active stp.service. - Right address? Use the Pi's LAN IP and port 8081 (the predictor), not 8080 (that's the SkyAware map).
- On the Pi itself,
curl -s localhost:8081/ | headshould return HTML.
Transits are genuinely rare — a plane has to cross the ~0.5° Sun or Moon disc from your exact spot. Before assuming a bug, confirm:
-
Your coordinates are correct — ⚙ Settings in the web UI (or
config/observer.json). A wrong location moves the whole geometry. - The Sun or Moon is actually up and above the 20° elevation floor the engine uses — nothing is predicted for a body below the horizon.
- The predictive watchlist (24 h preview) shows upcoming geometry even when no plane is near yet — that's the place to look, not the live candidate list.
⚙ Settings in the web UI (applies live, no restart). It writes
config/observer.json, which is gitignored — git pull and the nightly
auto-updater never overwrite it.
- Enter your user key + application token in Settings and use the test push button to confirm delivery first.
- Alerts only fire near a real event (early candidate, then T-minus) — no upcoming transit means no push. That's expected, not a fault.
- For the separate public mass-alert signup, see
alerts/README.md.
The installer enables a nightly auto-update from main by default —
nothing to do. To update now, or if you installed with --no-auto-update:
cd ~/sun-moon-transit-predictor
git pull && npm install --omit=dev && sudo systemctl restart stp.serviceYour config/ and data/ are never touched by an update.
The prediction geometry is fully offline (SGP4 for satellites,
astronomy-engine for Sun/Moon). Internet is only used for: refreshing
satellite TLE elements, sending Pushover, and the optional OpenSky
schedule augmentation. The core aircraft tracking works on a LAN with no
internet at all.
Check the display service and wiring — full layout, pinout and signals are in
display/README.md.
systemctl status stp-display.service --no-pagerStill stuck? Open an issue with the output of systemctl status dump1090-fa stp.service and the last ~30 lines of journalctl -u stp.service.