diff options
| -rw-r--r-- | TODO | 4 | ||||
| -rw-r--r-- | www/calibrate-gpsd-ntpd-howto.txt | 181 | ||||
| -rw-r--r-- | www/gpsd-time-service-howto.txt | 166 |
3 files changed, 162 insertions, 189 deletions
@@ -16,10 +16,6 @@ See the GPSD bug tracker on the project website, but don't be surprised if it's empty or very sparse. Our rate of new defects per month is quite low. -*** Documentation - -Consider merging the calibration draft into the Time Service HOWTO. - *** Time tracking Our goal is to be independent of the system clock. diff --git a/www/calibrate-gpsd-ntpd-howto.txt b/www/calibrate-gpsd-ntpd-howto.txt deleted file mode 100644 index 60819fe7..00000000 --- a/www/calibrate-gpsd-ntpd-howto.txt +++ /dev/null @@ -1,181 +0,0 @@ -= 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 == - - - -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 <<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 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. <<ANDY-POST>> -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 <ghane0@gmail.com>, based on -discussions on the GPSD list <<GPSD-LIST>> in Oct and Nov 2013. Code -examples are based on work by Andy Walls <andy@silverblocksystems.net>. -A copy of the original email can be found at <<ANDY-POST>>. - -A thorough review was contributed by Jaap Winius <jwinius@rjsystems.nl>. - -== 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] diff --git a/www/gpsd-time-service-howto.txt b/www/gpsd-time-service-howto.txt index 9d3e6d8b..a9ea088e 100644 --- a/www/gpsd-time-service-howto.txt +++ b/www/gpsd-time-service-howto.txt @@ -1,6 +1,6 @@ = GPSD Time Service HOWTO = Gary E. Miller <gem@rellim.com>, Eric S. Raymond <esr@thyrsus.com> -v1.4, Dec 2014 +v2.0, Feb 2015 This document is mastered in asciidoc format. If you are reading it in HTML, you can find the original at the GPSD project website. @@ -1047,7 +1047,9 @@ so GPS time is never used, just monitored. A more detailed description of the output is available at <<NTPQ-OUTPUT>>. -In order to determine the correct GPS offset, do the following: +In order to determine the correct GPS offset, do one of the following: + +==== Peerstats-based procedure ==== [start=1] 1. Add these lines to ntp.conf: @@ -1090,9 +1092,148 @@ This prints the average offset. 5. Adjust the "time1" value for unit 0 of your ntp.conf (the non-PPS channel) by subtracting the average offset from step 4. +[start=6] 6. Restart ntpd. -== Chrony peformance tuning +==== Loopstats-based procedure ==== + +Recall that 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. + +===== 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 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. + +[start=1] +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. + +[start=2] +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. <<ANDY-POST>> +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 +------------------ + +[start=3] +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. + +== Chrony performance tuning The easiest way to determine the offset with chronyd is probably to configure the source whose offset should be measured with the noselect @@ -1137,6 +1278,13 @@ much of the section on NTP working and performance details. Sanjeev Gupta <ghane0@gmail.com> assisted with editing. Shawn Kohlsmith <skohlsmith@gmail.com> tweaked the Bibliography. +The loopstats-based tuning procedure for ntpd was drafted by Sanjeev +Gupta <ghane0@gmail.com>, based on discussions on the GPSD list +<<GPSD-LIST>> in Oct and Nov 2013. Code examples are based on work by +Andy Walls <andy@silverblocksystems.net>. A copy of the original +email can be found at <<ANDY-POST>>. A thorough review was contributed +by Jaap Winius <jwinius@rjsystems.nl>. + == References == [bibliography] @@ -1178,6 +1326,14 @@ Shawn Kohlsmith <skohlsmith@gmail.com> tweaked the Bibliography. - [[[JOIN-POOL]]] http://www.pool.ntp.org/en/join.html[How do I join pool.ntp.org?] +- [[[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] + == Changelog == 1.1, Nov 2013: Initial release. @@ -1188,4 +1344,6 @@ Shawn Kohlsmith <skohlsmith@gmail.com> tweaked the Bibliography. 1.4, Dec 2014: Cleaned up Bibliography -Repository: More about troubleshooting PPS delivery. +2.0, Feb 2015: More about troubleshooting PPS delivery. Folded in Sanjeev +Guota's Calibration Howto describing the loopstats-based procedure. + |