'\" t
.\"     Title: gpsctl
.\"    Author: Eric S. Raymond
.\" Generator: Asciidoctor 2.0.18
.\"      Date: 2023-01-10
.\"    Manual: GPSD Documentation
.\"    Source: GPSD, Version 3.25
.\"  Language: English
.\"
.TH "GPSCTL" "1" "2023-01-10" "GPSD, Version 3.25" "GPSD Documentation"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
gpsctl \- control the modes of a GNSS receiver
.SH "SYNOPSIS"
.sp
\fBgpsctl\fP [OPTIONS] [serial\-port]
.sp
\fBgpsctl\fP \-h
.sp
\fBgpsctl\fP \-V
.SH "DESCRIPTION"
.sp
\fBgpsctl\fP can switch a dual\-mode GNSS receiver between NMEA and
vendor\-binary modes.  It can also be used to set the device baud
rate. Note: Not all devices have these capabilities.
.sp
If you have only one GNSS receiver attached to your machine, and \fBgpsd\fP
is running, it is not necessary to specify the device; \fBgpsctl\fP does its
work through \fBgpsd\fP, which will locate it for you.
.sp
When \fBgpsd\fP is running, \fBgpsctl\fP may be run as any user, or as root.
.sp
When \fBgpsd\fP is not running, the device specification is required, and you
will need to be running as root or be a member of the device\(cqs owning
group in order to have write access to the device. On many Unix variants
the owning group will be named \*(Aqdialout\*(Aq.
.sp
Running under \fBsudo\fP will cause some loss of functionality.
.SH "OPTIONS"
.sp
The program accepts the following options:
.sp
\fB\-?\fP, \fB\-h\fP, \fB\-\-help\fP
.RS 4
Display program usage and exit.
.RE
.sp
\fB\-b\fP, \fB\-\-binary\fP
.RS 4
Put the GNSS receiver into native (binary) mode.
.RE
.sp
\fB\-c RATE\fP, \fB\-\-rate RATE\fP
.RS 4
Change the receivers\(cqs cycle time. Units are seconds. Note, most
receivers have a fixed cycle time of 1 second.
.RE
.sp
\fB\-D LVL\fP, \fB\-\-debug LVL\fP
.RS 4
Set level of debug messages.
.RE
.sp
\fB\-e\fP, \fB\-\-echo\fP
.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\fP option without specifying a device. Note: the packet data
for a binary prototype will be raw, not ASCII\-ized in any way.
.RE
.sp
\fB\-f\fP, \fB\-\-force\fP
.RS 4
Force low\-level, direct, access (not through the daemon).
.RE
.sp
\fB\-l\fP, \fB\-\-list\fP
.RS 4
List a table showing which option switches can be applied to which
device types, and exit.
.RE
.sp
\fB\-n\fP, \fB\-\-nmea\fP
.RS 4
Put the GNSS receiver into NMEA mode.
.RE
.sp
\fB\-r\fP, \fB\-\-reset\fP
.RS 4
Reset the GNSS receiver. Device port and type must be specified.
.RE
.sp
\fB\-R\fP, \fB\-\-rmshm\fP
.RS 4
Remove the GPSD shared\-memory segment used for SHM export. This option
will normally only be of interest to GPSD developers.
.RE
.sp
\fB\-s SPEED\fP, \fB\-\-speed SPEED\fP
.RS 4
Set the baud rate at which the receiver emits packets.
.RE
.sp
Use the \fB\-s\fP 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.
.sp
\fB\-t TYPE\fP, \fB\-\-type TYPE\fP
.RS 4
Force the device type.
.RE
.sp
\fB\-T TIMEOUT\fP, \fB\-\-timeout TIMEOUT\fP
.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
.sp
\fB\-V\fP, \fB\-\-version\fP
.RS 4
Display program version and exit.
.RE
.sp
\fB\-x STR\fP, \fB\-\-ship STR\fP
.RS 4
Send the specified control string to the GNSS receiver. C\-style
backslash escapes in the string are decoded.  Use \(rsxNN for hex,
\(rse will be replaced with ESC.
.sp
.if n .RS 4
.nf
.fam C
In normal mode, through _gpsd_, the decoded string is passed through,
unchanged top _gpsd_ which in turns sends it to the receiver.  Headers,
checksums, and suffffices must be provided.
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
In low\-level, (direct) mode *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.
.fam
.fi
.if n .RE
.RE
.sp
The argument of the forcing option, \fB\-t\fP, should be a string which is
contained in exactly one of the known driver names; for a list, do
\fBgpsctl \-l\fP.
.sp
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\(cqt match the driver
you specified, \fBgpsctl\fP exits with a warning. (This may be useful in
scripts.)
.sp
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\(cqt respond to the normal SiRF ID probe.)
.sp
If no options are given, the program will display a message identifying
the GPS type of the selected device and exit.
.sp
Reset (\fB\-r\fP) operations must stand alone; others can be combined.
gpsctl will execute multiple options in this order: mode change (\-b
or \-n) first, speed changes (\-s) second, cycle rate (\-c) third and
control strings (\-x) last.
.SH "ENVIRONMENT VARIABLES"
.sp
By setting the environment variable \fBGPSD_SHM_KEY\fP, 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 \fBgpsd\fP from production ones.
.SH "EXAMPLES"
.sp
\fBgpsctl /dev/ttyUSB0\fP
.RS 4
Attempt to identify the device on USB serial device 0. Time out after
the default number of seconds. Adding the \fB\-f\fP will force low\-level
access and suppress the normal complaint when this tool can\(cqt find a
GPSD to work through.
.RE
.sp
\fBgpsctl \-f \-n \-s 9600 /dev/ttyUSB0\fP
.RS 4
Use low\-level operations (not going through a \fBgpsd\fP instance) to switch
a GPS to NMEA mode at 9600bps. The tool will identify the GPS type
itself.
.RE
.sp
\fBgpsctl \-x \*(Aq\(rsxb5\(rsx62\(rsx0a\(rsx04\(rsx00\(rsx00\(rsx0e\(rsx34\*(Aq\fP
.RS 4
Send a request for UBX\-MON\-VER to a \fIgpsd\fP connected GNSS receiver.
.RE
.SH "BUGS"
.sp
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.
.sp
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 "RETURN VALUES"
.sp
\fB0\fP
.RS 4
on success.
.RE
.sp
\fB1\fP
.RS 4
on failure
.RE
.SH "SEE ALSO"
.sp
\fBgpsd\fP(8), \fBgpsdctl\fP(1), \fBgps\fP(1), \fBubxtool\fP(1), \fBzerk\fP(1)
.SH "RESOURCES"
.sp
\fBProject web site:\fP \c
.URL "https://gpsd.io/" "" ""
.SH "COPYING"
.sp
This file is Copyright 2013 by the GPSD project
.br
SPDX\-License\-Identifier: BSD\-2\-clause
.SH "AUTHOR"
.sp
Eric S. Raymond