contrib/ntp/html/drivers/driver46.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html><head>
   3     <meta http-equiv="Content-Type"
   4     content="text/html;charset=iso-8859-1"><title>GPSD-NG client driver</title>
   5
   6     <link href="scripts/style.css" type="text/css" rel="stylesheet">
   7     <style type="text/css">
   8       table.dlstable { font-size:85%; }
   9       td.ttf{ font-family:Courier; font-weight:bold; }
  10     </style></head>
  11
  12
  13
  14   <body>
  15     <h3>GPSD NG client driver</h3>
  16 <p>Last update:
  17   <!-- #BeginDate format:En2m -->30-Apr-2015  05:53<!-- #EndDate -->
  18   UTC</p>
  19     <hr>
  20     <h4>Synopsis</h4>
  21
  22     <p>
  23       Address: 127.127.46.<i>u</i><br>
  24       Reference ID: <tt>GPSD</tt><br>
  25       Driver ID: <tt>GPSD_JSON</tt><br>
  26       Serial Port: <tt>/dev/gps<i>u</i></tt> as symlink to the true
  27       device (not used directly; see below)<br>
  28       Features: <tt></tt>
  29     </p>
  30
  31     <!-- --------------------------------------------------------- -->
  32
  33     <br><h4>Description</h4>
  34     <p>
  35       This driver is a client driver to the <i>GPSD</i> daemon, which
  36       over the time became increasingly popular for UN*Xish
  37       platforms. <i>GPSD</i> can manage several devices in parallel,
  38       aggregate information, and acts as a data hub for client
  39       applications. <i>GPSD</i> can also auto-detect and handle PPS
  40       hardware signals on serial ports. Have a look
  41       at <a href="http://www.catb.org/gpsd/">the
  42       <i>GPSD</i> project page</a>.
  43     </p>
  44     <p>
  45       <b>It is important to understand that this driver works best
  46       using a GPS device with PPS support.</b>
  47     </p>
  48     <p>
  49       The GPSD-NG protocol is text based, using JSON notation to
  50       transfer records in form of JSON objects. The driver uses a
  51       TCP/IP connection to <tt>localhost:gpsd</tt> to connect to the
  52       daemon and then requests the GPS
  53       device <tt>/dev/gps<i>u</i></tt> to be watched. (Different clock
  54       units use different devices, and
  55       <i>GPSD</i> is able to give only the relevant information to a clock
  56       instance.)
  57     </p>
  58     <p>
  59       This driver does not expect <i>GPSD</i> to be running or the
  60       clock device to be present <i>a priori</i>; it will try to
  61       re-establish a lost or hitherto unsuccessful connection and will
  62       wait for device to come up in <i>GPSD.</i> There is an initial
  63       10 seconds delay between a connection loss or failed attempt and
  64       the next reconnect attempt; this makes sure that there is no
  65       thrashing on the network layer. If the connection fails again,
  66       an exponential back off is used with an upper limit of
  67       approximately 10 minutes.
  68     </p>
  69     <p>
  70       The overall accuracy depends on the receiver used. The driver
  71       uses the error estimations (95% probability limits) provided by
  72       <i>GPSD</i> to set the clock precision dynamically according to
  73       these readings.
  74     </p>
  75     <p>
  76       The driver needs the VERSION, TPV, PPS, WATCH and TOFF objects
  77       of the <i>GPSD</i> protocol. (Others are quietly ignored.) The
  78       driver can operate without the TOFF objects, which are available
  79       with the <i>protocol</i> version 3.10 and above. (Not to be
  80       confused with the <i>release</i> version of <i>GPSD</i>!)
  81       Running without TOFF objects has a negative impact on the jitter
  82       and offset of the serial timing information; if possible, a
  83       version of <i>GPSD</i> with support for TOFF objects should be
  84       used.
  85     </p>
  86     <p>The acronym <u>STI</u> is used here as a synonym for <i>serial
  87       time information</i> from the data channel of the receiver, no
  88       matter what objects were used to obtain it.
  89     </p>
  90
  91     <!-- --------------------------------------------------------- -->
  92
  93     <br><h4>Naming a Device</h4>
  94     <p>
  95       The <i>GPSD</i> driver uses the same device name as the NMEA
  96       driver, namely <tt>/dev/gps<i>u</i></tt>. There is a simple
  97       reason for that: While the NMEA driver and the <i>GPSD</i>
  98       driver can be active at the same time <b>for different
  99       devices</b>, they cannot access the same device at a
 100       time. Having the same name helps on that. It also eases
 101       migration from using NMEA directly to using <i>GPSD</i>, as no
 102       new links etc need to be created.
 103     </p>
 104     <p>
 105       <i>GPSD</i> is normally started with the device name to access;
 106       it can also be instructed by hot-plug scripts to add or remove
 107       devices from its device pool. Luckily, the symlinks used by the
 108       NMEA driver are happily accepted and used by <i>GPSD</i>; this
 109       makes it possible to use the symlink names as device
 110       identification. This makes the migration from the built-in NMEA
 111       driver a bit easier.
 112     </p>
 113     <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot use kernel
 114       mode PPS on devices that are hot-plugged. This would require to
 115       attach the PPS line discipline to the character special file,
 116       which is not possible when running with root privileges already
 117       dropped. This is not likely to change in the future.
 118     </p>
 119
 120     <!-- --------------------------------------------------------- -->
 121
 122     <br><h4>The 'mode' word</h4>
 123     <p>
 124       A few operation modes can be selected with the mode word.
 125     </p>
 126     <p>
 127       <table border="1" frame="box" rules="all">
 128       <th colspan="3">The Mode Word</th>
 129         <tr> <td>Bits</td><td>Value</td><td>Description</td>
 130         </tr>
 131         <tr> <td rowspan="4"align="center">0..1</td>
 132           <td align="center">0</td>
 133           <td>STI only operation. This mode is affected by the timing
 134             stability of whatever protocol is used between the GPS
 135             device and GPSD.
 136             <br>
 137             Running on STI only is not recommended in general. Possible
 138             use cases include:
 139             <ul>
 140               <li>The receiver does not provide a PPS signal.
 141               <li>The receiver <i>does</i> provide a PPS signal and
 142               the secondary PPS unit is used.
 143               <li>The receiver has a stable serial timing and a proper
 144               fudge can be established.
 145               <li>You have other time sources available and want to
 146                 establish a useful fudge value for <tt>time2</tt>.
 147             </ul>
 148           </td>
 149         </tr>
 150         <tr>
 151           <td align="center">1</td>
 152           <td>Strict operation. This mode needs a valid PPS and a
 153             valid STI to combine the absolute time from the STI with
 154             the time stamp from the PPS record. Does not feed clock
 155             samples if no valid PPS+STI pair is available.
 156             <br><br>
 157             This type of operation results in an ordinary clock with a
 158             very low jitter as long as the PPS data is available, but
 159             the clock fails once PPS drops out. This mode is a
 160             possible choice for receivers that provide a PPS signal
 161             most of the time but have an unstable serial timing that
 162             cannot be fudge-compensated.
 163           </td>
 164         </tr>
 165         <tr><td align="center">2</td>
 166           <td>Automatic mode. Tries to operate in strict mode unless
 167             it fails to process valid samples for some time, currently
 168             120s. Then it reverts to STI-only operation until the PPS
 169             is stable again for 40s, when strict mode is engaged
 170             again.
 171             <br><br><b>Important Notice: This is an expiremental
 172             feature!</b><br>  Switching between strict and STI-only
 173             mode will cause changes in offset and jitter. Use this
 174             mode only if STI-only works fairly well with your setup,
 175             or if you expect longer dropouts of the PPS signal and
 176             prefer to use STI alone over not getting synchronised at
 177             all.</td>
 178         </tr>
 179         <tr>
 180           <td align="center">3</td>
 181           <td><i>(reserved for future extension, do not use)</i></td>
 182         </tr>
 183         <tr>
 184           <td align="center">2..31</td>
 185           <td colspan="2"><i>(reserved for future extension, do not
 186           use)</i></td>
 187         </tr>
 188       </table>
 189     </p>
 190
 191     <!-- --------------------------------------------------------- -->
 192
 193     <br><h4>Syslog flood throttle</h4>
 194     <p>This driver can create a lot of syslog messages when things go
 195       wrong, and cluttering the log files is frowned upon. So we
 196       attempt to log persistent or recurring errors only once per
 197       hour. On the other hand, when tracking a problem the syslog
 198       flood throttle can get into the way.</p>
 199     <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the
 200       flood throttle at any time; the throttle is engaged by
 201       default. Running with the syslog flood throttle disabled for
 202       lengthy time is not recommended unless the log files are closely
 203       monitored.</p>
 204
 205     <!-- --------------------------------------------------------- -->
 206
 207     <br><h4>PPS secondary clock unit</h4>
 208     <p>Units with numbers &ge;128 act as secondary clock unit for the
 209       primary clock unit (u mod 128). A secondary unit processes only
 210       the PPS data from <i>GPSD</i> and needs the corresponding master
 211       unit to work<a href="#fn1" name="fn1bl"><sup>1</sup></a>. Use
 212       the 'noselect' keyword on the primary unit if you are not
 213       interested in its data.
 214     </p><p>The secondary unit employs the usual precautions before
 215       feeding clock samples:</p>
 216     <ul>
 217       <li>The system must be already in a synchronised state.
 218       <li>The system offset must be less than 400ms absolute.
 219       <li>The phase adjustment from the PPS signal must also be less
 220         than 400ms absolute.
 221     </ul>
 222     <p>If fudge flag <tt>flag1</tt> is set for the secondary unit, the
 223       unit asserts the PPS flag on the clock as long as PPS data is
 224       available. This makes the unit eligible as PPS peer and should
 225       only be used if the GPS receiver can be trusted for the quality
 226       of its PPS signal<a href="fn2"
 227       name="fn2bl"><sup>2</sup></a>. The PPS flag gets cleared if no
 228       PPS records can be aquired for some time. The unit also flushes
 229       the sample buffer at this point to avoid the use of stale PPS
 230       data.</p>
 231     <p><b>Attention:</b> This unit uses its own PPS fudge value
 232       which must be set as fudge <tt>time1</tt>. Only the fudge
 233       values <tt>time1</tt> and <tt>flag1</tt> have an impact on secondary
 234       units.</p>
 235
 236     <!-- --------------------------------------------------------- -->
 237
 238     <br><h4>Clockstats</h4>
 239     <p>If flag4 is set when the driver is polled, a clockstats record
 240       is written for the primary clock unit. (The secondary PPS unit
 241       does not provide clock stats on its own.) The first 3 fields are
 242       the normal date, time, and IP address common to all clockstats
 243       records.
 244     </p><p>
 245       <table border="1" frame="box" rules="all">
 246         <th colspan="2">The Clockstats Line</th>
 247         <tr> <td>field</td><td>Description</td> </tr>
 248         <tr>
 249           <td align="center">1</td>
 250           <td>Date as day number since NTP epoch.</td>
 251         </tr><tr>
 252           <td align="center">2</td>
 253           <td>Time as seconds since midnight.</td>
 254         </tr><tr>
 255           <td align="center">3</td>
 256           <td>(Pseudo-) IP address of clock unit.</td>
 257         </tr><tr>
 258           <td align="center">4</td>
 259           <td>Number of received known JSON records since last
 260             poll. The driver knows about TPV, PPS, TOFF, VERSION and
 261             WATCH records; others are silently ignored.
 262           </td>
 263         </tr><tr>
 264           <td align="center">5</td>
 265           <td>Bad replies since last poll. A record is considered
 266             malformed or a bad reply when it is missing vital fields
 267             or the fields contain malformed data that cannot be
 268             parsed.
 269           </td>
 270         </tr><tr>
 271           <td align="center">6</td>
 272           <td>Number of sample cycles since last poll that were
 273             discarded because there was no GPS fix. This is
 274             effectively the number of TPV records with a fix value
 275             &lt; 2 or without a time stamp.
 276           </td>
 277         </tr><tr>
 278           <td align="center">7</td>
 279           <td>Number of serial time information records (TPV or TOFF,
 280             depending on the GPSD version) received since last poll.
 281           </td>
 282         </tr><tr>
 283           <td align="center">8</td>
 284           <td>Number of serial time information records used for
 285             clock samples since the last poll.
 286           </td>
 287         </tr><tr>
 288           <td align="center">9</td>
 289           <td>Number of PPS records received since the last poll.</td>
 290         </tr><tr>
 291           <td align="center">10</td>
 292           <td>Number of PPS records used for clock samples on the
 293             secondary channel since the last poll.
 294           </td>
 295         </tr>
 296       </table>
 297     </p>
 298
 299     <!-- --------------------------------------------------------- -->
 300
 301     <br><h4>Fudge Factors</h4>
 302
 303     <dl>
 304       <dt><tt>time1 <i>time</i></tt></dt>
 305       <dd>Specifies the PPS time offset calibration factor, in seconds
 306       and fraction, with default 0.0.</dd>
 307       <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt>
 308       <dd><em>[Primary Unit]</em> Specifies the TPV/TIME time offset
 309       calibration factor, in seconds and fraction, with default
 310       0.0.</dd>
 311       <dt><tt>stratum <i>number</i></tt></dt>
 312       <dd>Specifies the driver stratum, in decimal from 0 to 15, with
 313         default 0.</dd>
 314       <dt><tt>refid <i>string</i></tt></dt>
 315       <dd>Specifies the driver reference identifier, an ASCII string
 316         from one to four characters, with default <tt>GPSD</tt>.</dd>
 317       <dt><tt>flag1 0 | 1</tt></dt><dd><em>[<b>Secondary</b>
 318           Unit]</em> When set, flags the secondary clock unit as a
 319         potential PPS peer as long as good PPS data is available.
 320       </dd>
 321       <dt><tt>flag2 0 | 1</tt></dt>
 322       <dd><em>[Primary Unit]</em> When set, <u>disables</u> the
 323         processing of incoming PPS records. Intended as an aide to
 324         test the effects of a PPS dropout when using automatic mode
 325         (mode 2).
 326       </dd>
 327       <dt><tt>flag3 0 | 1</tt></dt><dd><em>[Primary Unit]</em>
 328       If set, <u>disables</u> the log throttle. Useful when tracking
 329       problems in the interaction between <i>GPSD</i> and <i>NTPD</i>,
 330       since now all error events are logged. Persistent/recurrent
 331       errors can easily fill up the log, so this should only be
 332       enabled during bug hunts.</dd>
 333       <dt><tt>flag4 0 | 1</tt></dt><dd><em>[Primary Unit]</em>
 334         If set, write a clock stats line on every poll cycle.
 335       </dd>
 336     </dl>
 337
 338     <!-- -- footnotes -------------------------------------------- -->
 339
 340     <hr>
 341     <p><a name="fn1" href="#fn1bl"><sup>1</sup>) </a>Data transmission
 342       an decoding is done only once by the primary unit. The decoded
 343       data is then processed independently in both clock units. This
 344       avoids double transmission over two sockets and decoding the
 345       same data twice, but the primary unit is always needed as a
 346       downside of this approach.
 347     </p>
 348     <p><a name="fn2" href="#fn2bl"><sup>2</sup>) </a>The clock driver
 349       suppresses the processing PPS records when the TPV/TIME data
 350       indicates the receiver has no fix. It can also deal with
 351       situations where the PPS signal is not delivered
 352       to <i>GPSD</i>. But once it is available, it is also processed
 353       and used to create samples. If a receiver cannot be trusted for
 354       the precision of its PPS signal, it should not be used to create
 355       a possible PPS peer: These get extra clout and can effectively
 356       become the sole source of input for the control loop. You do not
 357       want to use sloppy data for that.
 358     <hr>
 359     <p>Additional Information</p>
 360     <p><a href="../refclock.html">Reference Clock Drivers</a></p>
 361     <hr>
 362     <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
 363   </body></html>