|
- <?xml version="1.0" encoding="ISO-8859-1"?>
- <!--
- This file is Copyright 2010 by the GPSD project
- SPDX-License-Identifier: BSD-2-clause
- -->
- <!DOCTYPE refentry PUBLIC
- "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
- <refentry id='gpsctl.1'>
- <refentryinfo>
- <date>6 December 2020</date>
- </refentryinfo>
- <refmeta>
- <refentrytitle>gpsctl</refentrytitle>
- <manvolnum>1</manvolnum>
- <refmiscinfo class="source">The GPSD Project</refmiscinfo>
- <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
- </refmeta>
- <refnamediv id='name'>
- <refname>gpsctl</refname>
- <refpurpose>control the modes of a GPS</refpurpose>
- </refnamediv>
- <refsynopsisdiv id='synopsis'>
- <cmdsynopsis>
- <command>gpsctl</command>
- <group>
- <arg choice='plain'>-?</arg>
- <arg choice='plain'>--binary</arg>
- <arg choice='plain'>--nmea</arg>
- <arg choice='plain'>--reset</arg>
- </group>
- <arg choice='opt'>--debug <replaceable>LVL</replaceable>
- </arg>
- <arg choice='opt'>--direct </arg>
- <arg choice='opt'>--echo </arg>
- <arg choice='opt'>--help </arg>
- <arg choice='opt'>--list </arg>
- <arg choice='opt'>--rate </arg>
- <arg choice='opt'>--rmshm </arg>
- <arg choice='opt'>--rate <replaceable>rate</replaceable>
- </arg>
- <arg choice='opt'>--ship <replaceable>control</replaceable>
- </arg>
- <arg choice='opt'>--speed <replaceable>speed</replaceable>
- </arg>
- <arg choice='opt'>--timeout <replaceable>devicetype</replaceable>
- </arg>
- <arg choice='opt'>--version </arg>
- <group>
- <arg choice='plain'>-b</arg>
- <arg choice='plain'>-n</arg>
- <arg choice='plain'>-r</arg>
- </group>
- <arg choice='opt'>-D <replaceable>LVL</replaceable>
- </arg>
- <arg choice='opt'>-c <replaceable>rate</replaceable>
- </arg>
- <arg choice='opt'>-e </arg>
- <arg choice='opt'>-f </arg>
- <arg choice='opt'>-h </arg>
- <arg choice='opt'>-l </arg>
- <arg choice='opt'>-R </arg>
- <arg choice='opt'>-s <replaceable>speed</replaceable>
- </arg>
- <arg choice='opt'>-t <replaceable>devicetype</replaceable>
- </arg>
- <arg choice='opt'>-V </arg>
- <arg choice='opt'>-x <replaceable>control</replaceable>
- </arg>
- <arg choice='opt'>
- <replaceable>serial-port</replaceable>
- </arg>
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1 id='description'>
- <title>DESCRIPTION</title>
- <para>
- <application>gpsctl</application> 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.</para>
- <para>If you have only one GPS attached to your machine, and gpsd is
- running, it is not necessary to specify the device;
- <application>gpsctl</application> does its work through
- <application>gpsd</application>, which will locate it for you.</para>
- <para>When <application>gpsd</application> 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'.</para>
- <para>The program accepts the following options:</para>
- <variablelist remap='TP'>
- <varlistentry>
- <term>
- <option>-?</option>
- </term>
- <term>
- <option>-h</option>
- </term>
- <term>
- <option>--help</option>
- </term>
- <listitem>
- <para>Display program usage and exit.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-b</option>
- </term>
- <term>
- <option>--binary</option>
- </term>
- <listitem>
- <para>Put the GPS into native (binary) mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-c RATE</option>
- </term>
- <term>
- <option>--rate RATE</option>
- </term>
- <listitem>
- <para>Change the GPS's cycle time. Units are seconds. Note, most
- GPSes have a fixed cycle time of 1 second.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-D LVL</option>
- </term>
- <term>
- <option>--debug LVL</option>
- </term>
- <listitem>
- <para>Set level of debug messages.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-e</option>
- </term>
- <term>
- <option>--echo</option>
- </term>
- <listitem>
- <para>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 <option>-t</option> option without specifying a device. Note:
- the packet data for a binary prototype will be raw, not ASCII-ized in
- any way.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-f</option>
- </term>
- <term>
- <option>--force</option>
- </term>
- <listitem>
- <para>Force low-level access (not through the daemon).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-l</option>
- </term>
- <term>
- <option>--list</option>
- </term>
- <listitem>
- <para>List a table showing which option switches can be applied
- to which device types, and exit.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-n</option>
- </term>
- <term>
- <option>--nmea</option>
- </term>
- <listitem>
- <para>Put GPS into NMEA mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-r</option>
- </term>
- <term>
- <option>--reset</option>
- </term>
- <listitem>
- <para>Reset the GPS. Device port and type must be specified.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-R</option>
- </term>
- <term>
- <option>--rmshm</option>
- </term>
- <listitem>
- <para>Remove the GPSD shared-memory segment used for SHM export. This
- option will normally only be of interest to GPSD developers.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-s SPEED</option>
- </term>
- <term>
- <option>--speed SPEED</option>
- </term>
- <listitem>
- <para>Set the baud rate at which the GPS emits packets.</para>
- <para>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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-t TYPE</option>
- </term>
- <term>
- <option>--type TYPE</option>
- </term>
- <listitem>
- <para>Force the device type.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-T TIMEOUT</option>
- </term>
- <term>
- <option>--timeout TIMEOUT</option>
- </term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-V</option>
- </term>
- <term>
- <option>--version</option>
- </term>
- <listitem>
- <para>Display program version and exit.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-x STR</option>
- </term>
- <term>
- <option>--ship STR</option>
- </term>
- <listitem>
- <para>Send a specified control string to the GPS;
- <application>gpsctl</application> 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 <option>-f</option>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>The argument of the forcing option, <option>-t</option>, should be a
- string which is contained in exactly one of the known driver
- names; for a list, do <command>gpsctl -l</command>.</para>
- <para>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, <application>gpsctl</application> exits with
- a warning. (This may be useful in scripts.)</para>
- <para>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.)</para>
- <para>If no options are given, the program will display a message
- identifying the GPS type of the selected device and exit.</para>
- <para>Reset (<option>-r</option>) operations must stand alone; others can be combined.
- Multiple options will be executed in this order: mode changes (<option>-b</option> and
- -<option>n</option>) first, speed changes (<option>-s</option>) second, and control-string sends (<option>-c</option>)
- last.</para>
- </refsect1>
- <refsect1 id='environment'>
- <title>ENVIRONMENT VARIABLES</title>
- <para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>,
- 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 <application>gpsd</application> from
- production ones.</para>
- </refsect1>
- <refsect1 id='examples'>
- <title>EXAMPLES</title>
- <variablelist>
- <varlistentry>
- <term>
- <command>gpsctl /dev/ttyUSB0</command>
- </term>
- <listitem>
- <para>Attempt to identify the device on USB serial device 0. Time out
- after the default number of seconds. Adding the <option>-f</option> will
- force low-level access and suppress the normal complaint when this
- tool can't find a GPSD to work through.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>gpsctl -f -n -s 9600 /dev/ttyUSB0</term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1 id='bugs'>
- <title>BUGS</title>
- <para>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.</para>
- <para>Baud rate and mode changes work in direct mode but are not
- reliable in client mode. This will be fixed in a future release.</para>
- </refsect1>
- <refsect1 id='see_also'>
- <title>SEE ALSO</title>
- <para>
- <citerefentry>
- <refentrytitle>gpsd</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>gpsdctl</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>gps</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>libgps</refentrytitle>
- <manvolnum>3</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>libgpsmm</refentrytitle>
- <manvolnum>3</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>gpsprof</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>gpsfake</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>.
- </para>
- </refsect1>
- <refsect1 id='maintainer'>
- <title>AUTHOR</title>
- <para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para>
- </refsect1>
- </refentry>
|