Installation & Service Issues

Dashboard not loading (Nginx “Welcome” Page)

If you see the default “Welcome to nginx!” page after installation, it means the default Nginx configuration is still active and taking priority over ChroGPS Dash.

To resolve this, run the following commands to disable the default site and restart the web server:

sudo rm /etc/nginx/sites-enabled/default && sudo systemctl restart nginx

Caution

This permanently removes the default Nginx site symlink. If you have other virtual hosts configured on this server, verify they have their own site configs in /etc/nginx/sites-enabled/ before running this.

Chrony failed after hardware provisioning (/dev/pps0 not found)

If you ran the hardware provisioning script in GPIO mode and Chrony is failing to start with an error like:

Fatal error: Could not open /dev/pps0: No such file or directory

or systemctl status chrony shows the service in a failed state immediately after running the provisioning script – this is expected behavior and not a bug. In GPIO mode, the pps-gpio Device Tree overlay (added to config.txt) must activate before /dev/pps0 is created, and that only happens after a reboot. Reboot and the error will not recur:

sudo reboot

Note

If you installed ChroGPS Dash immediately after hardware provisioning (without rebooting first), the installer’s Chrony configuration step will print a yellow advisory message instead of the normal green success line. This is intentional – the installer detected that Chrony could not restart and deferred it to boot time. The ChroGPS Dash installation completed successfully and everything will work after reboot.

USB mode does not have this issue – GPSd and Chrony are restarted by the provisioning script immediately and no reboot is required.

GPSd not seeing the GNSS receiver after GPIO provisioning

After rebooting following GPIO mode setup, if GPSd reports no device or no data from the GNSS receiver:

1. Confirm the serial device exists:

   ls -la /dev/serial0 /dev/ttyAMA0
   

2. Confirm the disable-bt and pps-gpio overlays are active:

   dtoverlay -l
   

   Both should appear in the output. If they don’t, verify your config.txt contains the entries added by the provisioning script and that you have fully rebooted (not just restarted services).
3. Verify GPSd is pointed at the correct device:

   cat /etc/default/gpsd
   

4. Check GPSd logs for errors:

   journalctl -u gpsd -n 50
   

Note

On Raspberry Pi 3, 4, Zero W, and Zero 2W, the dtoverlay=disable-bt entry in config.txt is essential. Without it, Bluetooth occupies the reliable PL011 UART (ttyAMA0), leaving the GPS receiver on the unreliable mini-UART (ttyS0), which often results in garbage or missing data. The provisioning script adds this automatically, but it only takes effect after a reboot.

Empty Graphs?

If graphs appear but have no data:

1. Verify Chrony is logging: sudo ls -l /var/log/chrony/
2. Wait a few minutes for logs to populate.
3. Run the installer again to re-apply permission fixes.
   
   

Tip

Graphs are populated by the chrogps-poller systemd timer, which polls the dashboard endpoint every 30 seconds in the background – no browser tab needs to be open. Verify it is running: systemctl status chrogps-poller.timer. If it is inactive, re-running the installer will re-enable it.

Upgraded your OS and now the Dashboard won’t load or throws an error?

Recommended

Re-Run the Installer

OS upgrades often bump the PHP-FPM version (e.g. Debian 12 → PHP 8.2, Debian 13 → PHP 8.4). Re-running the one-line installer detects and corrects this automatically - no manual Nginx or PHP reconfiguration needed.

    <a href="../#installer" class="advisory-cta">
        <i data-feather="arrow-right"></i>
        Quick Installer
    </a>
    
</div>

“Cannot create/open log file: …” Message?

You broke something. Simply re-run the installer to fix it.

GPS & Satellite Data Issues

Wrong constellation colors?

Your GPS receiver may be using u-blox-style gnssid values instead of the NMEA standard. ChroGPS Dash handles both automatically by validating gnssid against PRN ranges.

To verify which scheme your receiver is using:

gpspipe -w | grep '"class":"SKY"' | head -3 | jq '.satellites[]? | {PRN, gnssid}'

Note

