driver46.html revision 275970
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: 17275970Scy <!-- #BeginDate format:En2m -->1-Mar-2014 03:48<!-- #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 31275970Scy <h4>Description</h4> 32275970Scy 33275970Scy <p> 34275970Scy This driver is a client driver to the <i>GPSD</i> daemon, which 35275970Scy over the time became increasingly popular for UN*Xish 36275970Scy platforms. <i>GPSD</i> can manage several devices in parallel, 37275970Scy aggregate information, and acts as a data hub for client 38275970Scy applications. <i>GPSD</i> can also auto-detect and handle PPS 39275970Scy hardware signals on serial ports. Have a look 40275970Scy at <a href="http://www.catb.org/gpsd/">the 41275970Scy <i>GPSD</i> project page</a>. 42275970Scy </p> 43275970Scy <p> 44275970Scy <b>It is important to understand that this driver works best 45275970Scy using a GPS device with PPS support.</b> 46275970Scy </p> 47275970Scy <p> 48275970Scy The GPSD-NG protocol is text based, using JSON notation to 49275970Scy transfer records in form of JSON objects. The driver uses a 50275970Scy TCP/IP connection to <tt>localhost:gpsd</tt> to connect to the 51275970Scy daemon and then requests the GPS 52275970Scy device <tt>/dev/gps<i>u</i></tt> to be watched. (Different clock 53275970Scy units use different devices, and 54275970Scy <i>GPSD</i> is able to give only the relevant information to a clock 55275970Scy instance.) 56275970Scy </p> 57275970Scy <p> 58275970Scy This driver does not expect <i>GPSD</i> to be running or the 59275970Scy clock device to be present <i>a priori</i>; it will try to 60275970Scy re-establish a lost or hitherto unsuccessful connection and will 61275970Scy wait for device to come up in <i>GPSD.</i> There is an initial 62275970Scy 10 seconds delay between a connection loss or failed attempt and 63275970Scy the next reconnect attempt; this makes sure that there is no 64275970Scy thrashing on the network layer. If the connection fails again, 65275970Scy an exponential back off is used with an upper limit of 66275970Scy approximately 10 minutes. 67275970Scy </p> 68275970Scy <p> 69275970Scy The overall accuracy depends on the receiver used. The driver 70275970Scy uses the error estimations (95% probability limits) provided by 71275970Scy <i>GPSD</i> to set the clock precision dynamically according to these 72275970Scy readings. 73275970Scy </p> 74275970Scy <p> 75275970Scy The driver needs the VERSION, TPV, PPS and WATCH objects of 76275970Scy the <i>GPSD</i> protocol. (Others are quietly ignored.) 77275970Scy </p> 78275970Scy 79275970Scy 80275970Scy <h4>Naming a Device</h4> 81275970Scy <p> 82275970Scy The <i>GPSD</i> driver uses the same name as the NMEA driver, 83275970Scy namely <tt>/dev/gps<i>u</i></tt>. There is a simple reason for 84275970Scy that: While the NMEA driver and the <i>GPSD</i> driver can be 85275970Scy active at the same time <b>for different devices</b>, 86275970Scy they cannot access the same device at a time. Having the same 87275970Scy name helps on that. It also eases migration from using NMEA 88275970Scy directly to using <i>GPSD</i>, as no new links etc need to be 89275970Scy created. 90275970Scy </p> 91275970Scy <p> 92275970Scy <i>GPSD</i> is normally started with the device name to access; 93275970Scy it can also be instructed by hot-plug scripts to add or remove 94275970Scy devices from its device pool. Luckily, the symlinks used by the 95275970Scy NMEA driver are happily accepted and used by <i>GPSD</i>; this 96275970Scy makes it possible to use the symlink names as device 97275970Scy identification. This makes the migration from the built-in NMEA 98275970Scy driver a bit easier. 99275970Scy </p> 100275970Scy <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot 101275970Scy use kernel mode PPS on devices that are hot-plugged. This would 102275970Scy require to attach the PPS line discipline to the file, which is 103275970Scy not possible when running with root privileges dropped. This is 104275970Scy not likely to change in the future. 105275970Scy </p> 106275970Scy 107275970Scy <h4>The 'mode' byte</h4> 108275970Scy <p> 109275970Scy A few operation modes can be selected with the mode word. 110275970Scy </p> 111275970Scy <p> 112275970Scy <table border="1" frame="box" rules="all"> 113275970Scy <th colspan="3">The Mode Word</th> 114275970Scy <tr> <td>Bits</td><td>Value</td><td>Description</td> 115275970Scy </tr> 116275970Scy <tr> <td rowspan="4"align="center">0..1</td><td align="center">0</td> 117275970Scy <td>Uses TPV to get absolute time stamps for full 118275970Scy synchronization. If PPS is available , it is used to improve 119275970Scy the precision, but the clock can work without it.</td> 120275970Scy </tr> 121275970Scy <tr><td align="center">1</td> 122275970Scy <td>Require TPV <b>and</b> PPS to work.</td> 123275970Scy </tr> 124275970Scy <tr><td align="center">2</td> 125275970Scy <td>Ignore PPS data, run on TPV only. This is not a 126275970Scy recommended mode unless the serial timing is very stable 127275970Scy and GPSD provides an information element in TPV that 128275970Scy indicates the receive time of the fix data.</td> 129275970Scy </tr> 130275970Scy <tr><td align="center">3</td> 131275970Scy <td>PPS-only mode. Ignores TPV and does only the PPS phase 132275970Scy correction. This means that some other source must get NTPD 133275970Scy close to synchronisation; only after that happened and the 134275970Scy phase shift between the system clock and the PPS pulse is 135275970Scy less than 125msec the PPS lock will be engaged.</td> 136275970Scy </tr> 137275970Scy <tf colspan="3"><b>IMPORTANT: work in progress, mode 138275970Scy word ignored right now. Fixed mode '0' operation.</b></tf> 139275970Scy </table> 140275970Scy </p> 141275970Scy 142275970Scy <h4>Syslog flood throttle</h4> 143275970Scy <p>This driver can create a lot of syslog messages when things go 144275970Scy wrong, and cluttering the log files is frowned upon. So we attempt 145275970Scy to log persistent or recurring errors only once per hour. On the 146275970Scy other hand, when tracking a problem the syslog flood throttle can 147275970Scy get into the way.</p> 148275970Scy <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the 149275970Scy flood throttle at any time; the throttle is engaged by 150275970Scy default. Running with the syslog flood throttle disabled for 151275970Scy lengthy time is not recommended unless the log files are closely 152275970Scy monitored.</p> 153275970Scy 154275970Scy <h4>Fudge Factors</h4> 155275970Scy 156275970Scy <dl> 157275970Scy <dt><tt>time1 <i>time</i></tt></dt> 158275970Scy <dd>Specifies the PPS time offset calibration factor, in seconds 159275970Scy and fraction, with default 0.0.</dd> 160275970Scy <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> 161275970Scy <dd>Specifies the TPV time offset calibration factor, in seconds 162275970Scy and fraction, with default 0.0.</dd> 163275970Scy <dt><tt>stratum <i>number</i></tt></dt> 164275970Scy <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd> 165275970Scy <dt><tt>refid <i>string</i></tt></dt> 166275970Scy <dd>Specifies the driver reference identifier, an ASCII string 167275970Scy from one to four characters, with default <tt>GPSD</tt>.</dd> 168275970Scy <dt><tt>flag1 0 | 1</tt></dt><dd><i>(not used)</i></dd> 169275970Scy <dt><tt>flag2 0 | 1</tt></dt><dd><i>(not used)</i></dd> 170275970Scy <dt><tt>flag3 0 | 1</tt></dt><dd>If set, <i>disable</i> the 171275970Scy log throttle. Useful when tracking problems in the interaction 172275970Scy between <i>GPSD</i> and <i>NTPD</i>, since now all error 173275970Scy events are logged. Persistent/recurrent errors can easily fill 174275970Scy up the log, so this should only be enabled during bug 175275970Scy hunts.</dd> 176275970Scy <dt><tt>flag4 0 | 1</tt></dt><dd>If set, write a clock stats 177275970Scy line on every poll cycle.</dd> 178275970Scy </dl> 179275970Scy 180275970Scy <p>Additional Information</p> 181275970Scy <p><a href="../refclock.html">Reference Clock Drivers</a></p> 182275970Scy <hr> 183275970Scy <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 184275970Scy </body></html> 185