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