'\" t
.\" Title: gpsctl
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 29 Oct 2006
.\" Manual: GPSD Documentation
.\" Source: The GPSD Project
.\" Language: English
.\"
.TH "GPSCTL" "1" "29 Oct 2006" "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 [\-h] [\-b | \-n | \-r] [\-x\ \fIcontrol\fR] [\-e] [\-f] [\-l] [\-s\ \fIspeed\fR] [\-t\ \fIdevicetype\fR] [\-R] [\-D\ \fIdebuglevel\fR] [\-V] [\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 baudrate\&. 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
\-b
.RS 4
Put the GPS into native (binary) mode\&.
.RE
.PP
\-c
.RS 4
Change the GPS\*(Aqs cycle time\&. Units are seconds\&. Note, most GPSes have a fixed cycle time of 1 second\&.
.RE
.PP
\-e
.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
\-f
.RS 4
Force low\-level access (not through the daemon)\&.
.RE
.PP
\-l
.RS 4
List a table showing which option switches can be applied to which device types, and exit\&.
.RE
.PP
\-n
.RS 4
Put GPS into NMEA mode\&.
.RE
.PP
\-r
.RS 4
Reset the GPS\&. Device port and type must be specified\&.
.RE
.PP
\-s
.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
\-t
.RS 4
Force the device type\&.
.RE
.PP
\-x
.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
\-T
.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
\-R
.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
\-h
.RS 4
Display program usage and exit\&.
.RE
.PP
\-D
.RS 4
Set level of debug messages\&.
.RE
.PP
\-V
.RS 4
Display program version and exit\&.
.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 (\-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\&.
.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
\&.