summaryrefslogtreecommitdiff
path: root/gpsd.xml
blob: 4f396a724c13b5e7d7cafef6ebef7bb20db7ed16 (plain)
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd" [
<!ENTITY gpsdsock	 "/var/run/gpsd.sock">
]>
<refentry id='gpsd.8'>
<refmeta>
<refentrytitle>gpsd</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class='date'>9 Aug 2004</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpsd</refname>
<refpurpose>interface daemon for GPS receivers</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpsd</command>
      <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg>
      <!-- arg choice='opt'>-R
      <replaceable>rtcm-listener-port</replaceable></arg -->
      <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>
      <arg choice='opt'>-b </arg>
      <arg choice='opt'>-l </arg>
      <arg choice='opt'>-G </arg>
      <arg choice='opt'>-n </arg>
      <arg choice='opt'>-N </arg>
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
      <arg choice='opt'>-V </arg>
      <arg rep='repeat'>
	   <group><replaceable>source-name</replaceable></group>
      </arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para><application>gpsd</application> is a monitor daemon that watches
a TCP/IP port (2947 by default), waiting for applications to request
information from GPSes or differential-GPS radios attached to the host
machine.  Each GPS or radio is expected to be direct-connected to the
host via a USB or RS232C serial port.  The port may be specified to
<application>gpsd</application> at startup, or it may be set via a
command shipped down a local control socket (e.g. by a USB hotplug
script). Given a GPS device by either means,
<application>gpsd</application> discovers the correct port speed and
protocol for it.</para>

<para><application>gpsd</application> should be able to query any GPS
that speaks either the standard textual NMEA 0183 protocol, or the
(differing) extended NMEA dialects used by MKT-3301, iTrax, Motorola
OnCore, Sony CXD2951, and Ashtech/Thales devices.  It can also
interpret the binary protocols used by EverMore, Garmin, Navcom,
Rockwell/Zodiac, SiRF, Trimble, and uBlox ANTARIS devices. It can read
heading and attitude information from the Oceanserver 5000 digital
compass.</para>

<para>The GPS protocols supported by your instance of
<application>gpsd</application> may differ depending on how it was
compiled; general-purpose versions support many, but it can be built
with protocol subsets down to a singleton for use in constrained
environments. For a list of the GPS protocols supported by your
instance, see the output of <command>gpsd -l</command></para>

<para><application>gpsd</application> effectively hides the
differences among the GPS types it supports. It also knows about and
uses commands that tune these GPSes for lower latency. </para>

<para><application>gpsd</application> can use differential-GPS
corrections from a DGPS radio or over the net, from a ground station
running a DGPSIP server or a Ntrip broadcaster that reports RTCM-104
data; this will shrink position errors by roughly a factor of four.
When <application>gpsd</application> opens a serial device emitting
RTCM-104, it automatically recognizes this and uses the device as a
correction source for all connected GPSes that accept RTCM corrections
(this is dependent on the type of the GPS; not all GPSes have the
firmware capability to accept RTCM correction packets). See 
<xref linkend='accuracy'/> and <xref linkend='files'/> for discussion.</para>

<para>The program accepts the following options:</para>
<variablelist remap='TP'>
<varlistentry>
<term>-F</term>
<listitem>
<para>Create a control socket for device addition and removal
commands.  You must specify a valid pathname on your local filesystem;
this will be created as a Unix-domain socket to which you can write
commands that edit the daemon's internal device list.</para>
</listitem>
</varlistentry>
<!-- varlistentry>
<term>-R</term>
<listitem><para>Set TCP/IP port on which to listen for DGPSIP clients
(default is 2101). The option -R 0 will disable serving DGPSIP
clients.</para></listitem>
</varlistentry -->
<varlistentry>
<term>-S</term>
<listitem><para>Set TCP/IP port on which to listen for GPSD clients
(default is 2947).</para></listitem>
</varlistentry>
<varlistentry>
<term>-b</term>
<listitem><para>Broken-device-safety, otherwise known as read-only
mode. Some popular bluetooth and USB receivers lock up or become
totally inaccessible when probed or reconfigured. This switch prevents
gpsd from writing to a receiver.  This means that
<application>gpsd</application> cannot configure the receiver for
optimal performance, but it also means that
<application>gpsd</application> cannot break the receiver. A better
solution would be for Bluetooth to not be so fragile. A platform
independent method to identify serial-over-Bluetooth devices would
also be nice.</para></listitem>
</varlistentry>
<varlistentry>
<term>-G</term>
<listitem><para>This flag causes <application>gpsd</application> to
listen on all addresses (INADDR_ANY) rather than just the loopback
(INADDR_LOOPBACK) address. For the sake of privacy and security, PVT
information is now private to the local machine until the user makes
an effort to expose this to the world. Listening on the loopback by
default is a change from previous behaviour.</para></listitem>
</varlistentry>
<varlistentry>
<term>-l</term>
<listitem><para>List all drivers compiled into this
<application>gpsd</application> instance. The letters to the left of
each driver name are the <application>gpsd</application> 
control commands supported by that driver.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n</term>
<listitem><para>Don't wait for a client to connect before polling
whatever GPS is associated with it. It is thought that some GPSes
go to a standby mode (drawing less power) before the host machine
asserts DTR, so waiting for the first actual request might save
battery power on portable equipment.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-N</term>
<listitem><para>Don't daemonize; run in foreground.  Also suppresses
privilege-dropping.  This switch is mainly useful for debugging.
Its meaning may change in future versions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem><para>Display help message and terminate.</para></listitem>
</varlistentry>
<varlistentry>
<term>-P</term>
<listitem>
<para>Specify the name and path to record the daemon's process ID.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D</term>
<listitem>
<para>Set debug level. At debug levels 2 and above,
<application>gpsd</application> reports incoming sentence and actions
to standard error if <application>gpsd</application> is in the foreground
(-N) or to syslog if in the background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-V</term>
<listitem>
<para>Dump version and exit.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Arguments are interpreted as the names of data sources.
Normally, a data source is the name of a local serial device from
which the daemon may expect GPS data.</para>

<para>A data source name may also be a URI pointing to a specific
network GNSS service (GPSD server, DGPSIP server or Ntrip broadcaster).
If the URI starts with "ntrip://" Ntrip will be used; if the URI starts
with "dgpsip://", DGPSIP will be used; if the URI starts with "gpsd://",
gps protocols will be used. <application>Gpsd</application> defaults to
DGPSIP if no protocol is defined. GPSD URIs take an optional argument to
select the wire protocol: raw, nmea or gpsd - these correspond to "R=2",
"R=1" and "W=1" modes. For Ntrip services that require authentication, a
prefix of the form "username:password@" can be added before the name of
the Ntrip broadcaster.  If a suffix of the service name begins with ":"
it is interpreted as a port number, overriding the default IANA-assigned
port of 2101.  For Ntrip service you must specify which stream to use;
the stream is given in the form "/streamname". !n example DGPSIP URI could
be "dgpsip://dgpsip.example.com" and a Ntrip URI could be
"ntrip://foo:bar@ntrip.example.com:80/example-stream". A gpsd URI could be
"gpsd://gpsd.example.com:12000/dev/gps1?raw". <!-- If this
option is not given, <application>gpsd</application> will hunt for a
DGPSIP server. --></para>

