1GPSCTL(1)                     GPSD Documentation                     GPSCTL(1)
2
3
4

NAME

6       gpsctl - control the modes of a GPS
7

SYNOPSIS

9       gpsctl [-h] [-b | -n] [-x control] [-e] [-f] [-l] [-s speed]
10              [-t devicetype] [-R] [-D debuglevel] [-V] [serial-port]
11

DESCRIPTION

13       gpsctl can switch a dual-mode GPS between NMEA and vendor-binary modes.
14       It can also be used to set the device baudrate. Note: Not all devices
15       have these capabilities.
16
17       If you have only one GPS attached to your machine, and gpsd is running,
18       it is not necessary to specify the device; gpsctl does its work through
19       gpsd, which will locate it for you.
20
21       When gpsd is not running, the device specification is required, and you
22       will need to be running as root or be a member of the device's owning
23       group in order to have write access to the device. On many Unix
24       variants the owning group will be named 'dialout'.
25
26       The program accepts the following options:
27
28       -b
29           Put the GPS into native (binary) mode.
30
31       -c
32           Change the GPS's cycle time. Units are seconds. Note, most GPSes
33           have a fixed cycle time of 1 second.
34
35       -e
36           Generate the packet from any other arguments specified and ship it
37           to standard output instead of the device. This switch can be used
38           with the -t option without specifying a device. Note: the packet
39           data for a binary prototype will be raw, not ASCII-ized in any way.
40
41       -f
42           Force low-level access (not through the daemon).
43
44       -l
45           List a table showing which option switches can be applied to which
46           device types, and exit.
47
48       -n
49           Put GPS into NMEA mode.
50
51       -s
52           Set the baud rate at which the GPS emits packets.
53
54           Use this option with caution. On USB and Bluetooth GPSes it is also
55           possible for serial mode setting to fail either because the serial
56           adaptor chip does not support non-8N1 modes or because the device
57           firmware does not properly synchronize the serial adaptor chip with
58           the UART on the GPS chipset when the speed changes. These failures
59           can hang your device, possibly requiring a GPS power cycle or (in
60           extreme cases) physically disconnecting the NVRAM backup battery.
61
62       -t
63           Force the device type.
64
65       -x
66           Send a specified control string to the GPS; gpsctl will provide
67           packet headers and trailers and checksum as appropriate for binary
68           packet types, and whatever checksum and trailer is required for
69           text packet types. (You must include the leading $ for NMEA
70           packets.) When sending to a UBX device, the first two bytes of the
71           string supplied will become the message class and type, and the
72           remainder the payload. When sending to a Navcom NCT or Trimble TSIP
73           device, the first byte is interpreted as the command ID and the
74           rest as payload. When sending to a Zodiac device, the first two
75           bytes are used as a message ID of type little-endian short, and the
76           remainder as payload in byte pairs interpreted as little-endian
77           short. For all other supported binary GPSes (notably including
78           SiRF) the string is taken as the entire message payload and wrapped
79           with appropriate header, trailer and checksum bytes. C-style
80           backslash escapes in the string, notably \xNN for hex, will be
81           interpreted; additionally, \e will be replaced with ESC. This
82           switch implies -f.
83
84       -T
85           Change the sampling timeout. Defaults to 8 seconds, which should
86           always be sufficient to get an identifying packet from a device
87           emitting at the normal rate of 1 per second.
88
89       -R
90           Remove the GPSD shared-memory segment used for SHM export. This
91           option will normally only be of interest to GPSD developers.
92
93       -h
94           Display program usage and exit.
95
96       -D
97           Set level of debug messages.
98
99       -V
100           Display program version and exit.
101
102       The argument of the forcing option, -t, should be a string which is
103       contained in exactly one of the known driver names; for a list, do
104       gpsctl -l.
105
106       Forcing the device type behaves somewhat differently depending on
107       whether this tool is going through the daemon or not. In high-level
108       mode, if the device that daemon selects for you doesn't match the
109       driver you specified, gpsctl exits with a warning. (This may be useful
110       in scripts.)
111
112       In low-level mode, if the device identifies as a Generic NMEA, use the
113       selected driver instead. This will be useful if you have a GPS device
114       of known type that is in NMEA mode and not responding to probes. (This
115       option was originally implemented for talking to SiRFStar I chips,
116       which don't respond to the normal SiRF ID probe.)
117
118       If no options are given, the program will display a message identifying
119       the GPS type of the selected device and exit.
120
121       Reset (-r) operations must stand alone; others can be combined.
122       Multiple options will be executed in this order: mode changes (-b and
123       -n) first, speed changes (-s) second, and control-string sends (-c)
124       last.
125

ENVIRONMENT VARIABLES

127       By setting the environment variable GPSD_SHM_KEY, you can control the
128       key value used to designate the shared-memory segment removed with the
129       -R option. This will be useful mainly when isolating test instances of
130       gpsd from production ones.
131

EXAMPLES

133       gpsctl /dev/ttyUSB0
134           Attempt to identify the device on USB serial device 0. Time out
135           after the default number of seconds. Adding the -f will force
136           low-level access and suppress the normal complaint when this tool
137           can't find a GPSD to work through.
138
139       gpsctl -f -n -s 9600 /dev/ttyUSB0
140           Use low-level operations (not going through a gpsd instance) to
141           switch a GPS to NMEA mode at 9600bps. The tool will identify the
142           GPS type itself.
143

BUGS

145       SiRF GPSes can only be identified by the success of an attempt to flip
146       them into SiRF binary mode. Thus, the process of probing one of these
147       running in NMEA will change its behavior.
148
149       Baud rate and mode changes work in direct mode but are not reliable in
150       client mode. This will be fixed in a future release.
151

SEE ALSO

153       gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),
154       gpsfake(1).
155

AUTHOR

157       Eric S. Raymond <esr@thyrsus.com>.
158
159
160
161The GPSD Project                  29 Oct 2006                        GPSCTL(1)
Impressum