Requires gpspipe and jq. If either is missing, run:

sudo apt-get install -y gpsd-clients jq

Then re-run the test command.

If you see GLONASS satellites (PRN 65-96) with gnssid=6, that’s u-blox numbering. If you see gnssid=2, that’s NMEA numbering. ChroGPS Dash handles both correctly.

Missing satellites?

Some receivers report satellites across multiple gpsd messages. ChroGPS Dash caches satellites for 30 seconds to accumulate all of them - the satellite count should grow from ~15 to ~25 over a few refreshes.

Note

It is normal for the count to be lower immediately after a page load or service restart. Allow 3-5 refresh cycles (~30-60 seconds) for the satellite cache to fully populate before concluding that satellites are missing.

To inspect the cache directly:

cat /var/tmp/cgpsd-sat-cache.json | jq '.satellites | length'

Duplicate satellites on a multi-band receiver?

ChroGPS Dash automatically aggregates multiple signals per satellite and shows only the strongest. You should see one entry per PRN regardless of how many frequency bands are being tracked. If you are seeing duplicates, patches are welcome .

Satellites showing but no position fix?

Check that you have:

• A clear view of the sky.
• At least 4 satellites with good signal (> 25 dBHz).
• HDOP < 5.0.
• Waited 30–60 seconds for the initial fix after startup.

Access & Security

Locked out of the dashboard? (Dashboard Gate)

If DASHBOARD_REQUIRE_AUTH is enabled and you have lost or forgotten the admin token, you cannot authenticate through the browser - the gate lock screen will reject all attempts. To regain access:

Option 1 - Display the current token (no change):

curl -fsSL https://chro.gpsda.sh/install | sudo bash -s -- -dt

This prints the token currently stored in cgpsd-settings.php without modifying anything.

Option 2 - Read it directly from the settings file:

sudo grep ADMIN_TOKEN /var/www/chrogps-dash/cgpsd-settings.php

Option 3 - Temporarily disable the gate via SSH:

sudo sed -i 's/\$DASHBOARD_REQUIRE_AUTH = true/\$DASHBOARD_REQUIRE_AUTH = false/' \
    /var/www/chrogps-dash/cgpsd-settings.php

This disables the gate immediately (no restart needed). Re-enable it from the Admin Panel once you have your token.

Tip

If you need to reset the admin token entirely, run the installer with the -rt flag:

curl -fsSL https://chro.gpsda.sh/install | sudo bash -s -- -rt

This generates a new random token and prints it to the terminal. Any existing dashboard gate sessions will be invalidated automatically since the HMAC cookie is derived from the token.

General Support (Note: lack thereof)

Q: “It’s not working, can you help me?”

A: No.

Q: “But I used the installer!”

A: It works on my machines. ¯\_(ツ)_/¯

This project is a labor of love, not a job. Please consult the Googles, the Linux man pages, or your local wizard for assistance.

In all (kind-of-)seriousness…

This dashboard is provided with a strict “You Break It, You Fix It” warranty.

I have provided crystal-clear instructions and a magical installer script that does 99% of the work for you. If you still manage to break it, congratulations! You have just discovered a learning opportunity.

• Documentation & Code: Read it again. Slower this time.
• Bugs: If you find a bug, patches are welcome .
• Tech Support: I do not offer tech support. If I did, I would charge a lot more than “Free.”

Q: “Does ChroGPS Dash support the ntpd daemon from Network Time Foundation/ISC (or ntpsec or ntpd-rs or timesyncd or openntpd etc.)?”

A: God no. And it never will. Chrony is superior in every way. Just…use…Chrony .

Q: “Can I install ChroGPS Dash on WPSD??”

A: No!!! 🛑 🚫
Look, I know I wrote both of these apps, but they were (deliberately) designed to not play nice together. WPSD is a managed ‘appliance’ - it likes its designs/setups exactly how they are.
Install ChroGPS Dash on a fresh or other existing, non-WPSD Linux instance so that WPSD remains happy and functional.
For the love of God…Just leave your WPSD installation alone and let it be. 🤦