1275970Scy<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2275970Scy<html><head> 3275970Scy <meta http-equiv="Content-Type" 4275970Scy content="text/html;charset=iso-8859-1"><title>GPSD-NG client driver</title> 5275970Scy 6275970Scy <link href="scripts/style.css" type="text/css" rel="stylesheet"> 7275970Scy <style type="text/css"> 8275970Scy table.dlstable { font-size:85%; } 9275970Scy td.ttf{ font-family:Courier; font-weight:bold; } 10275970Scy </style></head> 11275970Scy 12275970Scy 13275970Scy 14275970Scy <body> 15275970Scy <h3>GPSD NG client driver</h3> 16275970Scy<p>Last update: 17285612Sdelphij <!-- #BeginDate format:En2m -->30-Apr-2015 05:53<!-- #EndDate --> 18275970Scy UTC</p> 19275970Scy <hr> 20275970Scy <h4>Synopsis</h4> 21275970Scy 22275970Scy <p> 23275970Scy Address: 127.127.46.<i>u</i><br> 24275970Scy Reference ID: <tt>GPSD</tt><br> 25275970Scy Driver ID: <tt>GPSD_JSON</tt><br> 26275970Scy Serial Port: <tt>/dev/gps<i>u</i></tt> as symlink to the true 27275970Scy device (not used directly; see below)<br> 28275970Scy Features: <tt></tt> 29275970Scy </p> 30275970Scy 31285612Sdelphij <!-- --------------------------------------------------------- --> 32275970Scy 33285612Sdelphij <br><h4>Description</h4> 34275970Scy <p> 35275970Scy This driver is a client driver to the <i>GPSD</i> daemon, which 36275970Scy over the time became increasingly popular for UN*Xish 37275970Scy platforms. <i>GPSD</i> can manage several devices in parallel, 38275970Scy aggregate information, and acts as a data hub for client 39275970Scy applications. <i>GPSD</i> can also auto-detect and handle PPS 40275970Scy hardware signals on serial ports. Have a look 41275970Scy at <a href="http://www.catb.org/gpsd/">the 42275970Scy <i>GPSD</i> project page</a>. 43275970Scy </p> 44275970Scy <p> 45275970Scy <b>It is important to understand that this driver works best 46275970Scy using a GPS device with PPS support.</b> 47275970Scy </p> 48275970Scy <p> 49275970Scy The GPSD-NG protocol is text based, using JSON notation to 50275970Scy transfer records in form of JSON objects. The driver uses a 51275970Scy TCP/IP connection to <tt>localhost:gpsd</tt> to connect to the 52275970Scy daemon and then requests the GPS 53275970Scy device <tt>/dev/gps<i>u</i></tt> to be watched. (Different clock 54275970Scy units use different devices, and 55275970Scy <i>GPSD</i> is able to give only the relevant information to a clock 56275970Scy instance.) 57275970Scy </p> 58275970Scy <p> 59275970Scy This driver does not expect <i>GPSD</i> to be running or the 60275970Scy clock device to be present <i>a priori</i>; it will try to 61275970Scy re-establish a lost or hitherto unsuccessful connection and will 62275970Scy wait for device to come up in <i>GPSD.</i> There is an initial 63275970Scy 10 seconds delay between a connection loss or failed attempt and 64275970Scy the next reconnect attempt; this makes sure that there is no 65275970Scy thrashing on the network layer. If the connection fails again, 66275970Scy an exponential back off is used with an upper limit of 67275970Scy approximately 10 minutes. 68275970Scy </p> 69275970Scy <p> 70275970Scy The overall accuracy depends on the receiver used. The driver 71275970Scy uses the error estimations (95% probability limits) provided by 72285612Sdelphij <i>GPSD</i> to set the clock precision dynamically according to 73285612Sdelphij these readings. 74275970Scy </p> 75275970Scy <p> 76285612Sdelphij The driver needs the VERSION, TPV, PPS, WATCH and TOFF objects 77285612Sdelphij of the <i>GPSD</i> protocol. (Others are quietly ignored.) The 78285612Sdelphij driver can operate without the TOFF objects, which are available 79285612Sdelphij with the <i>protocol</i> version 3.10 and above. (Not to be 80285612Sdelphij confused with the <i>release</i> version of <i>GPSD</i>!) 81285612Sdelphij Running without TOFF objects has a negative impact on the jitter 82285612Sdelphij and offset of the serial timing information; if possible, a 83285612Sdelphij version of <i>GPSD</i> with support for TOFF objects should be 84285612Sdelphij used. 85275970Scy </p> 86285612Sdelphij <p>The acronym <u>STI</u> is used here as a synonym for <i>serial 87285612Sdelphij time information</i> from the data channel of the receiver, no 88285612Sdelphij matter what objects were used to obtain it. 89285612Sdelphij </p> 90275970Scy 91285612Sdelphij <!-- --------------------------------------------------------- --> 92275970Scy 93285612Sdelphij <br><h4>Naming a Device</h4> 94275970Scy <p> 95285612Sdelphij The <i>GPSD</i> driver uses the same device name as the NMEA 96285612Sdelphij driver, namely <tt>/dev/gps<i>u</i></tt>. There is a simple 97285612Sdelphij reason for that: While the NMEA driver and the <i>GPSD</i> 98285612Sdelphij driver can be active at the same time <b>for different 99285612Sdelphij devices</b>, they cannot access the same device at a 100285612Sdelphij time. Having the same name helps on that. It also eases 101285612Sdelphij migration from using NMEA directly to using <i>GPSD</i>, as no 102285612Sdelphij new links etc need to be created. 103275970Scy </p> 104275970Scy <p> 105275970Scy <i>GPSD</i> is normally started with the device name to access; 106275970Scy it can also be instructed by hot-plug scripts to add or remove 107275970Scy devices from its device pool. Luckily, the symlinks used by the 108275970Scy NMEA driver are happily accepted and used by <i>GPSD</i>; this 109275970Scy makes it possible to use the symlink names as device 110275970Scy identification. This makes the migration from the built-in NMEA 111275970Scy driver a bit easier. 112275970Scy </p> 113285612Sdelphij <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot use kernel 114285612Sdelphij mode PPS on devices that are hot-plugged. This would require to 115285612Sdelphij attach the PPS line discipline to the character special file, 116285612Sdelphij which is not possible when running with root privileges already 117285612Sdelphij dropped. This is not likely to change in the future. 118275970Scy </p> 119275970Scy 120285612Sdelphij <!-- --------------------------------------------------------- --> 121285612Sdelphij 122285612Sdelphij <br><h4>The 'mode' word</h4> 123275970Scy <p> 124275970Scy A few operation modes can be selected with the mode word. 125275970Scy </p> 126275970Scy <p> 127275970Scy <table border="1" frame="box" rules="all"> 128275970Scy <th colspan="3">The Mode Word</th> 129275970Scy <tr> <td>Bits</td><td>Value</td><td>Description</td> 130275970Scy </tr> 131285612Sdelphij <tr> <td rowspan="4"align="center">0..1</td> 132285612Sdelphij <td align="center">0</td> 133285612Sdelphij <td>STI only operation. This mode is affected by the timing 134285612Sdelphij stability of whatever protocol is used between the GPS 135285612Sdelphij device and GPSD. 136285612Sdelphij <br> 137285612Sdelphij Running on STI only is not recommended in general. Possible 138285612Sdelphij use cases include: 139285612Sdelphij <ul> 140285612Sdelphij <li>The receiver does not provide a PPS signal. 141285612Sdelphij <li>The receiver <i>does</i> provide a PPS signal and 142285612Sdelphij the secondary PPS unit is used. 143285612Sdelphij <li>The receiver has a stable serial timing and a proper 144285612Sdelphij fudge can be established. 145285612Sdelphij <li>You have other time sources available and want to 146285612Sdelphij establish a useful fudge value for <tt>time2</tt>. 147285612Sdelphij </ul> 148285612Sdelphij </td> 149275970Scy </tr> 150285612Sdelphij <tr> 151285612Sdelphij <td align="center">1</td> 152285612Sdelphij <td>Strict operation. This mode needs a valid PPS and a 153285612Sdelphij valid STI to combine the absolute time from the STI with 154285612Sdelphij the time stamp from the PPS record. Does not feed clock 155285612Sdelphij samples if no valid PPS+STI pair is available. 156285612Sdelphij <br><br> 157285612Sdelphij This type of operation results in an ordinary clock with a 158285612Sdelphij very low jitter as long as the PPS data is available, but 159285612Sdelphij the clock fails once PPS drops out. This mode is a 160285612Sdelphij possible choice for receivers that provide a PPS signal 161285612Sdelphij most of the time but have an unstable serial timing that 162285612Sdelphij cannot be fudge-compensated. 163285612Sdelphij </td> 164275970Scy </tr> 165275970Scy <tr><td align="center">2</td> 166285612Sdelphij <td>Automatic mode. Tries to operate in strict mode unless 167285612Sdelphij it fails to process valid samples for some time, currently 168285612Sdelphij 120s. Then it reverts to STI-only operation until the PPS 169285612Sdelphij is stable again for 40s, when strict mode is engaged 170285612Sdelphij again. 171285612Sdelphij <br><br><b>Important Notice: This is an expiremental 172285612Sdelphij feature!</b><br> Switching between strict and STI-only 173285612Sdelphij mode will cause changes in offset and jitter. Use this 174285612Sdelphij mode only if STI-only works fairly well with your setup, 175285612Sdelphij or if you expect longer dropouts of the PPS signal and 176285612Sdelphij prefer to use STI alone over not getting synchronised at 177285612Sdelphij all.</td> 178275970Scy </tr> 179285612Sdelphij <tr> 180285612Sdelphij <td align="center">3</td> 181285612Sdelphij <td><i>(reserved for future extension, do not use)</i></td> 182275970Scy </tr> 183285612Sdelphij <tr> 184285612Sdelphij <td align="center">2..31</td> 185285612Sdelphij <td colspan="2"><i>(reserved for future extension, do not 186285612Sdelphij use)</i></td> 187285612Sdelphij </tr> 188275970Scy </table> 189275970Scy </p> 190275970Scy 191285612Sdelphij <!-- --------------------------------------------------------- --> 192285612Sdelphij 193285612Sdelphij <br><h4>Syslog flood throttle</h4> 194275970Scy <p>This driver can create a lot of syslog messages when things go 195285612Sdelphij wrong, and cluttering the log files is frowned upon. So we 196285612Sdelphij attempt to log persistent or recurring errors only once per 197285612Sdelphij hour. On the other hand, when tracking a problem the syslog 198285612Sdelphij flood throttle can get into the way.</p> 199275970Scy <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the 200285612Sdelphij flood throttle at any time; the throttle is engaged by 201285612Sdelphij default. Running with the syslog flood throttle disabled for 202285612Sdelphij lengthy time is not recommended unless the log files are closely 203285612Sdelphij monitored.</p> 204275970Scy 205285612Sdelphij <!-- --------------------------------------------------------- --> 206275970Scy 207285612Sdelphij <br><h4>PPS secondary clock unit</h4> 208285612Sdelphij <p>Units with numbers ≥128 act as secondary clock unit for the 209285612Sdelphij primary clock unit (u mod 128). A secondary unit processes only 210285612Sdelphij the PPS data from <i>GPSD</i> and needs the corresponding master 211285612Sdelphij unit to work<a href="#fn1" name="fn1bl"><sup>1</sup></a>. Use 212285612Sdelphij the 'noselect' keyword on the primary unit if you are not 213285612Sdelphij interested in its data. 214285612Sdelphij </p><p>The secondary unit employs the usual precautions before 215285612Sdelphij feeding clock samples:</p> 216285612Sdelphij <ul> 217285612Sdelphij <li>The system must be already in a synchronised state. 218285612Sdelphij <li>The system offset must be less than 400ms absolute. 219285612Sdelphij <li>The phase adjustment from the PPS signal must also be less 220285612Sdelphij than 400ms absolute. 221285612Sdelphij </ul> 222285612Sdelphij <p>If fudge flag <tt>flag1</tt> is set for the secondary unit, the 223285612Sdelphij unit asserts the PPS flag on the clock as long as PPS data is 224285612Sdelphij available. This makes the unit eligible as PPS peer and should 225285612Sdelphij only be used if the GPS receiver can be trusted for the quality 226285612Sdelphij of its PPS signal<a href="fn2" 227285612Sdelphij name="fn2bl"><sup>2</sup></a>. The PPS flag gets cleared if no 228285612Sdelphij PPS records can be aquired for some time. The unit also flushes 229285612Sdelphij the sample buffer at this point to avoid the use of stale PPS 230285612Sdelphij data.</p> 231285612Sdelphij <p><b>Attention:</b> This unit uses its own PPS fudge value 232285612Sdelphij which must be set as fudge <tt>time1</tt>. Only the fudge 233285612Sdelphij values <tt>time1</tt> and <tt>flag1</tt> have an impact on secondary 234285612Sdelphij units.</p> 235285612Sdelphij 236285612Sdelphij <!-- --------------------------------------------------------- --> 237285612Sdelphij 238285612Sdelphij <br><h4>Clockstats</h4> 239285612Sdelphij <p>If flag4 is set when the driver is polled, a clockstats record 240285612Sdelphij is written for the primary clock unit. (The secondary PPS unit 241285612Sdelphij does not provide clock stats on its own.) The first 3 fields are 242285612Sdelphij the normal date, time, and IP address common to all clockstats 243285612Sdelphij records. 244285612Sdelphij </p><p> 245285612Sdelphij <table border="1" frame="box" rules="all"> 246285612Sdelphij <th colspan="2">The Clockstats Line</th> 247285612Sdelphij <tr> <td>field</td><td>Description</td> </tr> 248285612Sdelphij <tr> 249285612Sdelphij <td align="center">1</td> 250285612Sdelphij <td>Date as day number since NTP epoch.</td> 251285612Sdelphij </tr><tr> 252285612Sdelphij <td align="center">2</td> 253285612Sdelphij <td>Time as seconds since midnight.</td> 254285612Sdelphij </tr><tr> 255285612Sdelphij <td align="center">3</td> 256285612Sdelphij <td>(Pseudo-) IP address of clock unit.</td> 257285612Sdelphij </tr><tr> 258285612Sdelphij <td align="center">4</td> 259285612Sdelphij <td>Number of received known JSON records since last 260285612Sdelphij poll. The driver knows about TPV, PPS, TOFF, VERSION and 261285612Sdelphij WATCH records; others are silently ignored. 262285612Sdelphij </td> 263285612Sdelphij </tr><tr> 264285612Sdelphij <td align="center">5</td> 265285612Sdelphij <td>Bad replies since last poll. A record is considered 266285612Sdelphij malformed or a bad reply when it is missing vital fields 267285612Sdelphij or the fields contain malformed data that cannot be 268285612Sdelphij parsed. 269285612Sdelphij </td> 270285612Sdelphij </tr><tr> 271285612Sdelphij <td align="center">6</td> 272285612Sdelphij <td>Number of sample cycles since last poll that were 273285612Sdelphij discarded because there was no GPS fix. This is 274285612Sdelphij effectively the number of TPV records with a fix value 275285612Sdelphij < 2 or without a time stamp. 276285612Sdelphij </td> 277285612Sdelphij </tr><tr> 278285612Sdelphij <td align="center">7</td> 279285612Sdelphij <td>Number of serial time information records (TPV or TOFF, 280285612Sdelphij depending on the GPSD version) received since last poll. 281285612Sdelphij </td> 282285612Sdelphij </tr><tr> 283285612Sdelphij <td align="center">8</td> 284285612Sdelphij <td>Number of serial time information records used for 285285612Sdelphij clock samples since the last poll. 286285612Sdelphij </td> 287285612Sdelphij </tr><tr> 288285612Sdelphij <td align="center">9</td> 289285612Sdelphij <td>Number of PPS records received since the last poll.</td> 290285612Sdelphij </tr><tr> 291285612Sdelphij <td align="center">10</td> 292285612Sdelphij <td>Number of PPS records used for clock samples on the 293285612Sdelphij secondary channel since the last poll. 294285612Sdelphij </td> 295285612Sdelphij </tr> 296285612Sdelphij </table> 297285612Sdelphij </p> 298285612Sdelphij 299285612Sdelphij <!-- --------------------------------------------------------- --> 300285612Sdelphij 301285612Sdelphij <br><h4>Fudge Factors</h4> 302285612Sdelphij 303275970Scy <dl> 304275970Scy <dt><tt>time1 <i>time</i></tt></dt> 305275970Scy <dd>Specifies the PPS time offset calibration factor, in seconds 306275970Scy and fraction, with default 0.0.</dd> 307275970Scy <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> 308285612Sdelphij <dd><em>[Primary Unit]</em> Specifies the TPV/TIME time offset 309285612Sdelphij calibration factor, in seconds and fraction, with default 310285612Sdelphij 0.0.</dd> 311275970Scy <dt><tt>stratum <i>number</i></tt></dt> 312285612Sdelphij <dd>Specifies the driver stratum, in decimal from 0 to 15, with 313285612Sdelphij default 0.</dd> 314275970Scy <dt><tt>refid <i>string</i></tt></dt> 315275970Scy <dd>Specifies the driver reference identifier, an ASCII string 316275970Scy from one to four characters, with default <tt>GPSD</tt>.</dd> 317285612Sdelphij <dt><tt>flag1 0 | 1</tt></dt><dd><em>[<b>Secondary</b> 318285612Sdelphij Unit]</em> When set, flags the secondary clock unit as a 319285612Sdelphij potential PPS peer as long as good PPS data is available. 320285612Sdelphij </dd> 321285612Sdelphij <dt><tt>flag2 0 | 1</tt></dt> 322285612Sdelphij <dd><em>[Primary Unit]</em> When set, <u>disables</u> the 323285612Sdelphij processing of incoming PPS records. Intended as an aide to 324285612Sdelphij test the effects of a PPS dropout when using automatic mode 325285612Sdelphij (mode 2). 326285612Sdelphij </dd> 327285612Sdelphij <dt><tt>flag3 0 | 1</tt></dt><dd><em>[Primary Unit]</em> 328285612Sdelphij If set, <u>disables</u> the log throttle. Useful when tracking 329285612Sdelphij problems in the interaction between <i>GPSD</i> and <i>NTPD</i>, 330285612Sdelphij since now all error events are logged. Persistent/recurrent 331285612Sdelphij errors can easily fill up the log, so this should only be 332285612Sdelphij enabled during bug hunts.</dd> 333285612Sdelphij <dt><tt>flag4 0 | 1</tt></dt><dd><em>[Primary Unit]</em> 334285612Sdelphij If set, write a clock stats line on every poll cycle. 335285612Sdelphij </dd> 336275970Scy </dl> 337275970Scy 338285612Sdelphij <!-- -- footnotes -------------------------------------------- --> 339285612Sdelphij 340285612Sdelphij <hr> 341285612Sdelphij <p><a name="fn1" href="#fn1bl"><sup>1</sup>) </a>Data transmission 342285612Sdelphij an decoding is done only once by the primary unit. The decoded 343285612Sdelphij data is then processed independently in both clock units. This 344285612Sdelphij avoids double transmission over two sockets and decoding the 345285612Sdelphij same data twice, but the primary unit is always needed as a 346285612Sdelphij downside of this approach. 347285612Sdelphij </p> 348285612Sdelphij <p><a name="fn2" href="#fn2bl"><sup>2</sup>) </a>The clock driver 349285612Sdelphij suppresses the processing PPS records when the TPV/TIME data 350285612Sdelphij indicates the receiver has no fix. It can also deal with 351285612Sdelphij situations where the PPS signal is not delivered 352285612Sdelphij to <i>GPSD</i>. But once it is available, it is also processed 353285612Sdelphij and used to create samples. If a receiver cannot be trusted for 354285612Sdelphij the precision of its PPS signal, it should not be used to create 355285612Sdelphij a possible PPS peer: These get extra clout and can effectively 356285612Sdelphij become the sole source of input for the control loop. You do not 357285612Sdelphij want to use sloppy data for that. 358285612Sdelphij <hr> 359275970Scy <p>Additional Information</p> 360275970Scy <p><a href="../refclock.html">Reference Clock Drivers</a></p> 361275970Scy <hr> 362275970Scy <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 363275970Scy </body></html> 364