1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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>
|