<para>Internally, the daemon maintains a device list holding the
pathnames of GPSes known to the daemon. Initially, this list is the
list of device-name arguments specified on the command line.  That
list may be empty, in which case the daemon will have no devices on
its search list until they are added by a control-socket command (see
<xref linkend='devices'/> for details on this).  Daemon startup will
abort with an error if neither any devices nor a control socket are
specified.</para>

<para>Clients communicate with the dameon via textual request and
responses.  Currently there are two supported protocols, but there
may be only one in the future. It is a bad idea for applications to
speak either protocol directly: rather, they should use the
<application>libgps</application> client library and take appropriate
care to conditionalize their code on the major and minor API version
symbols.</para>

</refsect1>
<refsect1 id='old_protocol'><title>OLD PROTOCOL</title>

<warning><para><emphasis>Do not rely on being able to use this
protocol directly!</emphasis> This protocol has run out of command
namespace and is not flexible enough to handle report types other than
for GPS devices.  Thus, it is in the process of being replaced by a
new, JSON-based protocol documented in a later section; development on
the old protocol has ceased and support for it may be removed at any
time after the new one is deemed mature.</para></warning>

<para>Under the old protocol, each client will at any given time be
listening to only one of the GPSes on the internal device list (this
restriction is removed under the new JSON-based protocol).  By default, a
client's device is the one that most recently shipped information to
the daemon at the time the client first requests GPS
information.</para>

<para>Each request normally consists of a single ASCII
character followed by a newline.  Case of the request character is
ignored.  Each request returns a line of response text ended by a
CR/LF.  Requests and responses are as follows, with %f standing for a
decimal float numeral and %d for decimal integer numeral:</para>

<para>Any command other than L, F, K, W=0 or R=0 is considered a
request for GPS information and will cause a GPS device to be
connected to the client's channel.</para>

<variablelist>
<varlistentry>
<term>a</term>
<listitem><para>The current altitude as "A=%f", meters above mean sea level.</para></listitem>
</varlistentry>

<varlistentry>
<term>b</term>
<listitem><para>The B command with no argument returns four fields
giving the parameters of the serial link to the GPS as "B=%d %d %c
%d"; baud rate, byte size, parity (N, O or E for no parity, odd, or
even) and stop bits (1 or 2).</para>

