gpsctl - control the modes of a GPS
gpsctl [-? | --binary | --nmea | --reset] [--debug LVL] [--direct] [--echo] [--help] [--list] [--rate] [--rmshm] [--rate rate] [--ship control] [--speed speed] [--timeout devicetype] [--version] [-b | -n | -r] [-D LVL] [-c rate] [-e] [-f] [-h] [-l] [-R] [-s speed] [-t devicetype] [-V] [-x control] [serial-port]
gpsctl can switch a dual-mode GPS between NMEA and vendor-binary modes. It can also be used to set the device baud rate. Note: Not all devices have these capabilities.
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.
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's owning group in order to have write access to the device. On many Unix variants the owning group will be named 'dialout'.
The program accepts the following options:
-?, -h, --help
-c RATE, --rate RATE
-D LVL, --debug LVL
-s SPEED, --speed SPEED
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.
-t TYPE, --type TYPE
-T TIMEOUT, --timeout TIMEOUT
-x STR, --ship STR
The argument of the forcing option, -t, should be a string which is contained in exactly one of the known driver names; for a list, do gpsctl -l.
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't match the driver you specified, gpsctl exits with a warning. (This may be useful in scripts.)
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't respond to the normal SiRF ID probe.)
If no options are given, the program will display a message identifying the GPS type of the selected device and exit.
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.
By setting the environment variable GPSD_SHM_KEY, 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.
gpsctl -f -n -s 9600 /dev/ttyUSB0
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.
Baud rate and mode changes work in direct mode but are not reliable in client mode. This will be fixed in a future release.
Eric S. Raymond <email@example.com>.
|6 December 2020||The GPSD Project|