[gpsd-dev] [PATCH 1/1] Initial draft; how to estimate time1 offset

[Sanjeev Gupta]

This is based on Andy Walls et al.
---
 www/calibrate-gpsd-ntpd-howto.txt | 161 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 www/calibrate-gpsd-ntpd-howto.txt

diff --git a/www/calibrate-gpsd-ntpd-howto.txt 
b/www/calibrate-gpsd-ntpd-howto.txt
new file mode 100644
index 0000000..610df9a
--- /dev/null
+++ b/www/calibrate-gpsd-ntpd-howto.txt
@@ -0,0 +1,161 @@
+= Calibrating GPSD with ntpd HOWTO =
+<<FIX-ME Attribution>>
+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 ==
+
+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 first two lines (127.127.28.0) refer to the shared memory segment
+to report message-decode time, the next stanza (127.127.28.1) is used for 
+the 1PPS time.
+
+We assume that the 1PPS signal, being just one bit long, and directly
+triggering an interrupt, is always on time.  The message-decode time,
+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 <<NTP-MONOPT>>
+
+.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 GPSD time (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 GPSD time ====
+
+Locate the line in your ntp.conf which 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 GPS time from GPSD, but not use 
+for its algorithm.  It will 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 GPS time.  <<ANDY-POST>>
+suggests the following gnuplot fragment (you will need to set output
+options before plotting).
+
+Show 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) with lines 1
+        gnuplot> replot  "peerstats.shm" using ($2):($5):($8) with yerrorbars 2
+------------------
+
+==== 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 <address@hidden>, based on
+discussions on the GPSD list <<GPSD-LIST>> in Oct and Nov 2013.  Code 
+examples are based on work by Andy Walls <address@hidden>.
+A copy of the original email can be found at <<ANDY-POST>>.
+
+== 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]
+
-- 
1.8.4.2