gpsctl.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for details.
   5 -->
   6 <!DOCTYPE refentry PUBLIC
   7    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   8    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   9 <refentry id='gpsctl.1'>
  10 <refentryinfo><date>29 Oct 2006</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>gpsctl</refentrytitle>
  13 <manvolnum>1</manvolnum>
  14 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  15 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  16 </refmeta>
  17 <refnamediv id='name'>
  18 <refname>gpsctl</refname>
  19 <refpurpose>control the modes of a GPS</refpurpose>
  20 </refnamediv>
  21 <refsynopsisdiv id='synopsis'>
  22
  23 <cmdsynopsis>
  24   <command>gpsctl</command>
  25       <arg choice='opt'>-h </arg>
  26       <group>
  27         <arg choice='plain'>-b</arg>
  28         <arg choice='plain'>-n</arg>
  29       </group>
  30       <arg choice='opt'>-x <replaceable>control</replaceable></arg>
  31       <arg choice='opt'>-e </arg>
  32       <arg choice='opt'>-f </arg>
  33       <arg choice='opt'>-l </arg>
  34       <arg choice='opt'>-s <replaceable>speed</replaceable></arg>
  35       <arg choice='opt'>-t <replaceable>devicetype</replaceable></arg>
  36       <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  37       <arg choice='opt'>-V </arg>
  38       <arg choice='opt'><replaceable>serial-port</replaceable></arg>
  39 </cmdsynopsis>
  40 </refsynopsisdiv>
  41
  42 <refsect1 id='description'><title>DESCRIPTION</title>
  43
  44 <para><application>gpsctl</application> can switch a dual-mode GPS
  45 between NMEA and vendor-binary modes.  It can also be used to set the
  46 device baudrate.  Note:  Not all devices have these capabilities.</para>
  47
  48 <para>If you have only one GPS attached to your machine, and gpsd is
  49 running, it is not necessary to specify the device;
  50 <application>gpsctl</application> does its work through
  51 <application>gpsd</application>, which will locate it for you.</para>
  52
  53 <para>When <application>gpsd</application> is not running, the device
  54 specification is required, and you will almost certainly need to be
  55 running as root in order to have write access to the device.</para>
  56
  57 <para>The program accepts the following options:</para>
  58 <variablelist remap='TP'>
  59
  60 <varlistentry>
  61 <term>-b</term>
  62 <listitem>
  63 <para>Put the GPS into binary mode.  After the GPS resets itself, autobaud to
  64 the new speed.</para>
  65 </listitem>
  66 </varlistentry>
  67
  68 <varlistentry>
  69 <term>-c</term>
  70 <listitem>
  71 <para>Change the GPS's cycle time.  Units are seconds.  Note, most
  72 GPSes have a fixed cycle time of 1 second.</para>
  73 </listitem>
  74 </varlistentry>
  75
  76 <varlistentry>
  77 <term>-e</term>
  78 <listitem>
  79 <para>Generate the packet from any other arguments specified and ship
  80 it to standard output instead of the device. This switch can be used
  81 with the <option>-t</option> option without specifying a device. Note:
  82 the packet data for a binary prototype will be raw, not ASCII-ized in
  83 any way.</para>
  84 </listitem>
  85 </varlistentry>
  86
  87 <varlistentry>
  88 <term>-f</term>
  89 <listitem>
  90 <para>Force low-level access (not through the daemon).</para>
  91 </listitem>
  92 </varlistentry>
  93
  94 <varlistentry>
  95 <term>-l</term>
  96 <listitem>
  97 <para>List a table showing which option switches can be applied
  98 to which device types, and exit.</para>
  99 </listitem>
 100 </varlistentry>
 101
 102 <varlistentry>
 103 <term>-n</term>
 104 <listitem>
 105 <para>Put GPS into NMEA mode.  After the GPS resets itself autobaud to
 106 its new speed.</para>
 107 </listitem>
 108 </varlistentry>
 109
 110 <varlistentry>
 111 <term>-s</term>
 112 <listitem>
 113 <para>Set the baud rate at which the GPS emits packets.</para>
 114
 115 <para>Use this option with caution.  On USB and Bluetooth GPSes it is
 116 also possible for serial mode setting to fail either because the
 117 serial adaptor chip does not support non-8N1 modes or because the
 118 device firmware does not properly synchronize the serrial adaptor chip
 119 with the UART on the GPS chipset whjen the speed changes. These
 120 failures can hang your device, possibly requiring a GPS power cycle or (in
 121 extreme cases) physically disconnecting the NVRAM backup battery.</para>
 122 </listitem>
 123 </varlistentry>
 124
 125 <varlistentry>
 126 <term>-t</term>
 127 <listitem>
 128 <para>Force the device type.</para>
 129 </listitem>
 130 </varlistentry>
 131
 132 <varlistentry>
 133 <term>-x</term>
 134 <listitem>
 135 <para>Send a specified control string to the GPS;
 136 <application>gpsctl</application> will provide packet headers and
 137 trailers and checksum as appropriate for binary packet types, and
 138 whatever checksum and trailer is required for text packet types.  (You
 139 must include the leading $ for NMEA packets.) When sending to a UBX
 140 device, the first two bytes of the string supplied will become the
 141 message class and type, and the remainder the payload. When sending to
 142 a Navcom NCT or Trimble TSIP device, the first byte is interpreted as
 143 the command ID and the rest as payload. When sending to a Zodiac
 144 device, the first two bytes are used as a message ID of type
 145 little-endian short, and the remainder as payload in byte pairs
 146 interpreted as little-endian short. C-style backslash escapes in the
 147 string, notably \xNN for hex, will be interpreted; additionally, \e
 148 will be replaced with ESC. This switch implies
 149 <option>-f</option>.</para>
 150 </listitem>
 151 </varlistentry>
 152
 153 <varlistentry>
 154 <term>-T</term>
 155 <listitem>
 156 <para>Change the sampling timeout. Defaults to 4 seconds, which
 157 should always be sufficient to get a packet from a device emitting at
 158 the normal rate of 1 per second.</para>
 159 </listitem>
 160 </varlistentry>
 161
 162 <varlistentry>
 163 <term>-h</term>
 164 <listitem>
 165 <para>Display program usage and exit.</para>
 166 </listitem>
 167 </varlistentry>
 168
 169 <varlistentry>
 170 <term>-D</term>
 171 <listitem>
 172 <para>Set level of debug messages.</para>
 173 </listitem>
 174 </varlistentry>
 175
 176 <varlistentry>
 177 <term>-V</term>
 178 <listitem>
 179 <para>Display program version and exit.</para>
 180 </listitem>
 181 </varlistentry>
 182 </variablelist>
 183
 184 <para>The argument of the forcing option. <option>-t</option>, should be a
 185 string which should be contained in exactly one of the known driver
 186 names; for a list, do <command>gpsctl -l</command>.</para>
 187
 188 <para>Forcing the device type behaves somewhat differently depending
 189 on whether this tool is going through the daemon or not. In high-level
 190 mode, if the device that daemon selects for you doesn't match the
 191 driver you specified, <application>gpsctl</application> exits with
 192 a warning.  (This may be useful in scripts.)</para>
 193
 194 <para>In low-level mode, if the device identifies as a Generic NMEA,
 195 use the selected driver instead.  This will be useful if you have a
 196 GPS device of known type that is in NMEA mode and not responding to
 197 probes.  (This option was originally implemented for talking to
 198 SiRFStar I chips, which don't respond to the normal SiRF ID
 199 probe.)</para>
 200
 201 <para>If no options are given, the program will display a message
 202 identifying the GPS type of the selected device and exit.</para>
 203
 204 <para>Reset (-r) operations must stand alone; others can be combined.
 205 Multiple opations will be executed in tis order: mode changes (-b and
 206 -n) first, speed changes (-s) second, and control-string sends (-c)
 207 last.</para>
 208
 209 </refsect1>
 210
 211 <refsect1 id='examples'><title>EXAMPLES</title>
 212
 213 <variablelist>
 214 <varlistentry>
 215 <term><command>gpsctl /dev/ttyUSB0</command></term>
 216 <listitem>
 217 <para>Attempt to identify the device on USB serial device 0. Time out
 218 after the default number of seconds. Adding the <option>-f</option> will
 219 force low-level access and suppress the normal complaint when this
 220 tool can't find a GPSD to work through.</para>
 221 </listitem>
 222 </varlistentry>
 223
 224 <varlistentry>
 225 <term>gpsctl -f -n -s 9600 /dev/ttyUSB0</term>
 226 <listitem>
 227 <para>Use low-level operations (not going through a gpsd instance) to
 228 switch a GPS to NMEA mode at 9600bps.  The tool will identify the
 229 GPS type itself.</para>
 230 </listitem>
 231 </varlistentry>
 232 </variablelist>
 233
 234 </refsect1>
 235
 236 <refsect1 id='bugs'><title>BUGS</title>
 237
 238 <para>SiRF GPSes can only be identified by the success of an attempt
 239 to flip them into SiRF binary mode. Thus, the process of probing one of
 240 these running in NMEA will change its behavior.</para>
 241
 242 </refsect1>
 243
 244 <refsect1 id='see_also'><title>SEE ALSO</title>
 245 <para>
 246 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 247 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 248 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 249 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 250 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 251 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 252 </para>
 253 </refsect1>
 254
 255 <refsect1 id='maintainer'><title>AUTHOR</title>
 256
 257 <para>Eric S. Raymond <email>esr@thyrsus.com</email>.  There is a
 258 project page for <application>gpsd</application> <ulink
 259 url="http://gpsd.berlios.de/">here</ulink>.</para>
 260 </refsect1>
 261 </refentry>