gpsd/man/ubxtool.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright 2018 by the GPSD project
BSD terms apply: see the file COPYING in the distribution root for details.
-->
<!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='ubxtool.1'>
 <refentryinfo>
  <date>30 March 2020</date>
 </refentryinfo>
 <refmeta>
  <refentrytitle>ubxtool</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
 </refmeta>
 <refnamediv id='name'>
  <refname>ubxtool</refname>
  <refpurpose>u-blox tool</refpurpose>
 </refnamediv>
 <refsynopsisdiv id='synopsis'>
  <cmdsynopsis>
   <command>ubxtool</command>
   <arg choice='opt'>-? </arg>
   <arg choice='opt'>-c <replaceable>command</replaceable> </arg>
   <arg choice='opt'>-d <replaceable>disable</replaceable> </arg>
   <arg choice='opt'>-e <replaceable>enable</replaceable> </arg>
   <arg choice='opt'>-f <replaceable>file/device</replaceable> </arg>
   <arg choice='opt'>-g <replaceable>item,layer,position,end</replaceable>
   </arg>
   <arg choice='opt'>-h </arg>
   <arg choice='opt'>-i <replaceable>port</replaceable></arg>
   <arg choice='opt'>-P <replaceable>protver</replaceable></arg>
   <arg choice='opt'>-p <replaceable>preset</replaceable></arg>
   <arg choice='opt'>-R <replaceable>rawfile</replaceable></arg>
   <arg choice='opt'>-r </arg>
   <arg choice='opt'>-S <replaceable>setspeed</replaceable></arg>
   <arg choice='opt'>-s <replaceable>speed</replaceable></arg>
   <arg choice='opt'>-t </arg>
   <arg choice='opt'>-V </arg>
   <arg choice='opt'>-v <replaceable>verbosity</replaceable></arg>
   <arg choice='opt'>-w <replaceable>wait</replaceable></arg>
   <arg choice='opt'>-x <replaceable>item,layers</replaceable></arg>
   <arg choice='opt'>-z <replaceable>item,val,layers</replaceable></arg>
   <arg choice='opt'>[server[:port[:device]]]</arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1 id='description'>
  <title>DESCRIPTION</title>
  <para>
   <application>ubxtool</application> is a tool for u-blox GPS.
If you do not have a u-blox GPS then can stop reading now.</para>
  <para>This tool operates with your u-blox GPS at a very low level.
To understand <application>ubxtool</application> you must first be familiar
with your u-blox GPS and the documentation for the u-blox binary protocol.
The u-blox protocol varies greatly depending on GPS model and firmware
revision.  Use the u-blox documentation for your model and firmware.
</para>
  <para>
   <application>ubxtool</application> can decode common u-blox binary
 messages, poll the GPS status, enable and disable GPS features, and send user
generated commands to the GPS.  It can read binary messages from a file.  It
can read and write directly through a serial device, or through a
running gpsd instance.</para>
 </refsect1>
 <refsect1 id='options'>
  <title>OPTIONS</title>
  <para>The program accepts the following options:</para>
  <variablelist remap='TP'>
   <varlistentry>
    <term>-?</term>
    <listitem>
     <para>Makes <application>ubxtool</application> print
a usage message and exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-c COMMAND</term>
    <listitem>
     <para>Send a command to the GPS.  Accepts one parameter, COMMAND,
a comma-separated list of hexadecimal bytes specifying the class, the ID,
and any needed payload.  The header, length, and checksum are added automatically.
</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-d OPTION</term>
    <listitem>
     <para>Disable an option in the GPS.  Accepts one parameter, OPTION,
the option to disable.
</para>
     <variablelist>
      <varlistentry>
       <term>BEIDOU</term>
       <listitem>
        <para>Disable use of the BeiDou (COMPASS) constellation.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>BINARY</term>
       <listitem>
        <para>Disable sending of the basic binary messages.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>ECEF</term>
       <listitem>
        <para>Disable sending of ECEF binary messages.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>GALILEO</term>
       <listitem>
        <para>Disable use of the GALILEO constellation.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>GLONASS</term>
       <listitem>
        <para>Disable use of the GLONASS constellation.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>GPS</term>
       <listitem>
        <para>Disable use of the GPS and QZSS constellations.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>NED</term>
       <listitem>
        <para>Disable sending of NED binary messages.  UBX-NAV-VELNED
and UBX-NAV-RELPOSNED.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>NMEA</term>
       <listitem>
        <para>Disable sending basic NMEA messages.  The messages are
