forked from bzed/pkg-gpsd
-
Notifications
You must be signed in to change notification settings - Fork 0
/
gpsctl.1
177 lines (177 loc) · 7.38 KB
/
gpsctl.1
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
'\" t
.\" Title: gpsctl
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\" Date: 29 Oct 2006
.\" Manual: GPSD Documentation
.\" Source: The GPSD Project
.\" Language: English
.\"
.TH "GPSCTL" "1" "29 Oct 2006" "The GPSD Project" "GPSD Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gpsctl \- control the modes of a GPS
.SH "SYNOPSIS"
.HP \w'\fBgpsctl\fR\ 'u
\fBgpsctl\fR [\-h] [\-b | \-n] [\-x\ \fIcontrol\fR] [\-e] [\-f] [\-l] [\-s\ \fIspeed\fR] [\-t\ \fIdevicetype\fR] [\-R] [\-D\ \fIdebuglevel\fR] [\-V] [\fIserial\-port\fR]
.SH "DESCRIPTION"
.PP
gpsctl
can switch a dual\-mode GPS between NMEA and vendor\-binary modes\&. It can also be used to set the device baudrate\&. Note: Not all devices have these capabilities\&.
.PP
If you have only one GPS attached to your machine, and gpsd is running, it is not necessary to specify the device;
gpsctl
does its work through
gpsd, which will locate it for you\&.
.PP
When
gpsd
is not running, the device specification is required, and you will need to be running as root or be a member of the device\*(Aqs owning group in order to have write access to the device\&. On many Unix variants the owning group will be named \*(Aqdialout\*(Aq\&.
.PP
The program accepts the following options:
.PP
\-b
.RS 4
Put the GPS into native (binary) mode\&.
.RE
.PP
\-c
.RS 4
Change the GPS\*(Aqs cycle time\&. Units are seconds\&. Note, most GPSes have a fixed cycle time of 1 second\&.
.RE
.PP
\-e
.RS 4
Generate the packet from any other arguments specified and ship it to standard output instead of the device\&. This switch can be used with the
\fB\-t\fR
option without specifying a device\&. Note: the packet data for a binary prototype will be raw, not ASCII\-ized in any way\&.
.RE
.PP
\-f
.RS 4
Force low\-level access (not through the daemon)\&.
.RE
.PP
\-l
.RS 4
List a table showing which option switches can be applied to which device types, and exit\&.
.RE
.PP
\-n
.RS 4
Put GPS into NMEA mode\&.
.RE
.PP
\-s
.RS 4
Set the baud rate at which the GPS emits packets\&.
.sp
Use this option 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 serial adaptor chip with the UART on the GPS chipset when 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\&.
.RE
.PP
\-t
.RS 4
Force the device type\&.
.RE
.PP
\-x
.RS 4
Send a specified control string to the GPS;
gpsctl
will provide packet headers and trailers and checksum as appropriate for binary packet types, and whatever checksum and trailer is required for text packet types\&. (You must include the leading $ for NMEA packets\&.) When sending to a UBX device, the first two bytes of the string supplied will become the message class and type, and the remainder the payload\&. When sending to a Navcom NCT or Trimble TSIP device, the first byte is interpreted as the command ID and the rest as payload\&. When sending to a Zodiac device, the first two bytes are used as a message ID of type little\-endian short, and the remainder as payload in byte pairs interpreted as little\-endian short\&. For all other supported binary GPSes (notably including SiRF) the string is taken as the entire message payload and wrapped with appropriate header, trailer and checksum bytes\&. C\-style backslash escapes in the string, notably \exNN for hex, will be interpreted; additionally, \ee will be replaced with ESC\&. This switch implies
\fB\-f\fR\&.
.RE
.PP
\-T
.RS 4
Change the sampling timeout\&. Defaults to 8 seconds, which should always be sufficient to get an identifying packet from a device emitting at the normal rate of 1 per second\&.
.RE
.PP
\-R
.RS 4
Remove the GPSD shared\-memory segment used for SHM export\&. This option will normally only be of interest to GPSD developers\&.
.RE
.PP
\-h
.RS 4
Display program usage and exit\&.
.RE
.PP
\-D
.RS 4
Set level of debug messages\&.
.RE
.PP
\-V
.RS 4
Display program version and exit\&.
.RE
.PP
The argument of the forcing option,
\fB\-t\fR, should be a string which is contained in exactly one of the known driver names; for a list, do
\fBgpsctl \-l\fR\&.
.PP
Forcing the device type behaves somewhat differently depending on whether this tool is going through the daemon or not\&. In high\-level mode, if the device that daemon selects for you doesn\*(Aqt match the driver you specified,
gpsctl
exits with a warning\&. (This may be useful in scripts\&.)
.PP
In low\-level mode, if the device identifies as a Generic NMEA, use the selected driver instead\&. This will be useful if you have a GPS device of known type that is in NMEA mode and not responding to probes\&. (This option was originally implemented for talking to SiRFStar I chips, which don\*(Aqt respond to the normal SiRF ID probe\&.)
.PP
If no options are given, the program will display a message identifying the GPS type of the selected device and exit\&.
.PP
Reset (\-r) operations must stand alone; others can be combined\&. Multiple options will be executed in this order: mode changes (\-b and \-n) first, speed changes (\-s) second, and control\-string sends (\-c) last\&.
.SH "ENVIRONMENT VARIABLES"
.PP
By setting the environment variable
\fBGPSD_SHM_KEY\fR, you can control the key value used to designate the shared\-memory segment removed with the \-R option\&. This will be useful mainly when isolating test instances of
gpsd
from production ones\&.
.SH "EXAMPLES"
.PP
\fBgpsctl /dev/ttyUSB0\fR
.RS 4
Attempt to identify the device on USB serial device 0\&. Time out after the default number of seconds\&. Adding the
\fB\-f\fR
will force low\-level access and suppress the normal complaint when this tool can\*(Aqt find a GPSD to work through\&.
.RE
.PP
gpsctl \-f \-n \-s 9600 /dev/ttyUSB0
.RS 4
Use low\-level operations (not going through a gpsd instance) to switch a GPS to NMEA mode at 9600bps\&. The tool will identify the GPS type itself\&.
.RE
.SH "BUGS"
.PP
SiRF GPSes can only be identified by the success of an attempt to flip them into SiRF binary mode\&. Thus, the process of probing one of these running in NMEA will change its behavior\&.
.PP
Baud rate and mode changes work in direct mode but are not reliable in client mode\&. This will be fixed in a future release\&.
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8),
\fBgpsdctl\fR(8),
\fBgps\fR(1),
\fBlibgps\fR(3),
\fBlibgpsmm\fR(3),
\fBgpsprof\fR(1),
\fBgpsfake\fR(1)\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
<esr@thyrsus\&.com>\&.