1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3 <meta http-equiv="Content-Type"
4 content="text/html;charset=iso-8859-1"><title>GPSD-NG client driver</title>
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; }
15 <h3>GPSD NG client driver</h3>
17 <!-- #BeginDate format:En2m -->30-Apr-2015 05:53<!-- #EndDate -->
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>
31 <!-- --------------------------------------------------------- -->
33 <br><h4>Description</h4>
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>.
45 <b>It is important to understand that this driver works best
46 using a GPS device with PPS support.</b>
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
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.
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
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
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.
91 <!-- --------------------------------------------------------- -->
93 <br><h4>Naming a Device</h4>
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.
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
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.
120 <!-- --------------------------------------------------------- -->
122 <br><h4>The 'mode' word</h4>
124 A few operation modes can be selected with the mode word.
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>
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
137 Running on STI only is not recommended in general. Possible
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>.
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.
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.
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
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
180 <td align="center">3</td>
181 <td><i>(reserved for future extension, do not use)</i></td>
184 <td align="center">2..31</td>
185 <td colspan="2"><i>(reserved for future extension, do not
191 <!-- --------------------------------------------------------- -->
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
205 <!-- --------------------------------------------------------- -->
207 <br><h4>PPS secondary clock unit</h4>
208 <p>Units with numbers ≥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>
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
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
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
236 <!-- --------------------------------------------------------- -->
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
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>
249 <td align="center">1</td>
250 <td>Date as day number since NTP epoch.</td>
252 <td align="center">2</td>
253 <td>Time as seconds since midnight.</td>
255 <td align="center">3</td>
256 <td>(Pseudo-) IP address of clock unit.</td>
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.
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
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 < 2 or without a time stamp.
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.
283 <td align="center">8</td>
284 <td>Number of serial time information records used for
285 clock samples since the last poll.
288 <td align="center">9</td>
289 <td>Number of PPS records received since the last poll.</td>
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.
299 <!-- --------------------------------------------------------- -->
301 <br><h4>Fudge Factors</h4>
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
311 <dt><tt>stratum <i>number</i></tt></dt>
312 <dd>Specifies the driver stratum, in decimal from 0 to 15, with
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.
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
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.
338 <!-- -- footnotes -------------------------------------------- -->
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.
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.
359 <p>Additional Information</p>
360 <p><a href="../refclock.html">Reference Clock Drivers</a></p>
362 <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>