GBS, GGA, GSA, GGL, GST, GSV, RMC, VTG, and ZDA.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>PPS</term>
       <listitem>
        <para>Disable TIMEPULSE 0.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>RAWX</term>
       <listitem>
        <para>Disable sending of the UBX-RXM-RAWX messages.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>SBAS</term>
       <listitem>
        <para>Disable use of the SBAS constellation.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>SFRBX</term>
       <listitem>
        <para>Disable use of the SFRBX messages.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>SURVEYIN</term>
       <listitem>
        <para>Disable survey-in mode with TMODE2.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>TP</term>
       <listitem>
        <para>Disable sending UBX-TIM-TP.</para>
       </listitem>
      </varlistentry>
     </variablelist>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-e OPTION</term>
    <listitem>
     <para>Enable an option in the GPS.  Accepts one parameter, OPTION,
the option to enable.  -e accepts the same OPTIONs as -d, except the action
is to enable the option.
</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-f FILE</term>
    <listitem>
     <para>Connect to a file or device.  Accepts one parameter, FILE,
the file or device to open.   Files are opened read-only.  Character
devices are opened read/write, unless the -r parameter is given.
Requires the pyserial module.
</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-g ITEM,LAYER,POSITION,END</term>
    <listitem>
     <para>Get the value of ITEM from LAYER, starting at POSITION, up
to END key/value pairs (UBX-CFG-VALGET).  All parameters past ITEM are
optional and decimal.  If LAYER is absent, then layers 0, 1, 2
and 7 are all requested.  See the section on CONFIGURATION ITEMS</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-h</term>
    <listitem>
     <para>Makes <application>ubxtool</application> print
a usage message and exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-i port</term>
    <listitem>
     <para>Specifies port ID # (interface) for port-related commands.
</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-P protver</term>
    <listitem>
     <para>Sets the protocol version to use for sending commands.
Minimum 10 (ublox 5).  Use "ubxtool -p MON-VER" to see the version your
receiver supports.  Many newer u-blox receivers will fail silently or oddly
if this is not set correctly.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-p PRESET</term>
    <listitem>
     <para>Send a preset command the GPS.  Usually accepts one parameter,
PRESET, the name of the command to send.  A few PRESETS, like LOG-FINDTIME,
accept additional comma separated parameters.  More than one -p may be used.
</para>
<para> Only the common PRESETS are shown here.  To see the full list,
including optional parameters, run "ubxtool -h -v 2".
</para>
     <variablelist>
      <varlistentry>
       <term>COLDBOOT</term>
       <listitem>
        <para>Coldboot the GPS (UBX-CFG-RST).</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>HOTBOOT</term>
       <listitem>
        <para>Hotboot the GPS (UBX-CFG-RST).</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>MODEL,model</term>
       <listitem>
        <para>Configure the Dynamic Platform Model to model. (UBX-CFG-NAV5).
Model is the decimal number of the desired mode.
</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>PMS</term>
       <listitem>
        <para>Set power management settings (UBX-CFG-PMS).
"PMS,pow" where pow is powerSetupValue.</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>RATE</term>
       <listitem>
        <para>Set measurement and nav rate (UBX-CFG-RATE).
"RATE,meas,nav" meas is the measRate in milli seconds. The
nav argument is the navRate in cycles and defaults to 1</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>RESET</term>
       <listitem>
        <para>Reset configuration to defaults (UBX-CFG-CFG).</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>SAVE</term>
       <listitem>
        <para>Save current configuration (UBX-CFG-CFG).</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>MON-RESETODO</term>
       <listitem>
        <para>Reset the odometer (UBX-MON-RESETODO).</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>MON-VER</term>
       <listitem>
        <para>Poll GPS version (UBX-MON-VER).</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>WARMBOOT</term>
       <listitem>
        <para>Warmboot the GPS (UBX-CFG-RST).</para>
       </listitem>
      </varlistentry>
     </variablelist>
     <para>Most PRESET parameters are simple poll
commands.  They merely poll the GPS to respond with the associated
message.  For example "ubxtool -p CFG-GNSS" asks the GPS to respond with
a UBX-CFG-GNSS message describing the current GNSS configuration.
Increase the verbosity of the output by adding the "-v 2" or "-v 3"
options.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-R RAW</term>
    <listitem>
     <para>Save all raw serial data received from the GPS into the
     file RAW.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-r</term>
    <listitem>
     <para>Read only.  Do not send anything to the GPS.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-S SPEED</term>
    <listitem>
     <para>Set the GPS serial port speed to SPEED bps.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-s SPEED</term>
    <listitem>
     <para>Set local serial port speed to SPEED bps. Default 9,600 bps.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-t</term>
    <listitem>
     <para>Timestamp decoded messages with seconds since the epoch.  Use it
