Troubleshooting Guide¶

Solutions to common issues encountered when using FBSAT59.

Startup Issues¶

FBSAT59 Won't Launch¶

Check: 1. Click application / run from terminal to see error message 2. Verify Python 3.11+ installed: python3 --version 3. Check disk space: At least 500 MB free 4. Try deleting settings: rm -rf ~/.config/fbsat59 5. Restart computer

If persists: Report issue at https://github.com/jf9som/fbsat59/issues

Splash Screen Hangs¶

If initialization stalls at "Fetching TLE data...":

Check internet connection
Try turning off WiFi/4G (use wired if available)
CelesTrak servers might be temporarily down
Wait 2–3 minutes (large TLE downloads can be slow)
If stuck >5 min: Force quit and restart

Satellite Tracking Issues¶

"No satellites visible" / Pass List Empty¶

Likely cause: Wrong location or TLE data not loaded

Fix: 1. Verify location (Settings → Location) - Check coordinates are decimal degrees - Verify hemisphere (N/S, E/W) - Ensure elevation is reasonable (0–3000m) 2. Update TLE - Help → TLE Status (check age) - Satellite menu → Fetch TLE Data - Wait for download to complete

Satellite Position Seems Wrong¶

Cause: Old TLE data or location error

Fix: 1. Refresh TLE data (see above) 2. Verify location with GPS or web tool 3. ISS is the best reference satellite for testing

Pass Times Off by Hours¶

Cause: Timezone mismatch or wrong location

Fix: 1. Check system time: date (terminal) 2. Verify location latitude/longitude (±1° is too far off) 3. Change display format: View → Time Zone (UTC vs Local)

Radio Control Issues¶

"Serial Port Not Found" or "Failed to Connect"¶

Step 1: Check Physical Connection - Verify USB cable is plugged in - Try different USB port on computer - Test with another USB device (is port working?)

Step 2: Drivers (Windows/macOS) - Download FTDI drivers: https://ftdichip.com/drivers/ - Restart FBSAT59 after installing

Step 3: Port Name - Linux: lsusb (look for radio vendor ID) - macOS: ls /dev/tty.* (should list serial ports) - Windows: Device Manager → look for radio/COM port

Step 4: Settings - Try manual port selection (not auto-detect) - Change baud rate (38400 → 19200 or 9600) - Check radio manual for CAT/CI-V settings

Frequency Doesn't Update When Selecting Transponder¶

Likely cause: Radio not in correct mode or connection issues

Fix: 1. Verify radio connected: Status bar should show ✅ RIG: 1 2. Check radio is in SSB/USB/LSB mode (not FM) 3. Restart FBSAT59 and radio connection 4. Try simpler radio model from Hamlib (troubleshoot settings)

Doppler Correction Seems Excessive or Insufficient¶

Cause: Location error or old TLE

Fix: 1. Verify location accuracy (within 1 km) 2. Update TLE data (less than 24 hours old) 3. Test with ISS (most reliable for Doppler testing) 4. Doppler shift should: - Increase frequency as satellite approaches (max at TCA) - Decrease frequency as satellite recedes

PTT (Transmit) Not Working¶

Check: 1. Radio is connected (✅ RIG: 1 in status bar) 2. Radio supports CAT PTT (check manual) 3. Try: Click transponder → Radio Control tab → Click [PTT ON] 4. Verify radio is in transmit mode (not RX lock)

SDR Issues¶

SDR Not Detected¶

Check: 1. Plug in SDR via USB 2. Wait 3–5 seconds (driver loads) 3. Settings → SDR Settings → Click [Detect] 4. If not found: Driver issue (see below)

Linux Drivers:

sudo apt install libsoapysdr0 soapysdr-module-rtlsdr

macOS Drivers:

brew install soapysdr rtl-sdr

Windows: Download from https://osmocom.org/projects/rtl-sdr/wiki/Rtl-sdr

Waterfall Shows No Signal¶

