driver46.html revision 275970
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 -->1-Mar-2014 03:48<!-- #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 <h4>Description</h4> 32 33 <p> 34 This driver is a client driver to the <i>GPSD</i> daemon, which 35 over the time became increasingly popular for UN*Xish 36 platforms. <i>GPSD</i> can manage several devices in parallel, 37 aggregate information, and acts as a data hub for client 38 applications. <i>GPSD</i> can also auto-detect and handle PPS 39 hardware signals on serial ports. Have a look 40 at <a href="http://www.catb.org/gpsd/">the 41 <i>GPSD</i> project page</a>. 42 </p> 43 <p> 44 <b>It is important to understand that this driver works best 45 using a GPS device with PPS support.</b> 46 </p> 47 <p> 48 The GPSD-NG protocol is text based, using JSON notation to 49 transfer records in form of JSON objects. The driver uses a 50 TCP/IP connection to <tt>localhost:gpsd</tt> to connect to the 51 daemon and then requests the GPS 52 device <tt>/dev/gps<i>u</i></tt> to be watched. (Different clock 53 units use different devices, and 54 <i>GPSD</i> is able to give only the relevant information to a clock 55 instance.) 56 </p> 57 <p> 58 This driver does not expect <i>GPSD</i> to be running or the 59 clock device to be present <i>a priori</i>; it will try to 60 re-establish a lost or hitherto unsuccessful connection and will 61 wait for device to come up in <i>GPSD.</i> There is an initial 62 10 seconds delay between a connection loss or failed attempt and 63 the next reconnect attempt; this makes sure that there is no 64 thrashing on the network layer. If the connection fails again, 65 an exponential back off is used with an upper limit of 66 approximately 10 minutes. 67 </p> 68 <p> 69 The overall accuracy depends on the receiver used. The driver 70 uses the error estimations (95% probability limits) provided by 71 <i>GPSD</i> to set the clock precision dynamically according to these 72 readings. 73 </p> 74 <p> 75 The driver needs the VERSION, TPV, PPS and WATCH objects of 76 the <i>GPSD</i> protocol. (Others are quietly ignored.) 77 </p> 78 79 80 <h4>Naming a Device</h4> 81 <p> 82 The <i>GPSD</i> driver uses the same name as the NMEA driver, 83 namely <tt>/dev/gps<i>u</i></tt>. There is a simple reason for 84 that: While the NMEA driver and the <i>GPSD</i> driver can be 85 active at the same time <b>for different devices</b>, 86 they cannot access the same device at a time. Having the same 87 name helps on that. It also eases migration from using NMEA 88 directly to using <i>GPSD</i>, as no new links etc need to be 89 created. 90 </p> 91 <p> 92 <i>GPSD</i> is normally started with the device name to access; 93 it can also be instructed by hot-plug scripts to add or remove 94 devices from its device pool. Luckily, the symlinks used by the 95 NMEA driver are happily accepted and used by <i>GPSD</i>; this 96 makes it possible to use the symlink names as device 97 identification. This makes the migration from the built-in NMEA 98 driver a bit easier. 99 </p> 100 <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot 101 use kernel mode PPS on devices that are hot-plugged. This would 102 require to attach the PPS line discipline to the file, which is 103 not possible when running with root privileges dropped. This is 104 not likely to change in the future. 105 </p> 106 107 <h4>The 'mode' byte</h4> 108 <p> 109 A few operation modes can be selected with the mode word. 110 </p> 111 <p> 112 <table border="1" frame="box" rules="all"> 113 <th colspan="3">The Mode Word</th> 114 <tr> <td>Bits</td><td>Value</td><td>Description</td> 115 </tr> 116 <tr> <td rowspan="4"align="center">0..1</td><td align="center">0</td> 117 <td>Uses TPV to get absolute time stamps for full 118 synchronization. If PPS is available , it is used to improve 119 the precision, but the clock can work without it.</td> 120 </tr> 121 <tr><td align="center">1</td> 122 <td>Require TPV <b>and</b> PPS to work.</td> 123 </tr> 124 <tr><td align="center">2</td> 125 <td>Ignore PPS data, run on TPV only. This is not a 126 recommended mode unless the serial timing is very stable 127 and GPSD provides an information element in TPV that 128 indicates the receive time of the fix data.</td> 129 </tr> 130 <tr><td align="center">3</td> 131 <td>PPS-only mode. Ignores TPV and does only the PPS phase 132 correction. This means that some other source must get NTPD 133 close to synchronisation; only after that happened and the 134 phase shift between the system clock and the PPS pulse is 135 less than 125msec the PPS lock will be engaged.</td> 136 </tr> 137 <tf colspan="3"><b>IMPORTANT: work in progress, mode 138 word ignored right now. Fixed mode '0' operation.</b></tf> 139 </table> 140 </p> 141 142 <h4>Syslog flood throttle</h4> 143 <p>This driver can create a lot of syslog messages when things go 144 wrong, and cluttering the log files is frowned upon. So we attempt 145 to log persistent or recurring errors only once per hour. On the 146 other hand, when tracking a problem the syslog flood throttle can 147 get into the way.</p> 148 <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the 149 flood throttle at any time; the throttle is engaged by 150 default. Running with the syslog flood throttle disabled for 151 lengthy time is not recommended unless the log files are closely 152 monitored.</p> 153 154 <h4>Fudge Factors</h4> 155 156 <dl> 157 <dt><tt>time1 <i>time</i></tt></dt> 158 <dd>Specifies the PPS time offset calibration factor, in seconds 159 and fraction, with default 0.0.</dd> 160 <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> 161 <dd>Specifies the TPV time offset calibration factor, in seconds 162 and fraction, with default 0.0.</dd> 163 <dt><tt>stratum <i>number</i></tt></dt> 164 <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd> 165 <dt><tt>refid <i>string</i></tt></dt> 166 <dd>Specifies the driver reference identifier, an ASCII string 167 from one to four characters, with default <tt>GPSD</tt>.</dd> 168 <dt><tt>flag1 0 | 1</tt></dt><dd><i>(not used)</i></dd> 169 <dt><tt>flag2 0 | 1</tt></dt><dd><i>(not used)</i></dd> 170 <dt><tt>flag3 0 | 1</tt></dt><dd>If set, <i>disable</i> the 171 log throttle. Useful when tracking problems in the interaction 172 between <i>GPSD</i> and <i>NTPD</i>, since now all error 173 events are logged. Persistent/recurrent errors can easily fill 174 up the log, so this should only be enabled during bug 175 hunts.</dd> 176 <dt><tt>flag4 0 | 1</tt></dt><dd>If set, write a clock stats 177 line on every poll cycle.</dd> 178 </dl> 179 180 <p>Additional Information</p> 181 <p><a href="../refclock.html">Reference Clock Drivers</a></p> 182 <hr> 183 <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 184 </body></html> 185