= Calibrating GPSD with ntpd HOWTO = <> v1.0, November 2013 This document is mastered in asciidoc format. If you are reading it in HTML, you can find the original at the GPSD project website. == Introduction == When using GPSD with ntpd, you will often find references to measuring the delay between the time that the GPS with 1PPS emits a fix, and the time that the ntpd service, via the shared memory segment, process it. This is the 'time1' factor in the typical configuration below, as documented in the gpsd man page. -------------------- server 127.127.28.0 minpoll 4 maxpoll 4 fudge 127.127.28.0 time1 0.420 refid GPS server 127.127.28.1 minpoll 4 maxpoll 4 prefer fudge 127.127.28.1 refid GPS1 -------------------- Note that the 'GPS' and 'GPS1' on the second and fourth lines above have no special meaning, they are used only for display. The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpd shared-memory driver; 127.127.28.1 identifies unit 1. Unit 0 is used for in-band message timestamps (IMT) and unit 1 for the (more accurate, when available) time derived from combining IMT with the out-of-band PPS synchronization pulse. Splitting these notifications allows ntpd to use its normal heuristics to weight them. We assume that the 1PPS signal, being just one bit long, and directly triggering an interrupt, is always on time (sic). Correcting for latency in the 1PPS signal is beyond the scope of this document. The IMT, however, may be delayed, due to it being emitted, copied to shared memory, etc. Based on advice and script fragments on the GPSD list, the following may help to calculate the 'time1' factor. You may need to modify these scripts for your particular setup. These scripts are for the combination of GPSD and ntpd. If you use chronyd, you *will* need to modify these, at the least. == Measuring Offsets == === Format of the loopstats and peerstats files === The following is incorporated from the ntpd website, see <> .loopstats Record clock discipline loop statistics. Each system clock update appends one line to the loopstats file set: Example: 50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6 |================================ |Item |Units |Description |50935 |MJD |date |75440.031 |s |time past midnight |0.000006019 |s |clock offset |13.778 |PPM |frequency offset |0.000351733 |s |RMS jitter |0.013380 |PPM |RMS frequency jitter (aka wander) |6 |log2 s |clock discipline loop time constant |================================= .peerstats Record peer statistics. Each NTP packet or reference clock update received appends one line to the peerstats file set: Example: 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 |================================ |Item |Units |Description |48773 |MJD |date |10847.650 |s |time past midnight |127.127.4.1 |IP |source address |9714 |hex |status word |-0.001605376 |s |clock offset |0.000000000 |s |roundtrip delay |0.001424877 |s |dispersion |0.000958674 |s |RMS jitter |================================ === Measurement of delay === There are three parts to measuring and correcting for the delay in processing the 1PPS signal. 1. Running ntpd without using the IMT (but using the 1PPS time) 2. Measuring the delay between the two messages 3. Applying the correction factor We assume that you have successfully integrated GPSD with ntpd already. You should also have a decent set of NTP servers you are syncing to. ==== 1. Running ntpd without IMT ==== Locate the line in your ntp.conf that refers to the shm0 segment and append 'noselect' to it. As an example, the first two lines in the sample above will become: -------------------- server 127.127.28.0 minpoll 4 maxpoll 4 noselect fudge 127.127.28.0 time1 0.420 refid GPS -------------------- ntpd will now continue to monitor the IMT from GPSD, but not use it for its clock selection algorithm. It will still write out statistics to the peerstats file. Once ntpd is stable (a few hours or so), we can process the peerstats file. ==== 2. Measuring the delay between the two messages ==== From the 'peerstats' file, extract the lines corresponding to 127.127.28.0 ----------- grep 127.127.28.0 peerstats > peerstats.shm ----------- You can now examine the offset and jitter of the IMT. <> suggests the following gnuplot fragment (you will need to set output options before plotting). ---------------- set term gif set output "fudge.gif" ---------------- If your gnuplot has X11 support, and you do not wish to save the plot, the above may not be required. Use: --------------- set term x11 --------------- Now plot the GPSD shared memory clock deviations from the system clock. (You will get the GPSD shared memory clock fudge value estimate from this data when NTP has converged to your satisfaction.) ------------------ gnuplot> plot "peerstats.shm" using ($2):($5):($8) with yerrorbars gnuplot> replot "peerstats.shm" using ($2):($5) with lines ------------------ ==== 3. Applying the correction factor ==== By examining the plot generated above, you should be able to estimate the offset between the 1PPS time and the GPS Time. If, for example, your estimate of the offset is -0.32s, your time1 fudge value will be '0.32'. Note the change of sign. == Acknowledgments == This HOWTO was drafted by Sanjeev Gupta , based on discussions on the GPSD list <> in Oct and Nov 2013. Code examples are based on work by Andy Walls . A copy of the original email can be found at <>. A thorough review was contributed by Jaap Winius . == References == [bibliography] - [[[ANDY-POST]]] http://lists.gnu.org/archive/html/gpsd-dev/2013-10/msg00152.html[Clarifications needed for the time-service HOWTO] - [[[NTP-MONOPT]]] http://www.eecis.udel.edu/~mills/ntp/html/monopt.html[NTP Monitoring] - [[[GPSD-LIST]]]http://lists.gnu.org/archive/html/gpsd-dev[gpsd-dev Archives] - [[[WIKI-NTP]]] http://en.wikipedia.org/wiki/Network_Time_Protocol[Network Time Protocol] - [[[NTP-FAQ]]] http://www.ntp.org/ntpfaq/[NTP FAQ] - [[[NTP.ORG]]] http://www.ntp.org/[Home of the Network Time Protocol project]