Troubleshooting

Troubleshooting

Expand a topic below that matches what you are seeing.

1. Touch works in evtest / i2cdetect but taps do nothing in the app

On Raspberry Pi OS Bookworm with labwc/Wayland, Xwayland usually delivers mouse events for the panel, not SDL FINGER* events. If /etc/flightscnr.env has TOUCH_USE_FINGER_EVENTS=True, taps can be dropped on older builds:

sudo sed -i 's/^TOUCH_USE_FINGER_EVENTS=.*/TOUCH_USE_FINGER_EVENTS=False/' /etc/flightscnr.env
sudo systemctl restart flightscnr

Current builds also fall back to the mouse path automatically when no FINGER* events arrive (see issue #14).

Current install-pi.sh switches LightDM to the Pi X11 session (needed for pinch-zoom) and may reboot. After that switch, taps use SDL mouse emulation; Motif/cursor retries run on the SDL thread so touch-as-mouse is not wedged after restart.

2. Pinch-to-zoom does nothing

Tracked in issue #21.

Pinch only works when SDL delivers multi-touch as FINGERDOWN / FINGERMOTION / FINGERUP. Under Wayland / Xwayland, touch is often pointer-emulated as a single mouse cursor - mouse events cannot represent two fingers, so pinch is impossible on that path.

Current installs force X11 via install-pi.sh (LightDM Pi X11 session) and reboot when that switch is pending. After Update / Finish install / a fresh install, confirm you are on X11, then:

sudo journalctl -u flightscnr -b | grep -E 'Touch:|pinch:|FINGER'

• If you never see FINGER events detected / pinch: session ARMED, the display stack is not sending multi-touch to SDL.
• Keep TOUCH_USE_FINGER_EVENTS=False for reliable taps under pointer emulation; flipping it to True does not invent FINGER* events.
• Change range without pinch: on-device Settings → Display → Radar Range (or the portal radar range control).
• To pan/recenter the map without multi-touch: long-press then drag on the radar (~0.5 s still hold, then move; release after moving to save), or use Settings → Display → Click to Set Radar Center (pan, then tap center to save / tap rim to cancel).
• Optional debug: set TOUCH_DEBUG=1 in /etc/flightscnr.env, restart, pinch on radar, and inspect journalctl -u flightscnr -f | grep touch.

If you are still on labwc/Wayland, run Update Now or sudo bash install-pi.sh so the installer can switch to X11 (automatic reboot).

3. Web portal stuck on “Update in progress…”

Tracked in issue #25.

After an interrupted portal update, /var/lib/flightscnr/update-status.json can stay at "state": "running". The Updates section then shows Update in progress… forever (including across reboots), and Update Now is blocked.

Current firmware clears stale “running” state when no update worker is alive. If you are still stuck on an older build:

sudo rm -f /var/lib/flightscnr/update.lock /var/lib/flightscnr/update-status.json
cd ~/FlightScnr_Pi && bash install-pi.sh update

Or use the portal Repair & Update button when shown. Adjust the path if your clone is not ~/FlightScnr_Pi. Refresh the portal Updates section afterward.

4. Update fails / stuck on 2026.8.5.x / detached HEAD

Try Update Now once more from the portal. Older installs could leave scripts/release.sh mode-dirty, which used to block git pull; that file is frozen upstream so a second Update often succeeds.

If the portal shows Repair & Update, use it. If that button is missing:

curl -fsSL https://raw.githubusercontent.com/yashmulgaonkar/FlightScnr_Pi/main/scripts/repair-ota.sh | bash

Use | bash -s -- --hard only if other local edits also block the pull.

Detached HEAD (e.g. after checking out a release tag) is fixed by Update / Repair by fetching and checking out main from origin/main. If Finish install appears after an OTA, tap it (or reboot and let auto-resync finish). See Updates.

5. Blank Waveshare panel after boot

• Confirm the correct overlay in config.txt / /boot/firmware/config.txt (see Software Setup).
• On Pi 5 / Compute Module, try the DSI0 overlay line instead of DSI1.
• Power off fully before reseating the DSI ribbon.
• Fresh installs force 720×720 panel mode via kanshi / display setup; re-run install if the desktop is letterboxed.

6. Web portal not reachable

• Confirm the Pi is on the same LAN and try http://<hostname>.local (default hostname from Imager).
• Check the service: sudo systemctl status flightscnr and sudo journalctl -u flightscnr -f.
• Port defaults to 80; override with WEB_PORT in /etc/flightscnr.env.
• Kiosk installs disable Wi‑Fi power save to reduce hotspot stalls and flaky links; if Wi‑Fi still drops, check nmcli / router, or use Ethernet for setup.

7. ATC / chime has no sound

• Confirm mpv is installed: sudo apt install mpv.
• Prefer a USB speaker, or pair a Bluetooth speaker in the portal → Bluetooth Speaker, then Use Bluetooth. Fresh installs enable Bluetooth (rfkill unblock + bluetooth.service).
• By default the app requires a USB ALSA playback device (or the selected BT sink) so it does not open HDMI / 3.5 mm with nothing useful attached. Temporarily allow built-in sinks with FLIGHTSCNR_AUDIO_ALLOW_BUILTIN=1, or disable the gate with FLIGHTSCNR_REQUIRE_SPEAKER=0, in /etc/flightscnr.env (see .env.example).
• If PipeWire leaves the USB gadget sink missing after reconnect, unplug/replug the speaker or relaunch the app from System.
• Quiet hours (ATC) and off-hours schedule can block auto-start / chime / earthquake voice; use Play / Preview to test.
• Firmware 2026.8.5.2 routes the root-run service through the desktop user’s pipewire-pulse session. Update and rerun sudo bash install-pi.sh if audio works on the desktop but not in FlightScnr.

8. ATC keeps playing after disable or airport change

Fixed in firmware 2026.8.3.4. Update from the portal (or git pull + restart). On older builds, toggle Play/Stop on the ATC page or relaunch the app from System.

9. Radar aircraft positions freeze / hang

Fixed in firmware 2026.8.3.3 (AIS / overhead refresh could stall the radar redraw). Update to 2026.8.3.3 or newer. If you still see freezes on a current build, capture sudo journalctl -u flightscnr -f around the hang.

10. Bluetooth “Connection successful” steals the fullscreen UI

Firmware 2026.8.5.4 hardens popup suppression for Wayland wf-panel-pi: it writes an explicit Bluetooth-free widgets_right list and sets notify_enable=false. Re-run install/update and reboot or log in again. Older lxpanel desktops have their Bluetooth plugin removed. If a legacy panel config is unwritable, installation continues with a warning. On X11 kiosk installs, Openbox title / menu chrome is also suppressed for an edge-to-edge round UI.

11. Safety disclaimer does not auto-continue

• Don't show again must be checked on the physical display before tapping Accept.
• A remembered boot shows Continuing in 8…1 and no Accept button.
• Unchecking the box during that countdown clears the choice for the next boot.
• Changing the disclaimer version invalidates old acceptance.
• The portal can only clear acceptance. Uploading a settings backup also clears it and cannot restore consent.

12. Wipe & reinstall fails with sudo error

Portal Master Caution → Wipe & reinstall needs an updated sudoers entry. Tap Update Now or Finish install once, then try Wipe again. Download settings from System first if you want to keep prefs and API keys. Wipe does not touch Wi‑Fi or dump1090.

13. Marine (AIS) traffic not visible on radar

Marine positions come from aisstream.io over WebSocket. That service is known to be unreliable — outages, silent failures (connected but no vessel data), and auth issues are common and are not a FlightScnr Pi bug.

On the Pi first

• Portal → Radar → Radar traffic set to Marine (AIS) only or Aircraft and marine.
• Portal → API Keys → valid aisstream.io key saved; Use aisstream.io API key enabled.
• Relaunch the app from System after changing keys or traffic mode.

Check upstream status

• Live (unofficial) monitor: AIS Stream Uptime — checks stream.aisstream.io about every 30 seconds.
• Official issue tracker: aisstream/issues on GitHub — many open reports of outages and zero-data WebSocket connections.
• If the dashboard shows Down, Silent Failure, or Connectivity Issue (often an expired/invalid key), wait for aisstream.io to recover or fix the key; vessel icons may stay empty until the stream sends positions again.

sudo journalctl -u flightscnr -f | grep -iE 'ais|marine|websocket'

Aircraft-only mode or a missing/disabled key will look like “no marine traffic” even when aisstream.io is fine.

14. Useful log commands

sudo journalctl -u flightscnr -f
sudo journalctl -u flightscnr -b | grep -E 'Touch:|pinch:|FINGER'