The end state: a Pi 5 (pi5-2) serving NTP to the LAN, disciplined by a u-blox NEO-series GPS module. The GPS’s NMEA sentences over serial say which second it is; a PPS (pulse-per-second) line on GPIO18 says exactly when that second starts. chrony locks onto the PPS pulse as its primary source, and the whole LAN gets genuine stratum-1 time.

Hardware

• Raspberry Pi 5
• A cheap u-blox NEO-6M/7M/8M GPS breakout board
• An outdoor active GPS antenna (added later — more on why below)

Wiring to the GPIO header:

The first debugging lesson, before any software was involved: if the module’s status LED never blinks, check the power pin voltage before anything else. A GPS module that looks “dead” is very often just under-powered.

Software setup

The UART on the GPIO header defaults to being the serial console/login shell, so that has to be freed up first:

raspi-config nonint do_serial_cons 1   # disable login shell over serial
raspi-config nonint do_serial_hw 0     # enable the UART hardware (adds
                                        # dtparam=uart0=on on Pi 5)
reboot                                 # required for the overlay to apply

Then install the two pieces that do the actual work:

apt install gpsd gpsd-clients chrony

gpsd talks to the GPS module and parses its NMEA output; chrony is the NTP daemon that turns that (plus PPS, later) into disciplined system time and serves it to the LAN.

Point gpsd at the device in /etc/default/gpsd:

DEVICES="/dev/ttyAMA0"
GPSD_OPTIONS="-n"

And give chrony a GPS refclock in /etc/chrony/conf.d/gps.conf:

refclock SHM 0 refid NMEA precision 0.05 poll 3 filter 8 offset 0.142
allow 192.168.1.0/24
local stratum 10

Then systemctl enable --now gpsd.socket gpsd.service chrony.

That looks simple. Getting there wasn’t — two gotchas ate most of the debugging time, and neither is obvious from the standard docs.

Gotcha #1: /dev/serial0 is a trap on the Pi 5

The conventional wisdom is “use /dev/serial0, it’s the stable alias for the GPIO UART.” On this Pi 5 + Bookworm image, that’s wrong. serial0 resolves to ttyAMA10 — the SoC’s internal PL011 UART, not the RP1 UART actually wired to the GPIO14/15 header pins. The header UART is ttyAMA0.

This is a nasty one to debug because every surface-level check says it should work: the device exists, gpsd can open it without error, and pinctrl shows the pins correctly muxed to TXD0/RXD0. It just silently receives zero bytes, because it’s listening to a UART with nothing physically connected to it.

I confirmed it by comparing /sys/class/tty/ttyAMA*/device/of_node against /proc/device-tree/aliases/serial0 (they pointed at different device-tree nodes), and with a physical loopback test — a jumper wire between pins 8 and 10, then writing and reading /dev/ttyAMA0 directly to prove the header UART was the one actually moving bytes.

Fix: use /dev/ttyAMA0, not /dev/serial0, on this board.

Gotcha #2: gpsd’s chrony SOCK integration is PPS-only

gpsd ships wired up to feed chrony directly over a Unix socket at /run/chrony.<device>.sock (chrony creates the socket; gpsd connects to it as a client, which is the opposite of what the naming suggests). It looks like the obvious modern integration path. On a module with no PPS wire yet, it just doesn’t work — refclock SOCK /run/chrony.ttyAMA0.sock sits at reachability 0 forever, with no error logged anywhere.

Digging through the strings in the gpsd binary turned up the reason: "PPS:%s using chrony socket ..." — that path only activates once gpsd has a PPS source. No PPS wire, no socket traffic, ever, silently.

Fix: use the older refclock SHM 0 interface, which gpsd always populates with coarse NMEA/UBX-derived time regardless of whether PPS is present. That’s the refclock SHM 0 refid NMEA ... line above.

Calibrating the NMEA offset

Without PPS, NMEA time arrives late over the serial link by a fixed amount — on this setup, a very stable +142ms (std dev under 2ms once the outdoor antenna gave a solid fix). That’s calibrated out with the offset parameter:

1. Let chrony run with a good GPS fix for a few minutes.
2. Read the Offset column for the GPS source in chronyc sourcestats — its offset relative to the NTP-disciplined system clock.
3. Put that value (in seconds, same sign) on the refclock SHM line’s offset parameter and restart chrony.
4. Verify with chronyc sources: the GPS offset should now sit within a few milliseconds of the pool servers.

The precision 0.05 on that line claims a conservative ±50ms error bar — small enough that chrony selects GPS as primary, large enough that if the NMEA latency ever drifts substantially, the pool servers out-vote it and chrony marks it a falseticker instead of quietly following bad time.

Indoors, the module struggled to get a fix at all. An outdoor active antenna fixed that — a solid fix on ~10 satellites is what made everything past this point (including PPS) practical.

Reading chronyc sources

If you haven’t stared at chrony output before, the symbols are worth knowing:

MS Name/IP address         Stratum Poll Reach LastRx Last sample
===============================================================================
#- NMEA                          0   3   377     2   +1234us[+1230us] +/- 50ms
^* time.pool.example.org         2   6   377    23   -123us[ -089us] +/-  12ms
^+ ntp2.pool.example.org         2   6   377    41   +456us[ +460us] +/-  15ms

