diff options
Diffstat (limited to 'man/gpsctl.xml')
| -rw-r--r-- | man/gpsctl.xml | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/man/gpsctl.xml b/man/gpsctl.xml new file mode 100644 index 00000000..b0f9f6c0 --- /dev/null +++ b/man/gpsctl.xml @@ -0,0 +1,284 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 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>29 Oct 2006</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> + <arg choice='opt'>-h </arg> + <group> + <arg choice='plain'>-b</arg> + <arg choice='plain'>-n</arg> + </group> + <arg choice='opt'>-x <replaceable>control</replaceable></arg> + <arg choice='opt'>-e </arg> + <arg choice='opt'>-f </arg> + <arg choice='opt'>-l </arg> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='opt'>-t <replaceable>devicetype</replaceable></arg> + <arg choice='opt'>-R </arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-V </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 baudrate. 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>-b</term> +<listitem> +<para>Put the GPS into native (binary) mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-c</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>-e</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>-f</term> +<listitem> +<para>Force low-level access (not through the daemon).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-l</term> +<listitem> +<para>List a table showing which option switches can be applied +to which device types, and exit.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-n</term> +<listitem> +<para>Put GPS into NMEA mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-s</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>-t</term> +<listitem> +<para>Force the device type.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-x</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> + +<varlistentry> +<term>-T</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>-R</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>-h</term> +<listitem> +<para>Display program usage and exit.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-D</term> +<listitem> +<para>Set level of debug messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-V</term> +<listitem> +<para>Display program version and exit.</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 (-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.</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> |