<para>The command "B=%d" sets the baud rate, not changing parity or
stop bits; The command "B=%d [78] [NOE] [12]" (B followed by
whitespace; followed by a numeric speed; followed by one of the digits
7 or 8; followed by whitespace; followed by one of the letters 'N',
'O', or 'E'; followed by whitespace; followed by one of the digits '1'
or 2') sets not only speed but word length, parity, and stop bits.</para>

<para>For both forms, watch the response, because it is
possible for this to fail if the GPS does not support a
speed-switching command or only supports some combinations of
serial modes.  In case of failure, the daemon and GPS will
continue to communicate at the old speed.  Both forms are rejected
if more than one client is attached to the channel.</para>

<para>Use this command with caution.  On USB and Bluetooth GPSes it is
also possible for serial mode setting to fail either because the
serial adaptor chip does not support non-8N1 modes or because the
device firmware does not properly synchronize the serrial adaptor chip
with the UART on the GPS chipset whjen the speed changes. These
failures can hang your device, possibly requiring a GPS power cycle or (in
extreme cases) physically disconnecting the NVRAM backup battery.</para>

<para>(Older versions of <application>gpsd</application> supported
changing speed only.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>c</term>
<listitem>
<para>C with no following = asks the daemon to return the cycle time
of the attached GPS, if any.  If there is no attached device it will
return "C=?".</para>

<para>If the driver has the capability to change sampling rate the
command "C=%f" does so, setting a new cycle time in seconds. The "C="
form is rejected if more than one client is attached to the
channel.</para>

<para>If the driver has the capability to change sampling rate, this
command always returns "C=%f %f" giving the current cycle time in
seconds and the minimum possible cycle time.  If the driver does not
have the capability to change sampling rate, this returns, as "C=%f",
the cycle time in seconds only.</para>

<para>Either number may be fractional, indicating a GPS cycle shorter
than a second; however, if >1 the cycle time must be a whole number. Also
note that relatively few GPSes have the ability to set sub-second
cycle times; consult your hardware protocol description to make sure
this works.</para>

<para>This command will return "C=?" at start of session, before the
first full packet has been received from the GPS, because the GPS type is
not yet known. To set up conditions for a real answer, issue it after
some command that reads position/velocity/time information from the
device.</para>

<!--
<para>The second field of the C return may be 0, indicating no hard
lower limit on the cycle time. On an NMEA device of this kind it is
possible to try to push more characters through per cycle than the
time to transmit will allow. You must set the time high enough to let
all sentences come through.  Here are the maxima to use for
computation:</para>

<table frame='all'>
<tgroup cols='2'>
<tbody>
<row><entry>ZDA       </entry><entry>36</entry></row>
<row><entry>GLL       </entry><entry>47</entry></row>
<row><entry>GGA       </entry><entry>82</entry></row>
<row><entry>VTG       </entry><entry>46</entry></row>
<row><entry>RMC       </entry><entry>77</entry></row>
<row><entry>GSA       </entry><entry>67</entry></row>
<row><entry>GSV       </entry><entry>60 (per line, thus 180 for a set of 3)</entry> </row>
</tbody>
</tgroup>
</table>

<para>The transmit time for a cycle (which must be less than 1 second)
is the total character count multiplied by 10 and divided by the baud
rate. A typical budget is GGA, RMC, GSA, 3*GSV = 82+75+67+(3*60) =
404.</para>
-->
</listitem>

</varlistentry>

<varlistentry>
<term>d</term>
<listitem><para>Returns the UTC time in the ISO 8601 format,
"D=yyyy-mm-ddThh:nmm:ss.ssZ". Digits of precision in the fractional-seconds
part will vary and may be absent.</para></listitem>
</varlistentry>

<varlistentry>
<term>e</term>
<listitem>
<para>Returns "E=? %f %f": estimated position errors in meters
&mdash; horizontal, and vertical (95% confidence
level).  Note: many GPSes do not supply these numbers.  When the
GPS does not supply them, <application>gpsd</application> computes
them from satellite DOP using fixed figures for expected non-DGPS
and DGPS range errors in meters.  A value of '?' for either of these
numbers should be taken to mean that component of DOP is not
available. The ? value is a backwards-compatibility placeholder; some
early versions of GPSD returned a total error estimate there.
See also the 'q' command.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>f</term>
<listitem><para>Gets or sets the active GPS device name. The bare
command 'f' requests a response containing 'F=' followed by the name
of the active GPS device.  The other form of the command is 'f=', in
which case all following printable characters up to but not including
the next CR/LF are interpreted as the name of a trial GPS device. If
the trial device is in <application>gpsd</application>'s device list,
it is opened and read to see if a GPS can be found there.  If it can,
the trial device becomes the active device for this client.</para>

<para>The 'f=' command may fail if the specified device name is not on
the daemon's device list.  This device list is initialized with the
paths given on the command line, if any were specified.  For security
reasons, ordinary clients cannot change this device list; instead,
this must be done via the daemon's local control socket declared with
the -F option.</para>

<para>Once an 'f=' command succeeds, the client is tied to the
specified device until the client disconnects.</para>

<para>Whether the command is 'f' or 'f=' or not, and whether it succeeds
or not, the response always lists the name of the client's device.</para>

<para>(At protocol level 1, the F command failed if more than one
client was attached, and multiple devices were not supported.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>g</term>
<listitem>
<para>With =, accepts a single argument which may have any of the
values 'gps', 'ais', 'rtcm104v2', or 'rtcm104v3' , with case ignored.
This specifies the type of information the client wants and forces a
device assignment.  Without =, forces a device assignment but doesn't
force the type. This command is optional; if it is not given, the R, W
and B commands will bind the client to whatever available device the 
daemon finds first. All other commands require a GPS and will attempt
to bind the client to one.</para>

<para>This command returns either '?' if no device of the specified
type(s) could be assigned, otherwise a string ('GPS', 'AIS' or
'RTCM104v2') identifying the kind of information the attached device
returns.</para>

<para>(Earlier versions accepted 'RTCM104' and returned 'RTCM104'
rather than 'RTCM104v2')</para>
</listitem>
</varlistentry>

<!--
<varlistentry>
<term>h</term>
<listitem>
<para>Heading, "H=%f" in degrees from true north.  Only available from
True North Technologies or comparable digital compass devices (c.f. 't')</para>
</listitem>
</varlistentry>
-->

<varlistentry>
<term>i</term>
<listitem><para>Returns a text string identifying the GPS.  The string
may contain spaces and is terminated by CR-LF.  This command will
return '?' at start of session, before the first full packet has been
received from the GPS, because its type is not yet known.</para></listitem>
</varlistentry>

<varlistentry>
<term>j</term>
<listitem>
<para>Get or set buffering policy; this only matters for NMEA devices
which report fix data in several separate sentences during the poll
cycle (and in particular it <emphasis>doesn't</emphasis> matter for
SiRF chips).  The default (j=0) is to clear all fix data at the start
of each poll cycle, so until the sentence that reports a given piece
of data arrives queries will report ?.  Setting j=1 will disable this,
retaining data from the previous cycle.  This is a per-user-channel
bit, not a per-device one.  The j=0 setting is hyper-correct and never
displays stale data, but may produce a jittery display; the j=1 setting
allows stale data but smooths the display.</para>

<para>(At protocol level below 3, there was no J command.  Note, this
command is experimental and its semantics are subject to change.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>k</term>
<listitem><para>Returns a line consisting of "K=" followed by an
integer count of of all GPS devices known to
<application>gpsd</application>, followed by a space, followed by a
space-separated list of the device names. This command lists devices
the daemon has been pointed at by the command-line argument(s) or an
add command via its control socket, and has successfully recognized as
GPSes.  Because GPSes might be unplugged at any time, the presence of
a name in this list does not guarantee that the device is available.</para>

<para>(At protocol level 1, there was no K command.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>l</term>
<listitem><para>Returns four fields: the major protocol/API revision number,
the minor revision number, the gpsd version, and a list of accepted
request letters. Note: earlier versions of this command returned only
three fields, omitting the minor revision number.</para></listitem>
</varlistentry>

<varlistentry>
<term>m</term>
<listitem><para>The NMEA mode as "M=%d". 0=no mode value yet seen,
1=no fix, 2=2D (no altitude), 3=3D (with altitude).</para></listitem>
</varlistentry>

<varlistentry>
<term>n</term>
<listitem><para>Get or set the GPS driver mode.  Without argument,
reports the mode as "N=%d"; N=0 means NMEA mode and N=1 means
alternate mode (binary if it has one, for SiRF and Evermore chipsets
in particular).  With argument, set the mode if possible; the new mode
will be reported in the response. The "N=" form is rejected if more
than one client is attached to the channel.</para></listitem>
</varlistentry>

<varlistentry>
<term>o</term>
<listitem>
<para>Attempts to return a complete time/position/velocity report as a
unit.  Any field for which data is not available being reported as ?.
If there is no fix, the response is simply "O=?", otherwise a tag and
timestamp are always reported.  Fields are as follows, in order:</para>

<variablelist>
<varlistentry>
<term>tag</term> <listitem><para>A tag identifying the last sentence
received.  For NMEA devices this is just the NMEA sentence name; the
talker-ID portion may be useful for distinguishing among results
produced by different NMEA talkers in the same wire.</para></listitem>
</varlistentry>

<varlistentry>
<term>timestamp</term>
<listitem><para>Seconds since the Unix epoch, UTC. May have a
fractional part of up to .01sec precision.</para></listitem>
</varlistentry>

<varlistentry>
<term>time error</term>
<listitem><para>Estimated timestamp error (%f, seconds,
95% confidence).</para></listitem>
</varlistentry>

<varlistentry>
<term>latitude</term>
<listitem><para>Latitude as in the P report (%f, degrees).</para></listitem>
</varlistentry>

<varlistentry>
<term>longitude</term>
<listitem><para>Longitude as in the P report (%f, degrees).</para></listitem>
</varlistentry>

<varlistentry>
<term>altitude</term>
<listitem><para>Altitude as in the A report (%f, meters).  If the mode
field is not 3 this is an estimate and should be treated as
unreliable.</para></listitem>
</varlistentry>

<varlistentry>
<term>horizontal error estimate</term>
<listitem><para>Horizontal error estimate as in the E report
(%f, meters).</para></listitem>
</varlistentry>

<varlistentry>
<term>vertical error estimate</term>
<listitem><para>Vertical error estimate as in the E report
(%f, meters).</para></listitem>
</varlistentry>

<varlistentry>
<term>course over ground</term>
<listitem><para>Track as in the T report (%f, degrees).</para></listitem>
</varlistentry>

<varlistentry>
<term>speed over ground</term>
<listitem><para>Speed (%f, meters/sec). Note: older versions
of the O command reported this field in knots.</para></listitem>
</varlistentry>

<varlistentry>
<term>climb/sink</term>
<listitem><para>Vertical velocity as in the U report
(%f, meters/sec).</para></listitem>
</varlistentry>

<varlistentry>
<term>estimated error in course over ground</term>
<listitem><para>Error estimate for course (%f, degrees, 95% confidence).</para></listitem>
</varlistentry>

<varlistentry>
<term>estimated error in speed over ground</term>
<listitem><para>Error estimate for speed (%f, meters/sec, 95%
confidence). Note: older experimental versions of the O command
reported this field in knots.</para></listitem>
</varlistentry>

<varlistentry>
<term>estimated error in climb/sink</term>
<listitem><para>Estimated error for climb/sink
(%f, meters/sec, 95% confidence).</para></listitem>
</varlistentry>

<varlistentry>
<term>mode</term>
<listitem><para>The NMEA mode (%d, ?=no mode value yet seen,
1=no fix, 2=2D, 3=3D). (This field was not reported at protocol
levels 2 and lower.)</para></listitem>
</varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term>p</term>
<listitem><para>Returns the current position in the form "P=%f %f";
numbers are in degrees, latitude first.</para></listitem>
</varlistentry>

<varlistentry>
<term>q</term>
<listitem>
<para>Returns "Q=%d %f %f %f %f %f": a count of satellites used in the
last fix, and five dimensionless dilution-of-precision (DOP) numbers
&mdash; spherical, horizontal, vertical, time, and total geometric.
These are computed from the satellite geometry; they are factors by
which to multiply the estimated UERE (user error in meters at
specified confidence level due to ionospheric delay, multipath
reception, etc.) to get actual circular error ranges in meters (or
seconds) at the same confidence level. See also the 'e' command.
Note: Some GPSes may fail to report these, or report only one of them
(often HDOP); a value of 0.0 should be taken as an indication that the
data is not available.</para>

<para>Note: Older versions of <application>gpsd</application> reported
only the first three DOP numbers, omitting time DOP and total DOP.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>r</term>
<listitem><para>Sets or toggles 'raw' mode. Return "R=0" or "R=1" or
"R=2". In raw mode you read the NMEA data stream from each
GPS. (Non-NMEA GPSes get their communication format translated to NMEA
on the fly.)  If the device is a source of RTCM-104 corrections, the
corrections are dumped in the textual format described in
<citerefentry><refentrytitle>rtcm104</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
the device is a source of AIS data, AIS packets are dumped in CSV
form with each field (other than padding fields) dumped as an unscaled
integer or string, whichever is appropriate.</para>

<para>The command 'r' immediately followed by the digit '1' or the
plus sign '+' sets raw mode.  The command 'r' immediately followed by
the digit '2' sets super-raw mode; for non-NMEA (binary) GPSes or
RTCM-104 sources this dumps the raw binary packet.  The command 'r'
followed by the digit '0' or the minus sign '-' clears raw mode.  The
command 'r' with neither suffix toggles raw mode.</para>

<para>Note: older versions of <application>gpsd</application> did not
support super-raw mode.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>s</term>
<listitem><para>The NMEA status as "S=%d". 0=no fix, 1=fix,
2=DGPS-corrected fix.</para></listitem>
</varlistentry>

<varlistentry>
<term>t</term>
<listitem>
<para>Track made good; course "T=%f" in degrees from true north.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>u</term>
<listitem><para>Current rate of climb as "U=%f" in meters per second.
Some GPSes (not SiRF-based) do not report this, in that case
<application>gpsd</application> computes it using the altitude from
the last fix (if available).</para></listitem>
</varlistentry>

<varlistentry>
<term>v</term>
<listitem><para>The current speed over ground as "V=%f" in knots.</para></listitem>
</varlistentry>

<varlistentry>
<term>w</term>
<listitem><para>Sets or toggles 'watcher' mode (see the description
below). Return "W=0" or "W=1".The command 'w' immediately followed by
the digit '1' or the plus sign '+' sets watcher mode.  The command 'w'
followed by the digit '0' or the minus sign '-' clears watcher mode.
The command 'w' with neither suffix toggles watcher
mode.</para></listitem>
</varlistentry>

<varlistentry>
<term>x</term>
<listitem><para>Returns "X=0" if the GPS is offline, "X=%f" if
online; in the latter case, %f is a timestamp from when the device
was activated or the last sentence was received.</para>

<para>(At protocol level 1, the nonzero response was always 1.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>y</term>
<listitem>
<para>Returns Y=, followed by a sentence tag, followed by a timestamp
(seconds since the Unix epoch, UTC) and a count, followed by that many
quintuples of satellite PRNs, elevation/azimuth pairs (elevation an integer
formatted as %d in range 0-90, azimuth an integer formatted as %d in range
0-359), signal strengths in decibels, and 1 or 0 according as the satellite
was or was not used in the last fix. Each number is followed by one space.
The count field was formerly limited 12 - this is no longer the case, since
receivers with more than 12 channels are common and there are enough
satellites in orbit to have more than 12 usable.</para>

<para>(At protocol level 1, this response had no tag or timestamp.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>z</term> <listitem><para>The Z command returns daemon profiling
information of interest to <application>gpsd</application>
developers. The format of this string is subject to change without
notice.</para></listitem>
</varlistentry>

<varlistentry>
<term>$</term> <listitem><para>The $ command returns daemon profiling
information of interest to <application>gpsd</application>
developers. The format of this string is subject to change without
notice.</para></listitem>
</varlistentry>

</variablelist>

<para>Note that a response consisting of just ? following the =
means that there is no valid data available.  This may mean either
that the device being queried is offline, or (for
position/velocity/time queries) that it is online but has no fix.</para>

<para>Requests can be concatenated and sent as a string;
<application>gpsd</application> will then respond with a
comma-separated list of replies.</para>

<para>Every <application>gpsd</application> reply will start with the
string "GPSD" followed by the replies. Examples:</para>

<screen>
      query:       "p\n"
      reply:       "GPSD,P=36.000000 123.000000\r\n"

      query:       "d\n"
      reply:       "GPSD,D=2002-11-16T02:45:05.12Z\r\n"

      query:       "va\n"
      reply:       "GPSD,V=0.000000,A=37.900000\r\n"
</screen>

<para>The recommended mode for clients is watcher mode.  In watcher
mode <application>gpsd</application> ships a line of data to the
client each time the GPS gets either a fix update or a satellite
picture, but rather than being raw NMEA the line is a gpsd 'o' or 'y'
response.  Additionally, watching clients get notifications in the
form X=0 or X=%f when the online/offline status of the GPS
changes, and an I response giving the device type when the
user is assigned a device.</para>

</refsect1>
<refsect1 id='new_protocol'><title>NEW PROTOCOL</title>

<para>The new GPSD protocol is built on top of JSON, JaveScript
Object Notation. Use of this metaprotocol to pass structured
data between daemon and client avoids the non-extensibility
problems of the old protocol, and permits a richer set of record types
to be passed up to clients.</para>

<para>A request line is introduced by "?" and may include multiple
commands.  Commands begin with a command identifier, followed either
by a terminating ';' or by an equal sign "=" and a JSON object treated
as an argument.  Any ';' or newline indication (either LF or CR-LF)
after the end of a command is ignored. All request lines must be
composed of US-ASCII characters and may be no more than 80 characters
in length, exclusive of the trailing newline.</para>

<para>Responses are JSON objects all of which have a "class" attribute
the value of which is either the name of the invoking command 
or one of the strings "DEVICE" or "ERROR". Their length
limit is 1024 characters, including trailing newline.</para>

<variablelist>

<varlistentry>
<term>?VERSION;</term> 
<listitem><para>Returns an object with the following attributes:</para>

<table frame="all" pgwide="0"><title>VERSION object</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "VERSION"</entry>
</row>
<row>
	<entry>release</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Public release level</entry>
</row>
<row>
	<entry>rev</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Internal revision-control level.</entry>
</row>
<row>
	<entry>api_major</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>API major revision level..</entry>
</row>
<row>
	<entry>api_minor</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>API minor revision level..</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class":"VERSION","version":"2.40dev","rev":$Id$,"api_major":3,"api_minor":1}
</programlisting>


</listitem>
</varlistentry>

<varlistentry>
<term>?DEVICES;</term> 
<listitem><para>Returns a device list object with the
following elements:</para>

<table frame="all" pgwide="0"><title>DEVICES object</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "DEVICES"</entry>
</row>
<row>
	<entry>devices</entry>
	<entry>Yes</entry>
	<entry>list</entry>
        <entry>List of device descriptions</entry>
</row>
</tbody>
</tgroup>
</table>

<para>The list components have the following elements:</para>

<table frame="all" pgwide="0"><title>Device-description object</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "DEVICE"</entry>
</row>
<row>
	<entry>path</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Pathname of the device</entry>
</row>
<row>
	<entry>activated</entry>
	<entry>At device activation and device close time.</entry>
	<entry>numeric</entry>
        <entry>Time the device last sent data.</entry>
</row>
<row>
	<entry>flags</entry>
	<entry>No</entry>
	<entry>integer</entry>
        <entry>Bit vector of property flags.  Currently defined flags are:
        describe packet types seen so far (GPS, RTCM2, RTCM3,
	AIS). Won't be reported if empty, e.g. before
	<application>gpsd</application> has seen identifiable packets
	from the device.</entry>
</row>
<row>
	<entry>driver</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>GPSD's name for the device driver type. Won't be reported before
	<application>gpsd</application> has seen identifiable packets
	from the device.</entry>
</row>
<row>
	<entry>driver</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>GPSD's name for the device driver type.</entry>
</row>
<row>
	<entry>subtype</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>Firmware version or other subtype ID. Not always reported.</entry>
</row>
</tbody>
</tgroup>
</table>

<table frame="all" pgwide="0"><title>Device flags</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>C #define</entry>
	<entry>Value</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>SEEN_GPS</entry>
	<entry>0x01</entry>
	<entry>GPS data has been seen on this device</entry>
</row>
<row>
	<entry>SEEN_RTCM2</entry>
	<entry>0x02</entry>
	<entry>RTCM2 data has been seen on this device</entry>
</row>
<row>
	<entry>SEEN_RTCM3</entry>
	<entry>0x04</entry>
	<entry>RTCM3 data has been seen on this device</entry>
</row>
<row>
	<entry>SEEN_AIS</entry>
	<entry>0x08</entry>
	<entry>GPS data has been seen on this device</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class"="DEVICES","devices":[
    {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"},
    {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]}
</programlisting>

<para>The daemon occasionally ships a bare DEVICE object to the client
(that is, one not inside a DEVICES wrapper). The data content of these
objects will be described later in the section covering
notifications.</para>

</listitem>
</varlistentry>

<varlistentry>
<term>?TPV;</term> 
<listitem><para>Opens a GPS-class device, if available, and requests a
time/position/velocity report object in reply. Mainly intended as a
test command: production clients should use ?WATCH to set up
report streaming.</para>

<para>Here are the elements of a TPV object.  If there is no GPS device
available, only the "class" field will reliably be present.  Others
may be reported or not depending on the fix quality.</para>

<table frame="all" pgwide="0"><title>TPV object</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "TPV"</entry>
</row>
<row>
	<entry>tag</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>Type tag associated with this GPS sentence; from an NMEA
	device this is just the NMEA sentence type..</entry>
</row>
<row>
	<entry>device</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>Name of originating device</entry>
</row>
<row>
	<entry>time</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Seconds since the Unix epoch, UTC. May have a
	fractional part of up to .01sec precision.</entry>
</row>
<row>
	<entry>ept</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Estimated timestamp error (%f, seconds, 95% confidence).</entry>
</row>
<row>
	<entry>lat</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Latitude in degrees: +/- signifies West/East</entry>
</row>
<row>
	<entry>lon</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Longitude in degrees: +/- signifies North/South.</entry>
</row>
<row>
	<entry>alt</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Altitude in meters.</entry>
</row>
<row>
	<entry>eph</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Horizontal circular error in meters, 95% confidence.</entry>
</row>
<row>
	<entry>epv</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Estimated vertical error in meters, 95% confidence.</entry>
</row>
<row>
	<entry>track</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Course over ground, degrees from true north.</entry>
</row>
<row>
	<entry>speed</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Speed over ground, meters per second.</entry>
</row>
<row>
	<entry>climb/sink</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Climb (postive) or sink (negative) rate, meters per 
	second.</entry>
</row>
<row>
	<entry>epd</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Direction error estinmate in degrees, 95% confifdence.</entry>
</row>
<row>
	<entry>eps</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Speed error estinmate in meters/sec, 95% confifdence.</entry>
</row>
<row>
	<entry>epc</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Climb/sink error estinmate in meters/sec, 95% confifdence.</entry>
</row>
<row>
	<entry>mode</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D.</entry>
</row>

</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class":"TPV","tag":"MID2","device":"/dev/pts/1",
    "time":1118327688.280,"ept":0.005,
    "lat":46.498293369,"lon":7.567411672,"alt":1343.127, 
    "eph":36.000,"epv":32.321,
    "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3}
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term>?SKY;</term> 
<listitem><para>Opens a GPS-class device, if available, and requests a
skyview report object in reply. Mainly intended as a test command:
production clients should use ?WATCH to set up report
streaming..</para>

<para>Here are the elements of a SKY object.  If there is no GPS device
available, or no skyview has been reported yet, only the "class" field
will reliably be present.</para>

<table frame="all" pgwide="0"><title>SKY object</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "SKY"</entry>
</row>
<row>
	<entry>tag</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>Type tag associated with this GPS sentence; from an NMEA
	device this is just the NMEA sentence type..</entry>
</row>
<row>
	<entry>device</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>Name of originating device</entry>
</row>
<row>
	<entry>time</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Seconds since the Unix epoch, UTC. May have a
	fractional part of up to .01sec precision.</entry>
</row>
<row>
	<entry>reported</entry>
	<entry>No</entry>
	<entry>numeric</entry>
        <entry>Count of satellites in skyview.</entry>
</row>
<row>
	<entry>satellites</entry>
	<entry>Yes</entry>
	<entry>list</entry>
        <entry>List of satellite objects in skyview</entry>
</row>

</tbody>
</tgroup>
</table>

<para>The satellite list objects have the following elements:</para>

<table frame="all" pgwide="0"><title>Satellite object</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>PRN</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>PRN ID of the satellite</entry>
</row>
<row>
	<entry>az</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>Azimuth, degrees from true north.</entry>
</row>
<row>
	<entry>el</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>Elevation in degrees.</entry>
</row>
<row>
	<entry>ss</entry>
	<entry>Yes</entry>
	<entry>numeric</entry>
        <entry>Signal strength in dB.</entry>
</row>
<row>
	<entry>used</entry>
	<entry>Yes</entry>
	<entry>boolean</entry>
        <entry>Used in current solution?</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Note that satellite objects do not have a "class" field.., as
they are never shipped outside of a SKY object.</para>

<para>Here's an example:</para>

<programlisting>
{"class":"SKY","tag":"MID2","device":"/dev/pts/1","time":1118327688.280
    "reported":8,"satellites":[
        {"PRN":23,"el":6,"az":84,"ss":0,"used":false},
        {"PRN":28,"el":7,"az":160,"ss":0,"used":false},
        {"PRN":8,"el":66,"az":189,"ss":44,"used":true},
        {"PRN":29,"el":13,"az":273,"ss":0,"used":false},
        {"PRN":10,"el":51,"az":304,"ss":29,"used":true},
        {"PRN":4,"el":15,"az":199,"ss":36,"used":true},
        {"PRN":2,"el":34,"az":241,"ss":43,"used":true},
        {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]}
</programlisting>

</listitem>
</varlistentry>

<varlistentry>
<term>?WATCH</term> 
<listitem>

<para>This command sets watcher mode. It also sets or elicits a
report of per-subscriber buffering policy and the raw bit.  An
argument WATCH object changes the subscriber's policy. The respunce
describes the subscriber's policy.</para>

<para>A WATCH object has the following elements:</para>

<table frame="all" pgwide="0"><title>WATCH object</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "WATCH"</entry>
</row>
<row>
	<entry>raw</entry> 
        <entry>No</entry> 
        <entry>integer</entry>
	<entry>Controls 'raw' mode. When this attribute is set
	to 1 for a channel, <application>gpsd</application> reports
	the unprocessed data stream from whatever device is attached.
	(Non-NMEA GPSes get their communication format translated to
	NMEA on the fly.)  If the device is a source of RTCM2
	corrections, the corrections are dumped in the textual format
	described in
	<citerefentry><refentrytitle>rtcm104</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
	the device is a source of AIS data, AIS packets are dumped in
	CSV form with each field (other than padding fields) dumped as
	an unscaled integer or string, whichever is
	appropriate.</entry>
</row>
<row>
	<entry>buffer_policy</entry>
	<entry>No</entry>
	<entry>integer</entry>
        <entry>Get or set buffering policy; this only matters for NMEA
	devices which report fix data in several separate sentences
	during the poll cycle (and in particular it
	<emphasis>doesn't</emphasis> matter for SiRF chips).  The
	default (0) is to clear all fix data at the start of each poll
	cycle, so until the sentence that reports a given piece of
	data arrives queries will report ?.  Setting 1 will disable
	this, retaining data from the previous cycle.  The 0 setting is
	hyper-correct and never displays stale data, but may produce a
	jittery display; the 1 setting allows stale data but smooths
	the display.</entry>
</row>
<row>
	<entry>scaled</entry>
	<entry>No</entry>
	<entry>boolean</entry>
        <entry>If true, apply scaling divisors to output before
	dumping; default is false. Applies only to AIS reports.</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class":"WATCH", "raw":1,"buffer_policy":1."scaled":true}
</programlisting>

</listitem>
</varlistentry>

<varlistentry>
<term>?CONFIGDEV</term> 
<listitem>

<para>This command reports (when followed by ':') or sets (when
followed by by '=' and a CONFIGDEV object) device-specific control
bits, notably the device's speed and serial mode and the native-mode
bit.  It will be rejected if more than one client is attached to the
channel.</para>

<para>Pay attention to the response, because it is
possible for this command to fail if the GPS does not support a
speed-switching command or only supports some combinations of
serial modes.  In case of failure, the daemon and GPS will
continue to communicate at the old speed.</para>

<para>Use this command with caution.  On USB and Bluetooth GPSes it is
also possible for serial mode setting to fail either because the
serial adaptor chip does not support non-8N1 modes or because the
device firmware does not properly synchronize the serrial adaptor chip
with the UART on the GPS chipset whjen the speed changes. These
failures can hang your device, possibly requiring a GPS power cycle or (in
extreme cases) physically disconnecting the NVRAM backup battery.</para>

<para>A CONFIGDEV object has the following elements:</para>

<table frame="all" pgwide="0"><title>CONFIGCHAN object</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "CONFIGDEV"</entry>
</row>
<row>
	<entry>device</entry>
	<entry>No</entry>
	<entry>string</entry>
        <entry>Name the device for which the control bits are
	being reported, or for which they are to be applied. This 
        attribute may be omitted only when there is exactly one 
        subscribed channel.</entry>
</row>
<row>
	<entry>bps</entry>
	<entry>No</entry>
	<entry>integer</entry>
        <entry>Device speed in bits per second.</entry>
</row>
<row>
	<entry>serialmode</entry> 
        <entry>No</entry> 
        <entry>string</entry>
	<entry><para>Parameters of the serial link to the GPS as
        "$d%c%d"; byte size, parity (N, O or E for no parity, odd, or
	even) and stop bits (1 or 2).</para></entry>
</row>
<row>
	<entry>native</entry>
	<entry>No</entry>
	<entry>integer</entry>
        <entry>0 means NMEA mode and 1 means
	alternate mode (binary if it has one, for SiRF and Evermore chipsets
	in particular). Attempting to set this mode on a non-GPS
	device will yield an error.</entry>
</row>
<row>
	<entry>cycle</entry>
	<entry>No</entry>
	<entry>real</entry>
        <entry>Device cycle time in seconds.</entry>
</row>
<row>
	<entry>mincycle</entry>
	<entry>No</entry>
	<entry>real</entry>
        <entry>Device minimum cycle time in seconds. Reported from 
	?CONFIGDEV when (and only when) the rate is switchable. It is 
	read-only and not settable.</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class":"CONFIDEV", "speed":4800,"serialmode":"8N1","native":0}
</programlisting>

</listitem>
</varlistentry>

</variablelist>

<para>When a client is in watcher mode, the daemon may ship it
device status notifications.  These notications will be DEVICE
objects; the table below describes the circumstances and the 
meaning of the attributes.</para>

<table frame="all" pgwide="0"><title>DEVICE notification object</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>When?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>path</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Pathname of the cevice.</entry>
</row>
<row>
	<entry>activated</entry>
	<entry>At device activation and device close time.</entry>
	<entry>numeric</entry>
        <entry>Time the device was activated, 
	or 0 if it is being closed.</entry>
</row>
<row>
	<entry>subtype</entry>
	<entry>When the daemon sees a delayed response to a probe for
	subtype or firmware-version information.</entry>
	<entry>string</entry>
	<entry>Whatever version information the device returned.</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class":"DEVICE","path":"/dev/pts1","activated":0}
</programlisting>

<para>The daemon may ship an error object in response to a
syntactically invalid command line or unknown command. It has
the following elements:</para>

<table frame="all" pgwide="0"><title>ERROR notification object</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
	<entry>Name</entry>
	<entry>Always?</entry>
	<entry>Type</entry>
	<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>Yes</entry>
	<entry>string</entry>
        <entry>Fixed: "ERROR"</entry>
</row>
<row>
	<entry>message</entry>
	<entry>Yes</entry>
	<entry>string</entry>
	<entry>Textual error message</entry>
</row>
</tbody>
</tgroup>
</table>

<para>Here's an example:</para>

<programlisting>
{"class":"ERROR","message":"Unrecognized request '?FOO'"}
</programlisting>

</refsect1>
<refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title>

<para><application>gpsd</application> maintains an internal list of
GPS devices.  If you specify devices on the command line, the list is
initialized with those pathnames; otherwise the list starts empty.
Commands to add and remove GPS device paths from the daemon's device
list must be written to a local Unix-domain socket which will be
accessible only to programs running as root.  This control socket will
be located wherever the -F option specifies it.</para>

<para>When <application>gpsd</application> is properly installed along
with hotplug notifier scripts feeding it device-add commands over the
control socket, <application>gpsd</application> should require no
configuration or user action to find devices.</para>

<para>Sending SIGHUP to a running <application>gpsd</application>
forces it to close all GPSes and all client connections.  It will then
attempt to reconnect to any GPSes on its device list and resume
listening for client connections.  This may be useful if your GPS
enters a wedged or confused state but can be soft-reset by pulling
down DTR.</para>

<para>To point <application>gpsd</application> at a device that may be
a GPS, write to the control socket a plus sign ('+') followed by the
device name followed by LF or CR-LF.  Thus, to point the daemon at
<filename>/dev/foo</filename>. send "+/dev/foo\n".  To tell the daemon
that a device has been disconnected and is no longer available, send a
minus sign ('-') followed by the device name followed by LF or
CR-LF. Thus, to remove <filename>/dev/foo</filename> from the search
list. send "-/dev/foo\n".</para>

<para>To send a control string to a specified device, write to the
control socket a '!', followed by the device name, followed by '=',
followed by the control string.</para>

<para>To send a binary control string to a specified device, write to the
control socket a '&amp;', followed by the device name, followed by '=',
followed by the control string in paired hex digits.</para>

<para>Your client may await a response, which will be a line beginning
with either "OK" or "ERROR".  An ERROR reponse to an add command means
the device did not emit data recognizable as GPS packets; an ERROR
response to a remove command means the specified device was not in
<application>gpsd</application>'s device list. An ERROR response to a
! command means the daemon did not recognize the devicename
specified.</para>

<para>The control socket is intended for use by hotplug scripts and
other device-discovery services.  This control channel is separate
from the public <application>gpsd</application> service port, and only
locally accessible, in order to prevent remote denial-of-service and
spoofing attacks.</para>

</refsect1>
<refsect1 id='accuracy'><title>ACCURACY</title>

<para>The base User Estimated Range Error (UERE) of GPSes is 8 meters
or less at 66% confidence, 15 meters or less at 95% confidence. Actual
horizontal error will be UERE times a dilution factor dependent on current
satellite position.  Altitude determination is more sensitive to
variability to atmospheric signal lag than latitude/longitude, and is
also subject to errors in the estimation of local mean sea level; base
error is 12 meters at 66% confidence, 23 meters at 95% confidence.
Again, this will be multiplied by a vertical dilution of precision
(VDOP) dependent on satellite geometry, and VDOP is typically larger
than HDOP.  Users should <emphasis>not</emphasis> rely on GPS altitude for
life-critical tasks such as landing an airplane.</para>

<para>These errors are intrinsic to the design and physics of the GPS
system.  <application>gpsd</application> does its internal
computations at sufficient accuracy that it will add no measurable
position error of its own.</para>

<para>DGPS correction will reduce UERE by a factor of 4, provided you
are within about 100mi (160km) of a DGPS ground station from which you
are receiving corrections.</para>

<para>On a 4800bps connection, the time latency of fixes provided by
<application>gpsd</application> will be one second or less 95% of the
time.  Most of this lag is due to the fact that GPSes normally emit
fixes once per second, thus expected latency is 0.5sec.  On the
personal-computer hardware available in 2005, computation lag induced
by <application>gpsd</application> will be negligible, on the order of
a millisecond.  Nevertheless, latency can introduce significant errors
for vehicles in motion; at 50km/h (31mi/h) of speed over ground, 1
second of lag corresponds to 13.8 meters change in position between
updates.</para>

<para>The time reporting of the GPS system itself has an intrinsic
accuracy limit of 0.000,000,340 =
3.4&times;10<superscript>-7</superscript> seconds.  A more important
limit is the GPS tick rate.  While the one-per-second PPS pulses
emitted by serial GPS units are timed to the GPS system's intrinsic
accuracy limit,the satellites only emit navigation messages at
0.01-second intervals, and the timestamps in them only carry
0.01-second precision. Thus, the timestamps that
<application>gpsd</application> reports in time/position/velocity
messages are normally accurate only to 1/100th of a second.</para>

</refsect1>
<refsect1 id='ntp'><title>USE WITH NTP</title>

<para>gpsd can provide reference clock information to
<application>ntpd</application>, to keep the system clock synchronized
to the time provided by the GPS receiver.  This facility is
only available when the daemon is started from root.  If you're going
to use <application>gpsd</application> you probably want to run it
<option>-n</option> mode so the clock will be updated even when no
clients are active.</para>

<para>Note that deriving time from messages received from the GPS is
not as accurate as you might expect.  Messages are often delayed in
the receiver and on the link by several hundred milliseconds, and this
delay is not constant.  On Linux, <application>gpsd</application>
includes support for interpreting the PPS pulses emitted at the start
of every clock second on the carrier-detect lines of some serial
GPSes; this pulse can be used to update NTP at much higher accuracy
than message time provides.  You can determine whether your GPS emits
this pulse by running at -D 5 and watching for carrier-detect state
change messages in the logfile.</para>

<para>When <application>gpsd</application> receives a sentence with a
timestamp, it packages the received timestamp with current local time
and sends it to a shared-memory segment with an ID known to
<application>ntpd</application>, the network time synchronization
daemon.  If <application>ntpd</application> has been properly
configured to receive this message, it will be used to correct the
system clock.</para>

<para>Here is a sample <filename>ntp.conf</filename> configuration
stanza telling <application>ntpd</application> how to read the GPS
notfications:</para>

<programlisting>
server 127.127.28.0 minpoll 4 maxpoll 4
fudge 127.127.28.0 time1 0.420 refid GPS

server 127.127.28.1 minpoll 4 maxpoll 4 prefer
fudge 127.127.28.1 refid GPS1
</programlisting>

<para>The magic pseudo-IP address 127.127.28.0 identifies unit 0 of
the <application>ntpd</application> shared-memory driver; 127.127.28.1
identifies unit 1.  Unit 0 is used for message-decoded time and unit 1
for the (more accurate, when available) time derived from the PPS
synchronization pulse.  Splitting these notifications allows
<application>ntpd</application> to use its normal heuristics to weight
them.</para>

<para>With this configuration, <application>ntpd</application> will
read the timestamp posted by <application>gpsd</application> every 16
seconds and send it to unit 0.  The number after the parameter time1
is an offset in seconds.  You can use it to adjust out some of the
fixed delays in the system.  0.035 is a good starting value for the
Garmin GPS-18/USB, 0.420 for the Garmin GPS-18/LVC.</para>

<para>After restarting ntpd, a line similar to the one below should
appear in the output of the command "ntpq -p" (after allowing a couple
of minutes):</para>

<screen>
remote	   refid      st t when poll reach  delay    offset  jitter
=========================================================================
+SHM(0)	  .GPS.      0 l   13   16  377    0.000    0.885   0.882
</screen>

<para>If you are running PPS then it will look like this:</para>

<screen>
remote	   refid      st t when poll reach  delay    offset  jitter
=========================================================================
-SHM(0)	  .GPS.      0 l   13   16  377    0.000    0.885   0.882
*SHM(1)	  .GPS1.     0 l   11   16  377    0.000   -0.059   0.006
</screen>

<para>When the value under "reach" remains zero, check that gpsd is
running; and some application is connected to it or the '-n' option was
used.  Make sure the receiver is locked on to at least one satellite,
and the receiver is in SiRF binary, Garmin binary or NMEA/PPS mode.  Plain
NMEA will also drive ntpd, but the accuracy as bad as one second.  When
the SHM(0) line does not appear at all, check the system logs for error
messages from ntpd.</para>

<para>When no other reference clocks appear in the NTP configuration,
the system clock will lock onto the GPS clock.  When you have previously
used <application>ntpd</application>, and other reference clocks appear
in your configuration, there may be a fixed offset between the GPS clock
and other clocks.  The <application>gpsd</application> developers would
like to receive information about the offsets observed by users for each
type of receiver.  Please send us the output of the "ntpq -p" command
and the make and type of receiver.</para>

</refsect1>
<refsect1 id='dbus'><title>USE WITH D-BUS</title>

<para>On operating systems that support D-BUS,
<application>gpsd</application> can be built to broadcast GPS fixes to
D-BUS-aware applications.  As D-BUS is still at a pre-1.0 stage, we
will not attempt to document this interface here.  Read the
<application>gpsd</application> source code to learn more.</para>

</refsect1>
<refsect1 id='security'><title>SECURITY AND PERMISSIONS ISSUES</title>

<para><application>gpsd</application>, if given the -G flag, will
listen for connections from any reachable host, and then disclose the
current position.  Before using the -G flag, consider whether you
consider your computer's location to be sensitive data to be kept
private or something that you wish to publish.</para>

<para><application>gpsd</application> must start up as root in order
to open the NTPD shared-memory segment, open its logfile, and create
its local control socket.  Before doing any processing of GPS data, it
tries to drop root privileges by setting its UID to "nobody" (or another
userid as set by configure) and its group ID to the group of the initial
GPS passed on the command line &mdash; or, if that device doesn't exist,
to the group of <filename>/dev/ttyS0</filename>.</para>

<para>Privilege-dropping is a hedge against the possibility that
carefully crafted data, either presented from a client socket or from
a subverted serial device posing as a GPS, could be used to induce
misbehavior in the internals of <application>gpsd</application>.
It ensures that any such compromises cannot be used for privilege
elevation to root.</para>

<para>The assumption behind <application>gpsd</application>'s
particular behavior is that all the tty devices to which a GPS might
be connected are owned by the same non-root group and allow group
read/write, though the group may vary because of distribution-specific
or local administrative practice.  If this assumption is false,
<application>gpsd</application> may not be able to open GPS devices in
order to read them (such failures will be logged).</para>

<para>In order to fend off inadvertent denial-of-service attacks by
port scanners (not to mention deliberate ones),
<application>gpsd</application> will time out inactive client
connections.  Before the client has issued a command that requests a
channel assignment, a short timeout (60 seconds) applies.  There is no
timeout for clients in watcher or raw modes; rather,
<application>gpsd</application> drops these clients if they fail to
read data long enough for the outbound socket write buffer to fill.
Clients with an assigned device in polling mode are subject to a
longer timeout (15 minutes).</para>

</refsect1>
<refsect1 id='limitations'><title>LIMITATIONS</title>

<para>If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences
to the same serial device (possible with an RS422 adapter hooked up to
some marine-navigation systems), an 'O' response may mix an altitude
from one device's GGA with latitude/longitude from another's RMC/GLL
after the second sentence has arrived.</para>

<para><application>gpsd</application> may change control settings on
your GPS (such as the emission frequency of various sentences or
packets) and not restore the original settings on exit.  This is a
result of inadequacies in NMEA and the vendor binary GPS protocols,
which often do not give clients any way to query the values of control
settings in order to be able to restore them later.</para>

<para>If your GPS uses a SiRF chipset at firmware level 231, and it is
after 31 May 2007, reported UTC time may be off by the difference
between 13 seconds and whatever leap-second correction is currently
applicable, from startup until complete subframe information is
received (normally about six seconds).  Firmware levels 232 and up
don't have this problem.  You may run <application>gpsd</application> at
debug level 4 to see the chipset type and firmware revision
level.</para>

<para>When using SiRF chips, the VDOP/TDOP/GDOP figures and associated
error estimates are computed by <application>gpsd</application> rather
than reported by the chip.  The computation does not exactly match
what SiRF chips do internally, which includes some satellite weighting
using parameters <application>gpsd</application> cannot see.</para>

<para>Autobauding on the Trimble GPSes can take as long as 5 seconds
if the device speed is not matched to the GPS speed.</para>

<para>If you are using an NMEA-only GPS (that is, not using SiRF or
Garmin or Zodiac binary mode) and the GPS does not emit GPZDA at the
start of its update cycle (which most consumer-grade NMEA GPSes do
not) and it is after 2099, then the century part of the dates
<application>gpsd</application> delivers will be wrong.</para>

</refsect1>
<refsect1 id='files'><title>FILES</title>

<variablelist>
<varlistentry>
<term><filename>/dev/ttyS0</filename></term>
<listitem>
<para>Prototype TTY device. After startup,
<application>gpsd</application> sets its group ID to the owner of this
device if no GPS device was specified on the command line does not
exist.</para>
</listitem>
</varlistentry>
<!--
<varlistentry>
<term><filename>/usr/share/gpsd/dgpsip-servers</filename></term>
<listitem>
<para>A text file listing DGPSIP servers worldwide.  If no DGPSIP
server is specified at startup (via the -d option)
<application>gpsd</application> will look here to find the
nearest one.  Each line has three space-separated fields:
latitude (decimal degrees), longitude (decimal degrees) and
a server name (optionally followed by a colon and a port number).
Text following # on a line is ignored.  Blank lines are ignored.</para>
</listitem>
</varlistentry>
-->
</variablelist>

</refsect1>
<refsect1 id='standards'><title>APPLICABLE STANDARDS</title>

<para>The official NMEA protocol standard is available on paper from
the <ulink url='http://www.nmea.org/pub/0183/'>National Marine
Electronics Association</ulink>, but is proprietary and expensive; the
maintainers of <application>gpsd</application> have made a point of
not looking at it.  The <ulink url="http://gpsd.berlios.de/">GPSD
website</ulink> links to several documents that collect publicly
disclosed information about the protocol.</para>

<para><application>gpsd</application> parses the following NMEA
sentences: RMC, GGA, GLL, GSA, GSV, VTG, ZDA.  It recognizes these
with either the normal GP talker-ID prefix, or with the II prefix
emitted by Seahawk Autohelm marine navigation systems, or with the IN
prefix emitted by some Garmin units.  It recognizes one vendor
extension, the PGRME emitted by some Garmin GPS models.</para>

<para>Note that <application>gpsd</application> returns pure decimal
degrees, not the hybrid degree/minute format described in the NMEA
standard.</para>

<para>Differential-GPS corrections are conveyed by the RTCM-104
proocol. The applicable standard for RTCM-104 V2 is <citetitle>RTCM
Recommended Standards for Differential NAVSTAR GPS Service</citetitle>
RTCM Paper 194-93/SC 104-STD.  The applicable standard for RTCM-104 V3
is <citetitle>RTCM Standard 10403.1 for Differential GNSS Services -
Version 3</citetitle> RTCM Paper 177-2006-SC104-STD.</para>

</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</refsect1>

<refsect1 id='maintainer'><title>AUTHORS</title>

<para>Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond,
Chris Kuethe.  This manual page by Eric S. Raymond
<email>esr@thyrsus.com</email>.  There is a project site at <ulink
url="http://gpsd.berlios.de/">here</ulink>.</para>
</refsect1>

</refentry>