![[Steve Friedl Logo]](/images/unixwiz-logo-140x80.gif){kind=logo}
This site uses advanced css techniques
I've been playing with the Raspberry Pi for a while now — what a delight! — and have
finally managed to turn one of them into a time server using the Adafruit GPS hat. It took much longer
than it should have, with resources scattered all over the internet, and it was quite frustrating.
I hope to provide guidance to save others some time, though I wish to be clear that I am documenting my setup: it may not be optimal, but it works. This is also not intended to be a tutoral for first-time Raspberry Pi users, or for those who are not comfortable working with hardware and doing a bit of light soldering.
There are many sources for these parts, but the coolest by far is the awesome adafruit, founded by the lovely Lady Ada: she's the EE I wish I were. So many cool parts, projects, kits - it's a one-stop shop for all things Raspberry Pi.
GPS works with very, very weak radio signals, and having a line of sight
visibility to the sky is important for good reception, and this active antenna
claims to achieve 28db of gain; this is substantial and I presume it uses the 3.3
volts DC supplied by the pi to the antenna.
I typically use the NOOBS mechanism for setting up my Raspberry Pi units, and these instructions assume 2.1.0 with the full configuration. I do not typically use the X11 GUI, but this is likely the most common variant so I'm leaving it in the instructions.
A full discussion of the Global Positioning System is far beyond the scope of this Tech Tip, but some items are important
First, though the GPS signals are in the radio spectrum, GPS controllers typically decode them into an ASCII data stream that can be parsed to determine the location and time.
This data stream is in NMEA — National Marine Electronics Association — format which includes far more data than we care about for the purposes of accurate timekeeping. Sample data looks like:
$GPGGA,043801.000,3343.3999,N,11749.3068,W,2,07,1.25,24.0,M,-34.2,M,0000,0000*66 $GPGSA,A,3,28,19,30,11,17,13,15,,,,,,1.54,1.25,0.90*0C $GPGSV,3,1,12,17,85,221,32,19,61,216,21,28,51,040,24,30,46,127,27*76 $GPGSV,3,2,12,13,45,255,18,46,42,149,,15,26,290,17,01,21,056,*77 $GPGSV,3,3,12,06,15,170,,11,12,044,12,07,11,133,,24,05,315,*7C $GPRMC,043801.000,A,3343.3999,N,11749.3068,W,0.39,297.37,240117,,,D*7E $GPVTG,297.37,T,,M,0.39,N,0.72,K,D*3F
We don't really need to understand any of the above — the gpsd software does that for us — but knowing vaguely what the data streams look like will help with troubleshooting later.
But less obvious is the second data source, the PPS (Pulse Per Second) signal, which is critical for accurate timekeeping.
The gist of PPS is that the NMEA data stream is sent to the computer ahead of the start of the next second (perhaps 500 msec early), but PPS signal marks the exact start of that second. This eliminates variations due to serial timing and other factors.
"At the tone, the time will be 3:12:07 PM.... (beep)" - PPS is that tone.
The PPS signal is delivered on one of the GPIO pins, and the Linux kernel has specific support for treating this signal as special with respect to timekeeping. The chip can deliver the PPS pulse within 10 nanoseconds of the top of the second, though it seems unlikely that Linux can actually maintain that kind of precision.
It's possible to configure an accurate GPS time source without PPS, it will still be within one second of the correct time, but those of us with more free time than good sense will dig for that extra accuracy.
Though some GPS receivers (including, I think, the one used in the Ultimate GPS hat) can
compute a rough time based on seeing just one satellite, proper GPS operation needs
to see at least four satellites to obtain a proper 3D position fix.
GPS signals are extremely weak, and good visibility to the sky is important for acquisition: a good antenna located outdoors, or at least very near a window, helps a lot.
But it's not just a matter of seeing the satellite: the receiver has to know where the satellites are in space as they fly around the planet: this requires a catalog of every satellite and their orbital parameters. This catalog is known as the "almanac", and it's sent over the air every 12.5 minutes; the GPS receiver needs to have this information before it can acquire a real fix.
This means that an initial power-on of the GPS receiver must not only see all the satellites, but receive the full almanac before it can acquire a fix. This time can be many minutes.
On the test setup used to write this Tech Tip, with just a pigtail antenna (no active external GPS antenna), a single-satellite's rough UTC time was reliably obtained in about 60 seconds after power on, but a 3D fix took between 8 and 20 minutes, with the PPS signal showing up a couple of minutes later.
The Ultimate GPS Pi Hat has a small red LED to indicate whether it has a proper fix or not:
Note: the LED only determines the 3D fix; you can't tell from looking at the board whether the PPS signal is being delivered or not without adding a bit of hardware (another LED).
Though you'll get the NMEA messages from the unit over serial whether it has a fix or not, there won't be a PPS. This means that without a good GPS fix, you cannot test whether you have much of this working or not.
The small CR1220 coin cell on the Ultimate GPS Hat board can power the realtime clock inside the GPS chip, as well as maintain the almanac while powered off: though it won't be tracking the satellites when the power is off, it makes a huge difference in time-to-first-fix: typically less than 60 seconds.
ProTip: Make sure your GPS board obtains a solid fix before troubleshooting the GPS-to-Pi interface.
As noted in the previous section, there are two data streams coming from the Ultimate GPS hat, and we have to configure them both. Due to changes between the Raspberry Pi 2 and 3, instructions differ substantially between the two, and this is definitely more complicated on the Pi3 than the Pi2.
The Ultimate GPS hat delivers its data over a serial port at 9600 bps, which uses pins 14 and 15 on the GPIO header.
On the Raspberry Pi 2, this went directly to the hardware UART and was available to Linux on /dev/ttyAMA0. Assuming there was no serial console using it, GPS works great here.
But on the Pi 3, the high-performance hardware UART is used by the Bluetooth subsystem, and the serial port supported on GPIO pins 14+15 is emulated much more weakly and is available on /dev/ttyS0. This is pretty much a software UART, and I don't like it.
Fortunately, it's possible to shuffle around the hardware in software (!) to take back the hardware UART for our purposes, and I am so grateful to Jon Watkins for his outstanding article on this exact subject: I'd not have figured this out otherwise. It's very well written and I'm just going to cobble his instructions.
# systemctl stop serial-getty@ttyAMA0.service # systemctl disable serial-getty@ttyAMA0.service
dwc_otg.lpm_enable=0console=serial0,115200console=tty1 root=/dev/mmcblk0p7 ...
# Use the /dev/ttyAMA0 UART for user applications (GPS), not Bluetooth dtoverlay=pi3-disable-bt
# Use software UART for Bluetooth enable_uart=1 dtoverlay=pi3-miniuart-bt
# systemctl disable hciuart
If this has been done correctly (and after a reboot), we expect to see NMEA data on that serial port, which you can see directly with:
$ cat /dev/ttyAMA0 $GPGGA,052731.000,3343.3943,N,11749.3064,W,2,04,3.93,24.8,M,-34.2,M,0000,0000*65 $GPGSA,A,3,13,17,28,19,,,,,,,,,4.05,3.93,0.99*0C $GPRMC,052731.000,A,3343.3943,N,11749.3064,W,0.84,313.46,240117,,,D*74 ...
If you see the above, your serial port is configured correctly and it's seeing GPS data.
Do not move to the next step until you can see serial data.
Linux has special kernel support for Pulse Per Second input via a GPIO pin to help synchronize the time: it associates a hyper-precise kernel timestamp with the rising edge of the PPS signal and makes it available to the application; it can then get highly accurate timestamps.
# apt-get install pps-tools
# enable GPS PPS dtoverlay=pps-gpio,gpiopin=4
# ppstest /dev/pps0 trying PPS source "/dev/pps0" found PPS source "/dev/pps0" ok, found 1 source(s), now start fetching data... source 0 - assert 1485236391.009463473, sequence: 148 - clear 0.000000000, sequence: 0 source 0 - assert 1485236392.009462426, sequence: 149 - clear 0.000000000, sequence: 0 source 0 - assert 1485236393.009459816, sequence: 150 - clear 0.000000000, sequence: 0 source 0 - assert 1485236394.009457259, sequence: 151 - clear 0.000000000, sequence: 0 source 0 - assert 1485236395.009456680, sequence: 152 - clear 0.000000000, sequence: 0 ... ^C
DHCP on many networks delivers time server config to their clients, allowing them to synchronize time properly along with the rest of the network. This is a good thing except for NTP time servers themselves, and disabling this behavior took much longer than it should have.
Failing to make these updates will find your /etc/ntp.conf either edited or ignored; it was maddening.
...
#supersede domain-name "fugue.com home.vix.com";
#prepend domain-name-servers 127.0.0.1;
request subnet-mask, broadcast-address, time-offset, routers,
domain-name, domain-name-servers, domain-search, host-name,
dhcp6.name-servers, dhcp6.domain-search,
netbios-name-servers, netbios-scope, interface-mtu,
rfc3442-classless-static-routes , ntp-servers;
#require subnet-mask, domain-name-servers;
#timeout 60;
...
... # A list of options to request from the DHCP server. option domain_name_servers, domain_name, domain_search, host_name option classless_static_routes # Most distributions have NTP support.# option ntp_servers# Respect the network MTU. ...
It probably requires reboot for this to take effect. At this point, you will be able to configure NTP support entirely without interference from the rest of the system.
There are a number of services that can decode and interpret the NMEA data coming
from your Ultimate GPS hat, but the most popular by a fair measure is the open source
GPSD.
This package is available in the usual apt-get repository, but as of this writing, the version found there (3.11) didn't work right for me — permissions issue with the PPS device, I think — and the only way I got this to work was to build it myself using version 3.16. I don't know if 3.11 has actual problems, or if I just didn't know what I was doing.
NOTE: these instructions are just to show what I did, not a tutorial.
I'll note that this is the first software package I've ever used that employed the scons build tool, replacing autoconf and make; this was a learning experience for me in part because it's built around python, not m4.
# apt-get install scons libncurses5-dev python-dev
("scons" is the new "make")
# cd /home
(you may want to put this somewhere else)
# wget http://download-mirror.savannah.gnu.org/releases/gpsd/gpsd-3.16.tar.gz
(file downloads)
# tar -xzvf gpsd-3.16.tar.gz
(file extracts)
# cd gpsd-1.16
# scons
(lots of build steps)
# scons check
(runs many tests)
# scons install
(installs stuff mostly to /usr/local/sbin/ and /usr/local/share/)
The above installs the software, but unfortunately there's a raft of extra configuration required that doesn't seem to be handled by the gpsd source distribution. My knowledge of systemd is limited, so it's possible I just did this all wrong.
The instructions in the gpsd file "build.txt" suggests installing with "scons udev-install", but this appears to hook into the udev code to start/invoke gpsd only when a USB-based GPS device is added. Since we're using the hardware serial port, we want GPSD running all the time, and the udev stuff looks spurious.
# /etc/default/gpsd # # Default settings for the gpsd init script and the hotplug wrapper. # Start the gpsd daemon automatically at boot time START_DAEMON="true" # Use USB hotplugging to add new USB devices automatically to the daemon USBAUTO="false" # Devices gpsd should collect to at boot time. # They need to be read/writeable, either by user gpsd or the group dialout. DEVICES="/dev/ttyAMA0 /dev/pps0" # Other options you want to pass to gpsd # # -n don't wait for client to connect; poll GPS immediately GPSD_OPTIONS="-n"
# systemctl daemon-reload # systemctl enable gpsd # systemctl start gpsd
# systemctl status gpsd
* gpsd.service - GPS (Global Positioning System) Daemon
Loaded: loaded (/etc/systemd/system/gpsd.service; enabled)
Active: active (running) since Fri 2018-03-09 19:52:51 UTC; 3s ago
Main PID: 24956 (gpsd)
CGroup: /system.slice/gpsd.service
+-24956 /usr/local/sbin/gpsd -N -n -b /dev/ttyAMA0 /dev/pps0
Mar 09 19:52:54 gpsclock.unixwiz.lan gpsd[24956]: gpsd:PROG: PPS:/dev/pps0 Assert cycle: 1985535384, duration: 999999 @ (null)
Mar 09 19:52:54 gpsclock.unixwiz.lan gpsd[24956]: gpsd:PROG: NTP: ntpshm_put(/dev/pps0 pps) 1520625174.000000000 @ 1520625173.999978052
...
At this point, if all is well, the gpsd service will be running and syncing with the GPS device. That doesn't necessarily mean that the GPS module has a fix on the satellites; that you can tell by looking at the Ultimate GPS hat for a brief red LED flash every 15 seconds. A LED that's flashing one second on/one second off has not yet acquired a fix.
Now for the moment of truth: we're going to launch the gpsmon program to see what the daemon is doing:
+------------------------------------------------------------------------------+ |Time: 2017-01-24T14:04:17.000Z Lat: 33 43' 23.556" N Lon: 117 49' 18.353" W | +--------------------------------- Cooked TPV ---------------------------------+ +------------------------------------------------------------------------------+ | GPGGA GPGSA GPRMC GPZDA GPGSV | +--------------------------------- Sentences ----------------------------------+ +------------------++----------------------------++----------------------------+ |Ch PRN Az El S/N ||Time: 140417.000 ||Time: 140417.000 | | 0 18 305 73 28 ||Latitude: 3343.3926 N ||Latitude: 3343.3926 | | 1 21 22 68 32 ||Longitude: 11749.3059 W ||Longitude: 11749.3059 | | 2 10 257 45 22 ||Speed: 0.19 ||Altitude: 16.2 | | 3 133 147 44 0 ||Course: 309.52 ||Quality: 2 Sats: 06 | | 4 15 62 40 17 ||Status: A FAA: D ||HDOP: 1.33 | | 5 29 155 32 26 ||MagVar: ||Geoid: -34.2 | | 6 20 52 29 0 |+----------- RMC ------------++----------- GGA ------------+ | 7 27 318 23 21 |+----------------------------++----------------------------+ | 8 16 277 22 16 ||Mode: A3 Sats: 18 21 10 15 ||UTC: RMS: | | 9 26 248 18 18 ||DOP: H=1.33 V=0.93 P=1.62 ||MAJ: MIN: | |10 13 41 15 0 ||TOFF: 0.487295282 ||ORI: LAT: | |11 32 194 12 0 ||PPS: 0.001810795 ||LON: ALT: | +------ GSV -------++-------- GSA + PPS ---------++----------- GST ------------+ (68) $GPGSV,4,1,13,18,73,305,28,21,68,022,32,48,47,206,,10,45,256,22*79 (68) $GPGSV,4,2,13,15,40,062,17,29,32,155,26,20,29,052,,27,23,318,21*73 (66) $GPGSV,4,3,13,16,22,277,16,26,18,248,18,13,15,041,,32,12,194,*79 (29) $GPGSV,4,4,13,24,04,115,*4C (72) $GPRMC,140410.000,A,3343.3923,N,11749.3054,W,0.30,313.36,240117,,,D*7B (35) $GPZDA,140410.000,24,01,2017,,*55 ------------------- PPS offset: -0.001808670 ------ (82) $GPGGA,140411.000,3343.3924,N,11749.3055,W,2,06,1.33,16.2,M,-34.2,M,0000,0000*64 (54) $GPGSA,A,3,15,29,10,26,21,18,,,,,,,1.62,1.33,0.93*0C (72) $GPRMC,140411.000,A,3343.3924,N,11749.3055,W,0.34,316.90,240117,,,D*71 (35) $GPZDA,140411.000,24,01,2017,,*54 ------------------- PPS offset: -0.001808677 ------ (82) $GPGGA,140412.000,3343.3925,N,11749.3056,W,2,06,1.33,16.2,M,-34.2,M,0000,0000*65 (54) $GPGSA,A,3,15,29,10,26,21,18,,,,,,,1.62,1.33,0.93*0C (72) $GPRMC,140412.000,A,3343.3925,N,11749.3056,W,0.19,316.43,240117,,,D*71 ...
The top line summarizes the best information collected from the GPS receiver, including the time (in UTC) and the current location, and the bottom portion of the screen shows the more or less raw data from the GPS unit.
Of particular import are the lines ---- PPS offset --- because they indicate proper handling of the pulse-per-second input.
Running this on the real console likely shows proper clean line drawing characters, but for an SSH session (putty or SecureCRT) you may need to set your terminal type to VT100 (via "TERM=vt100 gpsmon") so things look right.
If the top of the gpsmon display shows:
+------------------------------------------------------------------------------+ |Time: 1980-01-08T14:14:50.092Z Lat: n/a Lon: n/a | +--------------------------------- Cooked TPV ---------------------------------+
The lack of Lat/Lon indicates the GPS receiver has not obtained a satellite fix, and the time in 1980 indicates that it doesn't see one satellite to get a rough time.
Always check for the fix LED on the GPS hat itself, which should flash once every 15 seconds; if instead it's one second on/one second off, then it doesn't have a fix and there's not much that gpsmon can do for you.
Do not proceed to the next section until you get valid PPS input and valid GPS data showing up via gpsmon.
The final part of this project configures the NTP (Network Time Protocol) daemon to consume the GPS time, possibly correlate it with other sources, and make accurate time available to the local machine and the rest of the network.
Many have configured NTP to check in with time servers on the internet, there are many references on the internet about this; this is not a general tutorial about NTP. We're here only to hook into GPS.
Disclaimer: there is a lot of confusing stuff surrounding ntpd, and I'm not at all any kind of expert; I waffled my way through most of this, and still don't fully get most of the intricacies. Some of this information might be wrong.
The question is: how does NTP get the precise time from GPSD?, and the answer is via shared memory. NTPD supports multiple kinds of time drivers, and one of them is a set of shared memory segments that feeds accurate time to all callers.
Note that GPSD also provides a TCP-based network service for all of the data it collects (certainly location data), but the network service is not useful for accurate time; the shared memory segment is far more precise for process-to-process communications.
The configuration is a little tricky and is not at all intuititive, so we'll do checking in steps.
First is the tool ntpshmmon, which monitors shared memory as if it were a client, and reports the counters found:
# ntpshmmon ntpshmmon version 1 # Name Seen@ Clock Real L Prec sample NTP0 1485442395.871672922 1485442395.484197563 1485442395.000000000 0 -1 sample NTP2 1485442395.871817243 1485442395.006707787 1485442395.000000000 0 -20 sample NTP0 1485442396.371839022 1485442395.484197563 1485442395.000000000 0 -1 sample NTP2 1485442396.371890219 1485442396.006709260 1485442396.000000000 0 -20 sample NTP0 1485442396.872924176 1485442396.452044456 1485442396.000000000 0 -1 sample NTP2 1485442396.872965791 1485442396.006709260 1485442396.000000000 0 -20 sample NTP0 1485442397.373009183 1485442396.452044456 1485442396.000000000 0 -1 sample NTP2 1485442397.373049704 1485442397.006707661 1485442397.000000000 0 -20 ... ^C to interrupt
The key values here are NTP0 (which represents the time), and NTP2, which represents the PPS; I believe the "Prec" (precision) column is what identifies this but am not sure. These NTP# values are key for the next step.
In /etc/ntp.conf we often find a list of servers
![[Steve's Email]](/images/steve-email.gif)
![[RSS Feed available]](/images/feed-icon-14x14.png){kind=icon}