Fix: 1. Check downlink frequency (should be satellite transmission freq) 2. Verify gain is high enough (try 40+ dB) 3. Check antenna connection 4. Tune ±50 kHz around expected frequency 5. Test with known transmitter first (radio station)

Audio Cracking / Distorted Sound¶

Cause: Gain too high, sample rate too low, or CPU usage high

Fix: 1. Lower RF Gain (reduce from 50 → 30 dB) 2. Increase sample rate if possible (2.4 MSPS better than 1 MSPS) 3. Close other apps (reduce CPU load) 4. Check USB cable (some cheap cables introduce interference)

Web Interface (Mobile) Issues¶

"Cannot Connect" to http://192.168.x.x:8080¶

Fix: 1. Verify on same WiFi network as desktop 2. Check desktop IP in Status Bar (may differ from example) 3. Disable cellular data (WiFi + cellular can cause issues) 4. Try http://localhost:8080 if on same device 5. Check firewall (some routers isolate guest networks)

Radar Updates Slowly / Sluggish¶

Cause: Network latency or desktop CPU overload

Fix: 1. Move closer to WiFi router 2. Check WiFi signal strength (RSSI) 3. Close other browser tabs 4. Close other desktop apps

Compass Mode Not Working (Android)¶

Fix: 1. Check device has compass sensor (Settings → Sensors) 2. Recalibrate compass: Move phone in figure-8 pattern 3. Disable screen rotation lock (auto-rotate must be ON) 4. Force-close and reopen browser

Data & Database Issues¶

"Database Locked" Error¶

Cause: Corrupted database or file permission issue

Fix:

# Backup
cp ~/.fbsat59-db.sqlite ~/.fbsat59-db.sqlite.backup

# Delete database (will rebuild on next launch)
rm ~/.fbsat59-db.sqlite

# Restart FBSAT59

TLE Update Stuck / Doesn't Complete¶

Fix: 1. Check internet connection 2. Try manual update: Help → TLE Status 3. CelesTrak might be down (try again in 5 min) 4. Check firewall isn't blocking access

Performance Issues¶

High CPU Usage¶

Cause: Rendering too many satellites or high update rate

Fix: 1. View menu → Use simpler map/radar (if available) 2. Reduce number of visible satellites (search/filter) 3. Disable background features (recordings, UDP broadcast)

Memory Usage Growing Over Time¶

Cause: Memory leak (rare) or long-running app

Fix: 1. Restart FBSAT59 periodically (daily recommended) 2. Close and reopen tabs 3. If persists: Report at https://github.com/jf9som/fbsat59/issues

Getting More Help¶

Check Logs¶

For developers/debugging:

# View application logs
tail -f ~/.cache/fbsat59/fbsat59.log

# Or on macOS/Linux:
journalctl -u fbsat59 -f

Report a Bug¶

Include: 1. Steps to reproduce (what you did) 2. Expected behavior (what should happen) 3. Actual behavior (what actually happened) 4. Screenshot (if visual issue) 5. System info: OS, FBSAT59 version, radio model

Post at: https://github.com/jf9som/fbsat59/issues

Ask the Community¶

Discord: [Join community server] (link)
Reddit: r/amateurradio
QRZ.com: Search "FBSAT59"

Common Mistakes¶

Mistake	Impact	Solution
Location off by >10°	Pass times wrong by hours	Re-check latitude/longitude
TLE older than 72 hours	Satellite position inaccurate	Manually update TLE
Radio in wrong mode	Frequency doesn't change	Set radio to USB/SSB mode
Gain too high (SDR)	Clipping / distortion	Lower to 30–40 dB
Old database	Missing new satellites	Delete & rebuild database

If Nothing Works¶

Restart everything: Computer, radio, SDR, app
Update FBSAT59: Check for newer version
Clear cache: Delete ~/.fbsat59-db.sqlite
Ask for help: Open GitHub issue with details

🚀 You're not alone — almost all issues are solvable!