diff options
Diffstat (limited to 'html/drivers/driver46.html')
| -rw-r--r-- | html/drivers/driver46.html | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/html/drivers/driver46.html b/html/drivers/driver46.html new file mode 100644 index 000000000000..40aded80cca1 --- /dev/null +++ b/html/drivers/driver46.html @@ -0,0 +1,184 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head> + <meta http-equiv="Content-Type" + content="text/html;charset=iso-8859-1"><title>GPSD-NG client driver</title> + + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <style type="text/css"> + table.dlstable { font-size:85%; } + td.ttf{ font-family:Courier; font-weight:bold; } + </style></head> + + + + <body> + <h3>GPSD NG client driver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->1-Mar-2014 03:48<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + + <p> + Address: 127.127.46.<i>u</i><br> + Reference ID: <tt>GPSD</tt><br> + Driver ID: <tt>GPSD_JSON</tt><br> + Serial Port: <tt>/dev/gps<i>u</i></tt> as symlink to the true + device (not used directly; see below)<br> + Features: <tt></tt> + </p> + + <h4>Description</h4> + + <p> + This driver is a client driver to the <i>GPSD</i> daemon, which + over the time became increasingly popular for UN*Xish + platforms. <i>GPSD</i> can manage several devices in parallel, + aggregate information, and acts as a data hub for client + applications. <i>GPSD</i> can also auto-detect and handle PPS + hardware signals on serial ports. Have a look + at <a href="http://www.catb.org/gpsd/">the + <i>GPSD</i> project page</a>. + </p> + <p> + <b>It is important to understand that this driver works best + using a GPS device with PPS support.</b> + </p> + <p> + The GPSD-NG protocol is text based, using JSON notation to + transfer records in form of JSON objects. The driver uses a + TCP/IP connection to <tt>localhost:gpsd</tt> to connect to the + daemon and then requests the GPS + device <tt>/dev/gps<i>u</i></tt> to be watched. (Different clock + units use different devices, and + <i>GPSD</i> is able to give only the relevant information to a clock + instance.) + </p> + <p> + This driver does not expect <i>GPSD</i> to be running or the + clock device to be present <i>a priori</i>; it will try to + re-establish a lost or hitherto unsuccessful connection and will + wait for device to come up in <i>GPSD.</i> There is an initial + 10 seconds delay between a connection loss or failed attempt and + the next reconnect attempt; this makes sure that there is no + thrashing on the network layer. If the connection fails again, + an exponential back off is used with an upper limit of + approximately 10 minutes. + </p> + <p> + The overall accuracy depends on the receiver used. The driver + uses the error estimations (95% probability limits) provided by + <i>GPSD</i> to set the clock precision dynamically according to these + readings. + </p> + <p> + The driver needs the VERSION, TPV, PPS and WATCH objects of + the <i>GPSD</i> protocol. (Others are quietly ignored.) + </p> + + + <h4>Naming a Device</h4> + <p> + The <i>GPSD</i> driver uses the same name as the NMEA driver, + namely <tt>/dev/gps<i>u</i></tt>. There is a simple reason for + that: While the NMEA driver and the <i>GPSD</i> driver can be + active at the same time <b>for different devices</b>, + they cannot access the same device at a time. Having the same + name helps on that. It also eases migration from using NMEA + directly to using <i>GPSD</i>, as no new links etc need to be + created. + </p> + <p> + <i>GPSD</i> is normally started with the device name to access; + it can also be instructed by hot-plug scripts to add or remove + devices from its device pool. Luckily, the symlinks used by the + NMEA driver are happily accepted and used by <i>GPSD</i>; this + makes it possible to use the symlink names as device + identification. This makes the migration from the built-in NMEA + driver a bit easier. + </p> + <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot + use kernel mode PPS on devices that are hot-plugged. This would + require to attach the PPS line discipline to the file, which is + not possible when running with root privileges dropped. This is + not likely to change in the future. + </p> + + <h4>The 'mode' byte</h4> + <p> + A few operation modes can be selected with the mode word. + </p> + <p> + <table border="1" frame="box" rules="all"> + <th colspan="3">The Mode Word</th> + <tr> <td>Bits</td><td>Value</td><td>Description</td> + </tr> + <tr> <td rowspan="4"align="center">0..1</td><td align="center">0</td> + <td>Uses TPV to get absolute time stamps for full + synchronization. If PPS is available , it is used to improve + the precision, but the clock can work without it.</td> + </tr> + <tr><td align="center">1</td> + <td>Require TPV <b>and</b> PPS to work.</td> + </tr> + <tr><td align="center">2</td> + <td>Ignore PPS data, run on TPV only. This is not a + recommended mode unless the serial timing is very stable + and GPSD provides an information element in TPV that + indicates the receive time of the fix data.</td> + </tr> + <tr><td align="center">3</td> + <td>PPS-only mode. Ignores TPV and does only the PPS phase + correction. This means that some other source must get NTPD + close to synchronisation; only after that happened and the + phase shift between the system clock and the PPS pulse is + less than 125msec the PPS lock will be engaged.</td> + </tr> + <tf colspan="3"><b>IMPORTANT: work in progress, mode + word ignored right now. Fixed mode '0' operation.</b></tf> + </table> + </p> + + <h4>Syslog flood throttle</h4> + <p>This driver can create a lot of syslog messages when things go + wrong, and cluttering the log files is frowned upon. So we attempt + to log persistent or recurring errors only once per hour. On the + other hand, when tracking a problem the syslog flood throttle can + get into the way.</p> + <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the + flood throttle at any time; the throttle is engaged by + default. Running with the syslog flood throttle disabled for + lengthy time is not recommended unless the log files are closely + monitored.</p> + + <h4>Fudge Factors</h4> + + <dl> + <dt><tt>time1 <i>time</i></tt></dt> + <dd>Specifies the PPS time offset calibration factor, in seconds + and fraction, with default 0.0.</dd> + <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> + <dd>Specifies the TPV time offset calibration factor, in seconds + and fraction, with default 0.0.</dd> + <dt><tt>stratum <i>number</i></tt></dt> + <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd> + <dt><tt>refid <i>string</i></tt></dt> + <dd>Specifies the driver reference identifier, an ASCII string + from one to four characters, with default <tt>GPSD</tt>.</dd> + <dt><tt>flag1 0 | 1</tt></dt><dd><i>(not used)</i></dd> + <dt><tt>flag2 0 | 1</tt></dt><dd><i>(not used)</i></dd> + <dt><tt>flag3 0 | 1</tt></dt><dd>If set, <i>disable</i> the + log throttle. Useful when tracking problems in the interaction + between <i>GPSD</i> and <i>NTPD</i>, since now all error + events are logged. Persistent/recurrent errors can easily fill + up the log, so this should only be enabled during bug + hunts.</dd> + <dt><tt>flag4 0 | 1</tt></dt><dd>If set, write a clock stats + line on every poll cycle.</dd> + </dl> + + <p>Additional Information</p> + <p><a href="../refclock.html">Reference Clock Drivers</a></p> + <hr> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body></html> |