twice and also get UTC time.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-V</term>
    <listitem>
     <para>Print <application>ubxtool</application> version and exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-v VERBOSITY</term>
    <listitem>
     <para>Set verbosity level to VERBOSITY.  Verbosity can be from 0
     (very quiet), 2 (decode messages), to 4 (very noisy).  Default 1.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-w WAIT</term>
    <listitem>
     <para>Wait for WAIT seconds before exiting.  Default 2 seconds.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-x ITEM,LAYERS</term>
    <listitem>
     <para>Delete the value of ITEM name from LAYERS.  The bit map LAYERS is
optional.  By default, delete in both the BBR and FLASH layers in the
receiver (UBX_CFG-VALDEL).  Returning to the reciver default for that
item.  See the section on CONFIGURATION ITEMS</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>-z ITEM,VAL,LAYERS</term>
    <listitem>
     <para>Set the value of ITEM name to VAL in LAYERS in the GPS
(UBX-CFG-VALSET).  VAL and the bit mask LAYERS are decimal.  ",LAYERS"
is optional.  The default LAYERS are RAM and FLASH See the section on
CONFIGURATION ITEMS</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>[server[:port[:device]]]</term>
    <listitem>
     <para>
       By default, <application>ubxtool</application> collects data
       from all compatible devices on localhost, using the default GPSD
       port 2947. An optional argument may specify a server to get data
       from. A colon-separated suffix is taken as a port number. If
       there is a second colon-separated suffix, that is taken as a
       specific device name to be watched. Further details on the
<citerefentry>
       <refentrytitle>gps</refentrytitle>
       <manvolnum>1</manvolnum>
      </citerefentry> man page.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1 id='configitems'>
  <title>CONFIGURATION ITEMS</title>
  <para>Configuring u-blox GPS with the traditional configuration
messages is fraught with problems.  Many configuration messages
interact in odd ways.  Something as simple as changing the serial
port speed requires you to read the current configuration using
UBX-CFG-PRT for the proper port, merging in the change, the
writing back the changed UBX-CFG-PRT message.  Or just guessing
at the current configuration and overwriting it all.</para>
  <para>The u-blox 9 series, protocol version 27+, tries, but does
not completely succeed, to solve the problem with Configuration
Items.  If your GPS does not support protocol version 27+, then
this section does not apply to you.</para>
  <para>Most of the configuration variables in the GPS have been
assigned a 32-bit Key ID.
Each Key references one specific value.
A typical receiver may have over 1,100 Key IDs.
Each Key ID has been assigned a Key Name.
Most of the Key Names are documented by u-blox and supported by ubxtool.
To see all the Key Name understood by ubxtool do: "ubxtool -h -v 3".
</para>

  <para>To get the value related to an item, use "-g ITEM".</para>
  <para>To reset the value related to an item to it default value, use
"-x ITEM".</para>
  <para>To set an ITEM name to a value, use "-z ITEM,VAL".</para>
  <para>If you only want to set an ITEM in one layer, use "-z ITEM,VAL,LAYER".
  </para>
  <para>See the EXAMPLES section for concrete examples.</para>
 </refsect1>
 <refsect1 id='examples'>
  <title>EXAMPLES</title>
  <para>
All examples assume that UBXOPTS is set with the protocol version of
your receiver.  Be sure to replace the "-P 18" with your correct
prototype version.
<programlisting>
export UBXOPTS="-P 18"
</programlisting>
  </para>
  <para>
Dump configuration and status of the GNSS recceiver.  The "-w 4" is
to provide extra time for the operations to complete. 
<programlisting>
ubxtool -p CONFIG -p STATUS -w 4 -v 2
</programlisting>
  </para>
  <para>
Decode raw log file:
<programlisting>
ubxtool -r -f ublox-neo-m8n.log
</programlisting>
  </para>
  <para>
Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:
<programlisting>
ubxtool -S 230400 -f /dev/ttyAMA0
</programlisting>
  </para>
  <para>
Watch entire GPS reset cycle, include $GPTXT messages:
<programlisting>
ubxtool -p COLDBOOT -w 20 -v 2
</programlisting>
  </para>
  <para>
Poll Enabled Constellations:
<programlisting>
ubxtool -p CFG-GNSS
</programlisting>
Dump gpsd data from a remote server named x.example.com:
<programlisting>
ubxtool -w 5 x.example.com
</programlisting>
  </para>
   <refsect2>
   <title>Version 27+ examples</title>
   <para>The following examples require a GPS supporting protocol 27 or
   greater.  Be sure to set your protocol version first:
    <programlisting>
    export UBXOPTS="-P 32"
    </programlisting>
   </para>
   <para>To check the current dynamic model, change it to 6 (AIR1, Airborne
   with &lt;1g acceleration), revert to the default setting, and verify the
   faults was restored.
