1GPSCTL(1) GPSD Documentation GPSCTL(1)
2
6 gpsctl - control the modes of a GPS
7
9 gpsctl [-? | --binary | --nmea | --reset] [--debug LVL] [--direct]
10 [--echo] [--help] [--list] [--rate] [--rmshm] [--rate rate]
11 [--ship control] [--speed speed] [--timeout devicetype]
12 [--version] [-b | -n | -r] [-D LVL] [-c rate] [-e] [-f] [-h]
13 [-l] [-R] [-s speed] [-t devicetype] [-V] [-x control]
14 [serial-port]
15
17 gpsctl can switch a dual-mode GPS between NMEA and vendor-binary modes.
18 It can also be used to set the device baud rate. Note: Not all devices
19 have these capabilities.
20 If you have only one GPS attached to your machine, and gpsd is running,
22 it is not necessary to specify the device; gpsctl does its work through
23 gpsd, which will locate it for you.
24 When gpsd is not running, the device specification is required, and you
26 will need to be running as root or be a member of the device's owning
27 group in order to have write access to the device. On many Unix
28 variants the owning group will be named 'dialout'.
29 The program accepts the following options:
31 -?, -h, --help
33 Display program usage and exit.
34 -b, --binary
36 Put the GPS into native (binary) mode.
37 -c RATE, --rate RATE
39 Change the GPS's cycle time. Units are seconds. Note, most GPSes
40 have a fixed cycle time of 1 second.
41 -D LVL, --debug LVL
43 Set level of debug messages.
44 -e, --echo
46 Generate the packet from any other arguments specified and ship it
47 to standard output instead of the device. This switch can be used
48 with the -t option without specifying a device. Note: the packet
49 data for a binary prototype will be raw, not ASCII-ized in any way.
50 -f, --force
52 Force low-level access (not through the daemon).
53 -l, --list
55 List a table showing which option switches can be applied to which
56 device types, and exit.
57 -n, --nmea
59 Put GPS into NMEA mode.
60 -r, --reset
62 Reset the GPS. Device port and type must be specified.
63 -R, --rmshm
65 Remove the GPSD shared-memory segment used for SHM export. This
66 option will normally only be of interest to GPSD developers.
67 -s SPEED, --speed SPEED
69 Set the baud rate at which the GPS emits packets.
70 Use this option with caution. On USB and Bluetooth GPSes it is also
72 possible for serial mode setting to fail either because the serial
73 adaptor chip does not support non-8N1 modes or because the device
74 firmware does not properly synchronize the serial adaptor chip with
75 the UART on the GPS chipset when the speed changes. These failures
76 can hang your device, possibly requiring a GPS power cycle or (in
77 extreme cases) physically disconnecting the NVRAM backup battery.
78 -t TYPE, --type TYPE
80 Force the device type.
81 -T TIMEOUT, --timeout TIMEOUT
83 Change the sampling timeout. Defaults to 8 seconds, which should
84 always be sufficient to get an identifying packet from a device
85 emitting at the normal rate of 1 per second.
86 -V, --version
88 Display program version and exit.
89 -x STR, --ship STR
91 Send a specified control string to the GPS; gpsctl will provide
92 packet headers and trailers and checksum as appropriate for binary
93 packet types, and whatever checksum and trailer is required for
94 text packet types. (You must include the leading $ for NMEA
95 packets.) When sending to a UBX device, the first two bytes of the
96 string supplied will become the message class and type, and the
97 remainder the payload. When sending to a Navcom NCT or Trimble TSIP
98 device, the first byte is interpreted as the command ID and the
99 rest as payload. When sending to a Zodiac device, the first two
100 bytes are used as a message ID of type little-endian short, and the
101 remainder as payload in byte pairs interpreted as little-endian
102 short. For all other supported binary GPSes (notably including
103 SiRF) the string is taken as the entire message payload and wrapped
104 with appropriate header, trailer and checksum bytes. C-style
105 backslash escapes in the string, notably \xNN for hex, will be
106 interpreted; additionally, \e will be replaced with ESC. This
107 switch implies -f.
108 The argument of the forcing option, -t, should be a string which is
110 contained in exactly one of the known driver names; for a list, do
111 gpsctl -l.
112 Forcing the device type behaves somewhat differently depending on
114 whether this tool is going through the daemon or not. In high-level
115 mode, if the device that daemon selects for you doesn't match the
116 driver you specified, gpsctl exits with a warning. (This may be useful
117 in scripts.)
118 In low-level mode, if the device identifies as a Generic NMEA, use the
120 selected driver instead. This will be useful if you have a GPS device
121 of known type that is in NMEA mode and not responding to probes. (This
122 option was originally implemented for talking to SiRFStar I chips,
123 which don't respond to the normal SiRF ID probe.)
124 If no options are given, the program will display a message identifying
126 the GPS type of the selected device and exit.
127 Reset (-r) operations must stand alone; others can be combined.
129 Multiple options will be executed in this order: mode changes (-b and
130 -n) first, speed changes (-s) second, and control-string sends (-c)
131 last.
132
134 By setting the environment variable GPSD_SHM_KEY, you can control the
135 key value used to designate the shared-memory segment removed with the
136 -R option. This will be useful mainly when isolating test instances of
137 gpsd from production ones.
138
140 gpsctl /dev/ttyUSB0
141 Attempt to identify the device on USB serial device 0. Time out
142 after the default number of seconds. Adding the -f will force
143 low-level access and suppress the normal complaint when this tool
144 can't find a GPSD to work through.
145 gpsctl -f -n -s 9600 /dev/ttyUSB0
147 Use low-level operations (not going through a gpsd instance) to
148 switch a GPS to NMEA mode at 9600bps. The tool will identify the
149 GPS type itself.
150
152 SiRF GPSes can only be identified by the success of an attempt to flip
153 them into SiRF binary mode. Thus, the process of probing one of these
154 running in NMEA will change its behavior.
155 Baud rate and mode changes work in direct mode but are not reliable in
157 client mode. This will be fixed in a future release.
158
160 gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),
161 gpsfake(1).
162
164 Eric S. Raymond <esr@thyrsus.com>.
165The GPSD Project 6 December 2020 GPSCTL(1)