'\" t
.\"     Title: gpsctl
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 6 December 2020
.\"    Manual: GPSD Documentation
.\"    Source: The GPSD Project
.\"  Language: English
.\"
.TH "GPSCTL" "1" "6 December 2020" "The GPSD Project" "GPSD Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gpsctl \- control the modes of a GPS
.SH "SYNOPSIS"
.HP \w'\fBgpsctl\fR\ 'u
\fBgpsctl\fR [\-? | \-\-binary | \-\-nmea | \-\-reset] [\-\-debug\ \fILVL\fR] [\-\-direct] [\-\-echo] [\-\-help] [\-\-list] [\-\-rate] [\-\-rmshm] [\-\-rate\ \fIrate\fR] [\-\-ship\ \fIcontrol\fR] [\-\-speed\ \fIspeed\fR] [\-\-timeout\ \fIdevicetype\fR] [\-\-version] [\-b | \-n | \-r] [\-D\ \fILVL\fR] [\-c\ \fIrate\fR] [\-e] [\-f] [\-h] [\-l] [\-R] [\-s\ \fIspeed\fR] [\-t\ \fIdevicetype\fR] [\-V] [\-x\ \fIcontrol\fR] [\fIserial\-port\fR]
.SH "DESCRIPTION"
.PP
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\&.
.PP
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\&.
.PP
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\*(Aqs owning group in order to have write access to the device\&. On many Unix variants the owning group will be named \*(Aqdialout\*(Aq\&.
.PP
The program accepts the following options:
.PP
\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
.RS 4
Display program usage and exit\&.
.RE
.PP
\fB\-b\fR, \fB\-\-binary\fR
.RS 4
Put the GPS into native (binary) mode\&.
.RE
.PP
\fB\-c RATE\fR, \fB\-\-rate RATE\fR
.RS 4
Change the GPS\*(Aqs cycle time\&. Units are seconds\&. Note, most GPSes have a fixed cycle time of 1 second\&.
.RE
.PP
\fB\-D LVL\fR, \fB\-\-debug LVL\fR
.RS 4
Set level of debug messages\&.
.RE
.PP
\fB\-e\fR, \fB\-\-echo\fR
.RS 4
Generate the packet from any other arguments specified and ship it to standard output instead of the device\&. This switch can be used with the
\fB\-t\fR
option without specifying a device\&. Note: the packet data for a binary prototype will be raw, not ASCII\-ized in any way\&.
.RE
.PP
\fB\-f\fR, \fB\-\-force\fR
.RS 4
Force low\-level access (not through the daemon)\&.
.RE
.PP
\fB\-l\fR, \fB\-\-list\fR
.RS 4
List a table showing which option switches can be applied to which device types, and exit\&.
.RE
.PP
\fB\-n\fR, \fB\-\-nmea\fR
.RS 4
Put GPS into NMEA mode\&.
.RE
.PP
\fB\-r\fR, \fB\-\-reset\fR
.RS 4
Reset the GPS\&. Device port and type must be specified\&.
.RE
.PP
\fB\-R\fR, \fB\-\-rmshm\fR
.RS 4
Remove the GPSD shared\-memory segment used for SHM export\&. This option will normally only be of interest to GPSD developers\&.
.RE
.PP
\fB\-s SPEED\fR, \fB\-\-speed SPEED\fR
.RS 4
Set the baud rate at which the GPS emits packets\&.
.sp
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\&.
.RE
.PP
\fB\-t TYPE\fR, \fB\-\-type TYPE\fR
.RS 4
Force the device type\&.
.RE
.PP
\fB\-T TIMEOUT\fR, \fB\-\-timeout TIMEOUT\fR
.RS 4
Change the sampling timeout\&. Defaults to 8 seconds, which should always be sufficient to get an identifying packet from a device emitting at the normal rate of 1 per second\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
Display program version and exit\&.
.RE
.PP
\fB\-x STR\fR, \fB\-\-ship STR\fR
.RS 4
Send a specified control string to the GPS;
gpsctl
will provide packet headers and trailers and checksum as appropriate for binary packet types, and whatever checksum and trailer is required for text packet types\&. (You must include the leading $ for NMEA packets\&.) When sending to a UBX device, the first two bytes of the string supplied will become the message class and type, and the remainder the payload\&. When sending to a Navcom NCT or Trimble TSIP device, the first byte is interpreted as the command ID and the rest as payload\&. When sending to a Zodiac device, the first two bytes are used as a message ID of type little\-endian short, and the remainder as payload in byte pairs interpreted as little\-endian short\&. For all other supported binary GPSes (notably including SiRF) the string is taken as the entire message payload and wrapped with appropriate header, trailer and checksum bytes\&. C\-style backslash escapes in the string, notably \exNN for hex, will be interpreted; additionally, \ee will be replaced with ESC\&. This switch implies
\fB\-f\fR\&.
.RE
.PP
The argument of the forcing option,
\fB\-t\fR, should be a string which is contained in exactly one of the known driver names; for a list, do
\fBgpsctl \-l\fR\&.
.PP
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\*(Aqt match the driver you specified,
gpsctl
exits with a warning\&. (This may be useful in scripts\&.)
.PP
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\*(Aqt respond to the normal SiRF ID probe\&.)
.PP
If no options are given, the program will display a message identifying the GPS type of the selected device and exit\&.
.PP
Reset (\fB\-r\fR) operations must stand alone; others can be combined\&. Multiple options will be executed in this order: mode changes (\fB\-b\fR
and \-\fBn\fR) first, speed changes (\fB\-s\fR) second, and control\-string sends (\fB\-c\fR) last\&.
.SH "ENVIRONMENT VARIABLES"
.PP
By setting the environment variable
\fBGPSD_SHM_KEY\fR, 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\&.
.SH "EXAMPLES"
.PP
\fBgpsctl /dev/ttyUSB0\fR
.RS 4
Attempt to identify the device on USB serial device 0\&. Time out after the default number of seconds\&. Adding the
\fB\-f\fR
will force low\-level access and suppress the normal complaint when this tool can\*(Aqt find a GPSD to work through\&.
.RE
.PP
gpsctl \-f \-n \-s 9600 /dev/ttyUSB0
.RS 4
Use low\-level operations (not going through a gpsd instance) to switch a GPS to NMEA mode at 9600bps\&. The tool will identify the GPS type itself\&.
.RE
.SH "BUGS"
.PP
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\&.
.PP
Baud rate and mode changes work in direct mode but are not reliable in client mode\&. This will be fixed in a future release\&.
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8),
\fBgpsdctl\fR(8),
\fBgps\fR(1),
\fBlibgps\fR(3),
\fBlibgpsmm\fR(3),
\fBgpsprof\fR(1),
\fBgpsfake\fR(1)\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
<esr@thyrsus\&.com>\&.