• # marks a reference clock (GPS); ^ marks a network peer.
• * is the currently selected source; + is a candidate in agreement; - is reachable but not currently selected/combined.
• The trailing +/- Nms is chrony’s estimated error bound for that source — this is what the precision setting on a refclock line ultimately informs.

The PPS upgrade

NMEA-only gets you agreement with the pool to a couple of milliseconds, but the true accuracy is only as good as that +142ms latency is stable — and it can shift if gpsd, the sentence mix, or the module changes. PPS fixes this properly: it’s a hardware pulse on the exact top of each second, so sub-second timing stops depending on a measured constant entirely. The NMEA sentence still supplies which second it is; PPS supplies the precise edge within it.

1. Enable the PPS overlay. In /boot/firmware/config.txt (Bookworm’s path — not /boot/config.txt):

dtoverlay=pps-gpio,gpiopin=18

reboot for the overlay to load. GPIO18 is just the convention dtoverlay=pps-gpio defaults to; any free GPIO works if gpiopin= matches the wire.

2. Confirm the kernel sees pulses:

apt install pps-tools
lsmod | grep pps_gpio          # pps_gpio module loaded
dmesg | grep pps                # "new PPS source pps@12" + "Registered IRQ"
ppstest /dev/pps-gps            # one "assert" line per second, timed

If ppstest prints nothing, either the module has no fix yet (most NEO boards don’t pulse PPS without one) or the wiring/gpiopin is wrong.

3. Gotcha: /dev/ppsN numbering is a boot-time race. On the Pi 5, the Ethernet controller’s PTP clock (ptp0) and the GPIO PPS both register as /dev/pps*, and which number each gets depends on probe order at boot. On this box the GPIO PPS came up as pps0 and the Ethernet PTP clock as pps1 — the opposite of what I’d first assumed, and the opposite of how it had been before adding PPS. Trusting a bare device number risks chrony silently locking onto the Ethernet PTP clock after a reboot: no error, just quietly wrong time.

The fix is to match on the stable device-tree name instead of the number, via a udev rule (/etc/udev/rules.d/10-pps-gps.rules):

SUBSYSTEM=="pps", ATTR{name}=="pps@12.-1", SYMLINK+="pps-gps"

Then udevadm control --reload-rules && udevadm trigger --subsystem-match=pps, and confirm /dev/pps-gps points at whichever ppsN is actually the GPIO source. Check the name on your own board with cat /sys/class/pps/pps*/name — the GPIO one is the pps@NN entry, the Ethernet one is ptp0.

4. Add the PPS refclock to chrony. Keep the existing NMEA line (it still supplies the integer second) and add a native PPS refclock locked to it, in /etc/chrony/conf.d/gps.conf:

refclock SHM 0 refid NMEA precision 0.05 poll 3 filter 8 offset 0.142
refclock PPS /dev/pps-gps refid PPS lock NMEA precision 1e-7 poll 3 prefer

• lock NMEA tells chrony to take the ambiguous PPS second-number from the NMEA refclock — so the calibrated offset 0.142 still matters, just for a much looser reason: it only needs to land NMEA within ±0.2s of the pulse to keep the lock, and 142ms is comfortably inside that.
• prefer makes PPS the source chrony actually steers to; the pool servers and NMEA become agreement/sanity checks rather than the trusted source.
• precision 1e-7 (~100ns) tells chrony this is a high-quality source, so it gets weighted well above NMEA and the pool.

Restart chrony. In chronyc sources -v, PPS should now be the selected source (#*) with an estimated error in the hundreds of nanoseconds, NMEA reachable but not combined (#-, it’s just supplying the lock), and the pool servers as agreement checks (^-). journalctl -u chrony logs Selected source PPS.

Simpler alternative: once PPS is wired, gpsd’s SOCK integration from gotcha #2 finally has a PPS source to report, so refclock SOCK /run/chrony.ttyAMA0.sock refid GPS precision 1e-7 prefer works too, letting gpsd handle the PPS plumbing. I kept the native refclock PPS line instead — it’s explicit about the NMEA lock, doesn’t depend on gpsd’s internal PPS handling, and sidesteps needing gpsd to pick the correct device. SOCK is one line if you’d rather use it.

Where accuracy ended up

The calibrated NMEA constant went from “the thing being trusted” to a wide safety margin that only has to hold the PPS second-lock — a much easier job than being the actual accuracy source.

Verifying it’s all working

gpspipe -w -n 20        # raw gpsd JSON: satellites, fix mode, position
cgps -s                  # live satellite dashboard
ppstest /dev/pps-gps     # confirm PPS pulses (one assert/sec) reach the kernel
chronyc sources -v       # confirm PPS is selected (#*), NMEA reachable (#-)
chronyc sourcestats

If chronyc sources shows #* next to PPS, the whole chain — antenna, module, kernel PPS, chrony — is doing its job, and every other device on the LAN syncing against this Pi is getting time that isn’t waiting on an internet connection to be right.