Skip to content

Troubleshooting

Jump to bottom
W9KSB edited this page Jun 14, 2026 · 5 revisions

Troubleshooting

Service Does Not Start

Check service status:

sudo systemctl status pi-sat
journalctl -u pi-sat -f

Common causes:

  • invalid config file
  • missing Python dependencies
  • missing Hamlib utilities
  • malformed TLE source configuration

If the service is not starting and the config file is suspected, you can easily revert to the original, default, config and backup the current file if you would like with these commands:

cd ~/pi-sat
mv pi-sat-controller.conf pi-sat-controller.conf.bak
cp pi-sat-controller.conf.example pi-sat-controller.conf
sudo systemctl restart pi-sat
sudo systemctl status pi-sat

Settings Page Loads Incorrectly

If the browser is showing stale UI assets, force a hard refresh. If caching has been disabled in config, the backend should serve the frontend with no-cache headers.

No Passes Showing

Check the following:

  • station location is correct
  • tracked satellites are configured
  • TLE data exists and is current
  • the selected satellites are present in the merged TLE cache

If a TLE source fails, Pi-Sat may still run on an older cache, but missing satellites in the cache will not produce passes.

TLE Download Failures

Common causes:

  • remote source unavailable
  • source returns HTTP errors
  • source blocks access
  • malformed source list in config

If one source fails and others succeed, the merge can still complete.

Automation Script Problems

Check the following:

  • the script is placed in the root scripts/ directory
  • the script uses a supported extension such as .py or .sh
  • the script appears in the settings-page dropdown
  • the settings-page test button succeeds
  • the monitor page shows the expected execution result

If the test button works but the script does not fire during a pass, verify that the correct AOS or LOS script is selected and that the pass event actually occurred.

Wrong Time Zone or Pass Time Display

Pi-Sat derives display timezone from the configured station coordinates, not from a hardcoded Eastern time zone assumption or anything like that. If times look wrong, verify the station location first.

SDR or Radio Does Not Track

Check:

  • the device is enabled in config
  • the correct connectivity mode is selected
  • the correct host and port or serial path is configured
  • Hamlib can control the device outside Pi-Sat
  • config-level write control is enabled where required
  • the settings-page test button succeeds for that role

Local Serial Device Problems

Check:

  • the serial path exists
  • the chosen path is stable
  • the Pi user has permission to access the device
  • the baud rate and model ID are correct
  • the settings page is not showing Selected device not connected

Rotator Does Not Move

Check:

  • rotator control is enabled
  • config-level rotator writes are enabled in the config file (should be by default)
  • the pass is actually active
  • target elevation is above the configured minimum elevation
  • local or network rotctld is reachable and functioning
  • the settings-page rotator test succeeds

If pass tracking is inactive, Pi-Sat should not be sending tracking commands.

Frequency Does Not Match Other Software

Possible causes:

  • different TLE source quality
  • stale TLE data
  • different Doppler update timing
  • radio readback lag
  • manual user offset still applied

Before changing the tracking logic, compare:

  • Pi-Sat target frequency
  • actual radio readback
  • another tracking program
  • observed signal location on the waterfall

Browser Looks Wrong After Update

Start with:

  • hard refresh
  • service restart

Then verify whether browser asset caching is enabled or disabled in config.

Clone this wiki locally