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 By default, the <i>GPSD</i> driver uses the same device name as 96 the NMEA driver, namely <tt>/dev/gps<i>u</i></tt>. There is a 97 simple reason for that: While the NMEA driver and 98 the <i>GPSD</i> driver can be active at the same time <b>for 99 different 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> 114 The driver also honors <tt>device</tt> statements for 115 the <tt>timedata</tt> channel. (PPS is handled 116 inside <i>GPSD</i>, so there's no need for that.) This permits a 117 more natural way to specify the link between <i>GPSD</i> 118 and <i>NTPD</i>: Simply name the device as it was given 119 to <i>GPSD</i>. 120 </p> 121 <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot use kernel 122 mode PPS on devices that are hot-plugged or activated on demand. 123 This is not likely to change in the future. Have a look 124 at <i>GPSD</i>'s <tt>-n</tt> (<i>nowait</i>) option. 125 </p> 126 127 <!-- --------------------------------------------------------- --> 128 129 <br><h4>The 'mode' word</h4> 130 <p> 131 A few operation modes can be selected with the mode word. 132 </p> 133 <p> 134 <table border="1" frame="box" rules="all"> 135 <th colspan="3">The Mode Word</th> 136 <tr> <td>Bits</td><td>Value</td><td>Description</td> 137 </tr> 138 <tr> <td rowspan="4"align="center">0..1</td> 139 <td align="center">0</td> 140 <td>STI only operation. This mode is affected by the timing 141 stability of whatever protocol is used between the GPS 142 device and GPSD. 143 <br> 144 Running on STI only is not recommended in general. Possible 145 use cases include: 146 <ul> 147 <li>The receiver does not provide a PPS signal. 148 <li>The receiver <i>does</i> provide a PPS signal and 149 the secondary PPS unit is used. 150 <li>The receiver has a stable serial timing and a proper 151 fudge can be established. 152 <li>You have other time sources available and want to 153 establish a useful fudge value for <tt>time2</tt>. 154 </ul> 155 </td> 156 </tr> 157 <tr> 158 <td align="center">1</td> 159 <td>Strict operation. This mode needs a valid PPS and a 160 valid STI to combine the absolute time from the STI with 161 the time stamp from the PPS record. Does not feed clock 162 samples if no valid PPS+STI pair is available. 163 <br><br> 164 This type of operation results in an ordinary clock with a 165 very low jitter as long as the PPS data is available, but 166 the clock fails once PPS drops out. This mode is a 167 possible choice for receivers that provide a PPS signal 168 most of the time but have an unstable serial timing that 169 cannot be fudge-compensated. 170 </td> 171 </tr> 172 <tr><td align="center">2</td> 173 <td>Automatic mode. Tries to operate in strict mode unless 174 it fails to process valid samples for some time, currently 175 120s. Then it reverts to STI-only operation until the PPS 176 is stable again for 40s, when strict mode is engaged 177 again. 178 <br><br><b>Important Notice: This is an experimental 179 feature!</b><br> Switching between strict and STI-only 180 mode will cause changes in offset and jitter. Use this 181 mode only if STI-only works fairly well with your setup, 182 or if you expect longer dropouts of the PPS signal and 183 prefer to use STI alone over not getting synchronised at 184 all.</td> 185 </tr> 186 <tr> 187 <td align="center">3</td> 188 <td><i>(reserved for future extension, do not use)</i></td> 189 </tr> 190 <tr> 191 <td align="center">2..31</td> 192 <td colspan="2"><i>(reserved for future extension, do not 193 use)</i></td> 194 </tr> 195 </table> 196 </p> 197 198 <!-- --------------------------------------------------------- --> 199 200 <br><h4>Syslog flood throttle</h4> 201 <p>This driver can create a lot of syslog messages when things go 202 wrong, and cluttering the log files is frowned upon. So we 203 attempt to log persistent or recurring errors only once per 204 hour. On the other hand, when tracking a problem the syslog 205 flood throttle can get into the way.</p> 206 <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the 207 flood throttle at any time; the throttle is engaged by 208 default. Running with the syslog flood throttle disabled for 209 lengthy time is not recommended unless the log files are closely 210 monitored.</p> 211 212 <!-- --------------------------------------------------------- --> 213 214 <br><h4>PPS secondary clock unit</h4> 215 <p>Units with numbers ≥128 act as secondary clock unit for the 216 primary clock unit (u mod 128). A secondary unit processes only 217 the PPS data from <i>GPSD</i> and needs the corresponding master 218 unit to work<a href="#fn1" name="fn1bl"><sup>1</sup></a>. Use 219 the '<tt>noselect</tt>' keyword on the primary unit if you are not 220 interested in its data. 221 </p><p>The secondary unit employs the usual precautions before 222 feeding clock samples:</p> 223 <ul> 224 <li>The system must be already in a synchronised state. 225 <li>The system offset must be less than 400ms absolute. 226 <li>The phase adjustment from the PPS signal must also be less 227 than 400ms absolute. 228 </ul> 229 <p>If fudge flag <tt>flag1</tt> is set for the secondary unit, the 230 unit asserts the PPS flag on the clock as long as PPS data is 231 available. This makes the unit eligible as PPS peer and should 232 only be used if the GPS receiver can be trusted for the quality 233 of its PPS signal<a href="fn2" 234 name="fn2bl"><sup>2</sup></a>. The PPS flag gets cleared if no 235 PPS records can be acquired for some time. The unit also flushes 236 the sample buffer at this point to avoid the use of stale PPS 237 data.</p> 238 <p><b>Attention:</b> This unit uses its own PPS fudge value 239 which must be set as fudge <tt>time1</tt>. Only the fudge 240 values <tt>time1</tt> and <tt>flag1</tt> have an impact on secondary 241 units.</p> 242 243 <!-- --------------------------------------------------------- --> 244 245 <br><h4>Clockstats</h4> 246 <p>If flag4 is set when the driver is polled, a clockstats record 247 is written for the primary clock unit. (The secondary PPS unit 248 does not provide clock stats on its own.) The first 3 fields are 249 the normal date, time, and IP address common to all clockstats 250 records. 251 </p><p> 252 <table border="1" frame="box" rules="all"> 253 <th colspan="2">The Clockstats Line</th> 254 <tr> <td>field</td><td>Description</td> </tr> 255 <tr> 256 <td align="center">1</td> 257 <td>Date as day number since NTP epoch.</td> 258 </tr><tr> 259 <td align="center">2</td> 260 <td>Time as seconds since midnight.</td> 261 </tr><tr> 262 <td align="center">3</td> 263 <td>(Pseudo-) IP address of clock unit.</td> 264 </tr><tr> 265 <td align="center">4</td> 266 <td>Number of received known JSON records since last 267 poll. The driver knows about TPV, PPS, TOFF, VERSION and 268 WATCH records; others are silently ignored. 269 </td> 270 </tr><tr> 271 <td align="center">5</td> 272 <td>Bad replies since last poll. A record is considered 273 malformed or a bad reply when it is missing vital fields 274 or the fields contain malformed data that cannot be 275 parsed. 276 </td> 277 </tr><tr> 278 <td align="center">6</td> 279 <td>Number of sample cycles since last poll that were 280 discarded because there was no GPS fix. This is 281 effectively the number of TPV records with a fix value 282 < 2 or without a time stamp. 283 </td> 284 </tr><tr> 285 <td align="center">7</td> 286 <td>Number of serial time information records (TPV or TOFF, 287 depending on the GPSD version) received since last poll. 288 </td> 289 </tr><tr> 290 <td align="center">8</td> 291 <td>Number of serial time information records used for 292 clock samples since the last poll. 293 </td> 294 </tr><tr> 295 <td align="center">9</td> 296 <td>Number of PPS records received since the last poll.</td> 297 </tr><tr> 298 <td align="center">10</td> 299 <td>Number of PPS records used for clock samples on the 300 secondary channel since the last poll. 301 </td> 302 </tr> 303 </table> 304 </p> 305 306 <!-- --------------------------------------------------------- --> 307 308 <br><h4>Fudge Factors</h4> 309 310 <dl> 311 <dt><tt>time1 <i>time</i></tt></dt> 312 <dd>Specifies the PPS time offset calibration factor, in seconds 313 and fraction, with default 0.0.</dd> 314 <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> 315 <dd><em>[Primary Unit]</em> Specifies the TPV/TIME time offset 316 calibration factor, in seconds and fraction, with default 317 0.0.</dd> 318 <dt><tt>stratum <i>number</i></tt></dt> 319 <dd>Specifies the driver stratum, in decimal from 0 to 15, with 320 default 0.</dd> 321 <dt><tt>refid <i>string</i></tt></dt> 322 <dd>Specifies the driver reference identifier, an ASCII string 323 from one to four characters, with default <tt>GPSD</tt>.</dd> 324 <dt><tt>flag1 0 | 1</tt></dt><dd><em>[<b>Secondary</b> 325 Unit]</em> When set, flags the secondary clock unit as a 326 potential PPS peer as long as good PPS data is available. 327 </dd> 328 <dt><tt>flag2 0 | 1</tt></dt> 329 <dd><em>[Primary Unit]</em> When set, <u>disables</u> the 330 processing of incoming PPS records. Intended as an aide to 331 test the effects of a PPS dropout when using automatic mode 332 (mode 2). 333 </dd> 334 <dt><tt>flag3 0 | 1</tt></dt><dd><em>[Primary Unit]</em> 335 If set, <u>disables</u> the log throttle. Useful when tracking 336 problems in the interaction between <i>GPSD</i> and <i>NTPD</i>, 337 since now all error events are logged. Persistent/recurrent 338 errors can easily fill up the log, so this should only be 339 enabled during bug hunts.</dd> 340 <dt><tt>flag4 0 | 1</tt></dt><dd><em>[Primary Unit]</em> 341 If set, write a clock stats line on every poll cycle. 342 </dd> 343 </dl> 344 345 <!-- -- footnotes -------------------------------------------- --> 346 347 <hr> 348 <p><a name="fn1" href="#fn1bl"><sup>1</sup>) </a>Data transmission 349 an decoding is done only once by the primary unit. The decoded 350 data is then processed independently in both clock units. This 351 avoids double transmission over two sockets and decoding the 352 same data twice, but the primary unit is always needed as a 353 downside of this approach. 354 </p> 355 <p><a name="fn2" href="#fn2bl"><sup>2</sup>) </a>The clock driver 356 suppresses the processing PPS records when the TPV/TIME data 357 indicates the receiver has no fix. It can also deal with 358 situations where the PPS signal is not delivered 359 to <i>GPSD</i>. But once it is available, it is also processed 360 and used to create samples. If a receiver cannot be trusted for 361 the precision of its PPS signal, it should not be used to create 362 a possible PPS peer: These get extra clout and can effectively 363 become the sole source of input for the control loop. You do not 364 want to use sloppy data for that. 365 <hr> 366 <p>Additional Information</p> 367 <p><a href="../refclock.html">Reference Clock Drivers</a></p> 368 <hr> 369 <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 370 </body></html> 371