<programlisting>
$ ubxtool -g CFG-NAVSPG-DYNMODEL
[...]
UBX-CFG-VALGET:
 version 1 layer 0 reserved 0,0
  layers (ram)
    item CFG-NAVSPG-DYNMODEL/0x20110021 val 2
[...]
$ ubxtool -z CFG-NAVSPG-DYNMODEL,6
[...]
UBX-ACK-ACK:
 ACK to Class x6 (CFG) ID x8a (VALSET)
[...]
$ ubxtool -g CFG-NAVSPG-DYNMODEL
[...]
UBX-CFG-VALGET:
 version 1 layer 0 reserved 0,0
  layers (ram)
    item CFG-NAVSPG-DYNMODEL/0x20110021 val 6
[...]
$ ubxtool -x CFG-NAVSPG-DYNMODEL
[...]
UBX-ACK-ACK:
 ACK to Class x6 (CFG) ID x8c (VALDEL)
[...]
$ ubxtool -g CFG-NAVSPG-DYNMODEL
[...]
UBX-CFG-VALGET:
 version 1 layer 0 reserved 0,0
  layers (ram)
    item CFG-NAVSPG-DYNMODEL/0x20110021 val 6
</programlisting>
   </para>
   <para>Notice that the current DYNMODEL stayed at 6 (AIR1).  The
   "-x" only affects the saved setting, not the current setting.  To
   change the current setting you must set it with "-z".</para>
   <para>Getting all the Configuration Items in a group one by one
could be very tedious.  VAL-GET allows you to wild card the item
number and dump all the items in a group.  To get all the CFG-TP
items in ram, the currently active ones, you can do this:
<programlisting>
$ ubxtool -g CFG-TP,0
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-TP-TP1_ENA/0x10050007 val 1
    item CFG-TP-SYNC_GNSS_TP1/0x10050008 val 1
    item CFG-TP-USE_LOCKED_TP1/0x10050009 val 1
[...]
</programlisting>
   </para>
   <para>The truly masochistic can dump all the Configuration Items
by wildcarding the group.  Dumping all 1,000+ of them, 64 at a time, could
still be tedious.  The -g parameter optionally allows you to specify the
starting position to get from, as well as the ending position.  To get
all the known, and unknown, items supported by the receiver that are
currently in ram:
<programlisting>
$ ubxtool -g CFG,0,0,1200 | fgrep "item CFG-"
    item CFG-1-1/0x10010001 val 0
    item CFG-1-1/0x10010101 val 0
    item CFG-4-1/0x10040001 val 1
    item CFG-4-2/0x10040002 val 0
    item CFG-4-3/0x10040003 val 0
    item CFG-4-4/0x10040004 val 0
    item CFG-4-9/0x10040009 val 0
    item CFG-TP-TP1_ENA/0x10050007 val 1
    item CFG-TP-SYNC_GNSS_TP1/0x10050008 val 1
[...]
</programlisting>
   </para>
   <para>Changing <parameter>CFG,0,0,1200</parameter> to
   <parameter>CFG,7,0,1200</parameter> would instead dump all the
configuration defaults, from the Default layer (7).</para>
   </refsect2>
 </refsect1>
 <refsect1 id='environment'>
  <title>ENVIRONMENT</title>
  <para>Options can be placed in the UBXOPTS environment variable.
UBXOPTS is processed before the CLI options.</para>
 </refsect1>
 <refsect1 id='see_also'>
  <title>SEE ALSO</title>
  <para>
   <application>ubxtool</application> is written to conform to the official
u-blox documentation for the u-blox binary protocol.
<ulink url="https://www.u-blox.com/en/product-resources"></ulink></para>
  <para>
   <citerefentry>
    <refentrytitle>cgps</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
   <citerefentry>
    <refentrytitle>gpscat</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
   <citerefentry>
    <refentrytitle>gpsctl</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
   <citerefentry>
    <refentrytitle>gpsfake</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
   <citerefentry>
    <refentrytitle>xgps</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
   <citerefentry>
    <refentrytitle>gpsd</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>,
</para>
 </refsect1>
 <refsect1 id='maintainer'>
  <title>AUTHOR</title>
  <para>Gary E. Miller<email>gem@rellim.com</email>
  </para>
 </refsect1>
</refentry>