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

NAME

6       gpsctl - control the modes of a GNSS receiver
7

SYNOPSIS

9       gpsctl [OPTIONS] [serial-port]
10
11       gpsctl -h
12
13       gpsctl -V
14

DESCRIPTION

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
20       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
24       When gpsd is running, gpsctl may be run as any user, or as root.
25
26       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
31       Running under sudo will cause some loss of functionality.
32

OPTIONS

34       The program accepts the following options:
35
36       -?, -h, --help
37           Display program usage and exit.
38
39       -b, --binary
40           Put the GNSS receiver into native (binary) mode.
41
42       -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
46       -D LVL, --debug LVL
47           Set level of debug messages.
48
49       -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
55       -f, --force
56           Force low-level access (not through the daemon).
57
58       -l, --list
59           List a table showing which option switches can be applied to which
60           device types, and exit.
61
62       -n, --nmea
63           Put the GNSS receiver into NMEA mode.
64
65       -r, --reset
66           Reset the GNSS receiver. Device port and type must be specified.
67
68       -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
72       -s SPEED, --speed SPEED
73           Set the baud rate at which the receiver emits packets.
74
75       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
83       -t TYPE, --type TYPE
84           Force the device type.
85
86       -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
91       -V, --version
92           Display program version and exit.
93
94       -x STR, --ship STR
95           Send a specified control string to the GPS, gpsctl will provide
96           packet headers and trailers and checksum as appropriate for binary
97           packet types, and whatever checksum and trailer is required for
98           text packet types. (You must include the leading $ for NMEA
99           packets.) When sending to a UBX device, the first two bytes of the
100           string supplied will become the message class and type, and the
101           remainder the payload. When sending to a Navcom NCT or Trimble TSIP
102           device, the first byte is interpreted as the command ID and the
103           rest as payload. When sending to a Zodiac device, the first two
104           bytes are used as a message ID of type little-endian short, and the
105           remainder as payload in byte pairs interpreted as little-endian
106           short. For all other supported binary GPSes (notably including
107           SiRF) the string is taken as the entire message payload and wrapped
108           with appropriate header, trailer and checksum bytes. C-style
109           backslash escapes in the string, notably \xNN for hex, will be
110           interpreted; additionally, \e will be replaced with ESC. This
111           switch implies -f.
112
113       The argument of the forcing option, -t, should be a string which is
114       contained in exactly one of the known driver names; for a list, do
115       gpsctl -l.
116
117       Forcing the device type behaves somewhat differently depending on
118       whether this tool is going through the daemon or not. In high-level
119       mode, if the device that daemon selects for you doesn’t match the
120       driver you specified, gpsctl exits with a warning. (This may be useful
121       in scripts.)
122
123       In low-level mode, if the device identifies as a Generic NMEA, use the
124       selected driver instead. This will be useful if you have a GPS device
125       of known type that is in NMEA mode and not responding to probes. (This
126       option was originally implemented for talking to SiRFStar I chips,
127       which don’t respond to the normal SiRF ID probe.)
128
129       If no options are given, the program will display a message identifying
130       the GPS type of the selected device and exit.
131
132       Reset (-r) operations must stand alone; others can be combined.
133       Multiple options will be executed in this order: mode changes (-b and
134       -n) first, speed changes (-s) second, and control-string sends (-c)
135       last.
136

ENVIRONMENT VARIABLES

138       By setting the environment variable GPSD_SHM_KEY, you can control the
139       key value used to designate the shared-memory segment removed with the
140       -R option. This will be useful mainly when isolating test instances of
141       gpsd from production ones.
142

EXAMPLES

144       gpsctl /dev/ttyUSB0
145           Attempt to identify the device on USB serial device 0. Time out
146           after the default number of seconds. Adding the -f will force
147           low-level access and suppress the normal complaint when this tool
148           can’t find a GPSD to work through.
149
150       gpsctl -f -n -s 9600 /dev/ttyUSB0
151           Use low-level operations (not going through a gpsd instance) to
152           switch a GPS to NMEA mode at 9600bps. The tool will identify the
153           GPS type itself.
154

BUGS

156       SiRF GPSes can only be identified by the success of an attempt to flip
157       them into SiRF binary mode. Thus, the process of probing one of these
158       running in NMEA will change its behavior.
159
160       Baud rate and mode changes work in direct mode but are not reliable in
161       client mode. This will be fixed in a future release.
162

RETURN VALUES

164       0
165           on success.
166
167       1
168           on failure
169

SEE ALSO

171       gpsd(8), gpsdctl(1), gps(1), ubxtool(1), zerk(1)
172

RESOURCES

174       Project web site: https://gpsd.io/
175

COPYING

177       This file is Copyright 2013 by the GPSD project
178       SPDX-License-Identifier: BSD-2-clause
179

AUTHOR

181       Eric S. Raymond
182
183
184
185GPSD, Version 3.24                2021-09-20                         GPSCTL(1)
Impressum