gpsctl(1)
NAME
gpsctl - control the modes of a GPS
SYNOPSIS
gpsctl [-h] [-b | -n] [-x control] [-e] [-f] [-l] [-s speed]
[-t devicetype] [-R] [-D debuglevel] [-V] [serial-port]
DESCRIPTION
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.
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:
-b
Put the GPS into native (binary) mode.
-c
Change the GPS's cycle time. Units are seconds. Note, most GPSes
have a fixed cycle time of 1 second.
-e
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 -t option without specifying a device. Note: the packet
data for a binary prototype will be raw, not ASCII-ized in any way.
-f
Force low-level access (not through the daemon).
-l
List a table showing which option switches can be applied to which
device types, and exit.
-n
Put GPS into NMEA mode.
-s
Set the baud rate at which the GPS emits packets.
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
Force the device type.
-x
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 \xNN for hex, will be
interpreted; additionally, \e will be replaced with ESC. This
switch implies -f.
-T
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.
-R
Remove the GPSD shared-memory segment used for SHM export. This
option will normally only be of interest to GPSD developers.
-h
Display program usage and exit.
-D
Set level of debug messages.
-V
Display program version and exit.
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.
ENVIRONMENT VARIABLES
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.
EXAMPLES
gpsctl /dev/ttyUSB0
Attempt to identify the device on USB serial device 0. Time out
after the default number of seconds. Adding the -f will force
low-level access and suppress the normal complaint when this tool
can't find a GPSD to work through.
gpsctl -f -n -s 9600 /dev/ttyUSB0
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.
BUGS
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.
SEE ALSO
gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1).
AUTHOR
Eric S. Raymond <[email protected]>.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
