1GPSCTL(1) GPSD Documentation GPSCTL(1)
2
6 gpsctl - control the modes of a GNSS receiver
7
9 gpsctl [OPTIONS] [serial-port]
10 gpsctl -h
12 gpsctl -V
14
16 gpsctl can switch a dual-mode GNSS receiver between NMEA and
17 vendor-binary modes. It can also be used to set the device baud rate.
18 Note: Not all devices have these capabilities.
19 If you have only one GNSS receiver attached to your machine, and gpsd
21 is running, it is not necessary to specify the device; gpsctl does its
22 work through gpsd, which will locate it for you.
23 When gpsd is running, gpsctl may be run as any user, or as root.
25 When gpsd is not running, the device specification is required, and you
27 will need to be running as root or be a member of the device’s owning
28 group in order to have write access to the device. On many Unix
29 variants the owning group will be named 'dialout'.
30 Running under sudo will cause some loss of functionality.
32
34 The program accepts the following options:
35 -?, -h, --help
37 Display program usage and exit.
38 -b, --binary
40 Put the GNSS receiver into native (binary) mode.
41 -c RATE, --rate RATE
43 Change the receivers’s cycle time. Units are seconds. Note, most
44 receivers have a fixed cycle time of 1 second.
45 -D LVL, --debug LVL
47 Set level of debug messages.
48 -e, --echo
50 Generate the packet from any other arguments specified and ship it
51 to standard output instead of the device. This switch can be used
52 with the -t option without specifying a device. Note: the packet
53 data for a binary prototype will be raw, not ASCII-ized in any way.
54 -f, --force
56 Force low-level, direct, access (not through the daemon).
57 -l, --list
59 List a table showing which option switches can be applied to which
60 device types, and exit.
61 -n, --nmea
63 Put the GNSS receiver into NMEA mode.
64 -r, --reset
66 Reset the GNSS receiver. Device port and type must be specified.
67 -R, --rmshm
69 Remove the GPSD shared-memory segment used for SHM export. This
70 option will normally only be of interest to GPSD developers.
71 -s SPEED, --speed SPEED
73 Set the baud rate at which the receiver emits packets.
74 Use the -s option with caution. On USB and Bluetooth GPSes it is also
76 possible for serial mode setting to fail either because the serial
77 adaptor chip does not support non-8N1 modes or because the device
78 firmware does not properly synchronize the serial adaptor chip with the
79 UART on the GPS chipset when the speed changes. These failures can hang
80 your device, possibly requiring a GPS power cycle or (in extreme cases)
81 physically disconnecting the NVRAM backup battery.
82 -t TYPE, --type TYPE
84 Force the device type.
85 -T TIMEOUT, --timeout TIMEOUT
87 Change the sampling timeout. Defaults to 8 seconds, which should
88 always be sufficient to get an identifying packet from a device
89 emitting at the normal rate of 1 per second.
90 -V, --version
92 Display program version and exit.
93 -x STR, --ship STR
95 Send the specified control string to the GNSS receiver. C-style
96 backslash escapes in the string are decoded. Use \xNN for hex, \e
97 will be replaced with ESC.
98 In normal mode, through _gpsd_, the decoded string is passed through,
100 unchanged top _gpsd_ which in turns sends it to the receiver. Headers,
101 checksums, and suffffices must be provided.
102 In low-level, (direct) mode *gpsctl* will provide packet headers and
104 trailers and checksum as appropriate for binary packet types, and
105 whatever checksum and trailer is required for text packet types.
106 (You must include the leading $ for NMEA packets.) When sending to a
107 UBX device, the first two bytes of the string supplied will become
108 the message class and type, and the remainder the payload. When
109 sending to a Navcom NCT or Trimble TSIP device, the first byte is
110 interpreted as the command ID and the rest as payload. When sending
111 to a Zodiac device, the first two bytes are used as a message ID of
112 type little-endian short, and the remainder as payload in byte pairs
113 interpreted as little-endian short. For all other supported binary
114 GPSes (notably including SiRF) the string is taken as the entire
115 message payload and wrapped with appropriate header, trailer and
116 checksum bytes.
117 The argument of the forcing option, -t, should be a string which is
119 contained in exactly one of the known driver names; for a list, do
120 gpsctl -l.
121 Forcing the device type behaves somewhat differently depending on
123 whether this tool is going through the daemon or not. In high-level
124 mode, if the device that daemon selects for you doesn’t match the
125 driver you specified, gpsctl exits with a warning. (This may be useful
126 in scripts.)
127 In low-level mode, if the device identifies as a Generic NMEA, use the
129 selected driver instead. This will be useful if you have a GPS device
130 of known type that is in NMEA mode and not responding to probes. (This
131 option was originally implemented for talking to SiRFStar I chips,
132 which don’t respond to the normal SiRF ID probe.)
133 If no options are given, the program will display a message identifying
135 the GPS type of the selected device and exit.
136 Reset (-r) operations must stand alone; others can be combined. gpsctl
138 will execute multiple options in this order: mode change (-b or -n)
139 first, speed changes (-s) second, cycle rate (-c) third and control
140 strings (-x) last.
141
143 By setting the environment variable GPSD_SHM_KEY, you can control the
144 key value used to designate the shared-memory segment removed with the
145 -R option. This will be useful mainly when isolating test instances of
146 gpsd from production ones.
147
149 gpsctl /dev/ttyUSB0
150 Attempt to identify the device on USB serial device 0. Time out
151 after the default number of seconds. Adding the -f will force
152 low-level access and suppress the normal complaint when this tool
153 can’t find a GPSD to work through.
154 gpsctl -f -n -s 9600 /dev/ttyUSB0
156 Use low-level operations (not going through a gpsd instance) to
157 switch a GPS to NMEA mode at 9600bps. The tool will identify the
158 GPS type itself.
159 gpsctl -x '\xb5\x62\x0a\x04\x00\x00\x0e\x34'
161 Send a request for UBX-MON-VER to a gpsd connected GNSS receiver.
162
164 SiRF GPSes can only be identified by the success of an attempt to flip
165 them into SiRF binary mode. Thus, the process of probing one of these
166 running in NMEA will change its behavior.
167 Baud rate and mode changes work in direct mode but are not reliable in
169 client mode. This will be fixed in a future release.
170
172 0
173 on success.
174 1
176 on failure
177
179 gpsd(8), gpsdctl(1), gps(1), ubxtool(1), zerk(1)
180
182 Project web site: https://gpsd.io/
183
185 This file is Copyright 2013 by the GPSD project
186 SPDX-License-Identifier: BSD-2-clause
187
189 Eric S. Raymond
190GPSD, Version 3.25 2023-01-10 GPSCTL(1)