gpsd/man/ubxtool.adoc

= ubxtool(1)
Gary E. Miller <gem@rellim.com>
:author: Gary E. Miller
:date: 25 February 2021
:email: <gem@rellim.com.>
:keywords: gps, gpsd, ubxtool, u-blox
:manmanual: GPSD Documentation
:mansource: GPSD, Version {gpsdver}
:robots: index,follow
:sectlinks:
:toc: macro
:type: manpage
:webfonts!:

include::../www/inc-menu.adoc[]

== NAME

ubxtool - u-blox tool

== SYNOPSIS

*ubxtool* [OPTIONS} [server[:port[:device]]]

*ubxtool* -h

*ubxtool* -V

== DESCRIPTION

*ubxtool* is a tool for u-blox GPS. If you do not have a u-blox GPS then
can stop reading now.

This tool operates with your u-blox GPS at a very low level. To
understand *ubxtool* 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.

*ubxtool* 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.

*ubxtool* does not require root privileges, except maybe to access the
serial port in direct mode.  It will run fine as root.  Running under
sudo will cause loss of functionality.

== OPTIONS

The program accepts the following options:

*-?*, *-h*, *--help*::
  Makes *ubxtool* print a usage message and exit. Use with *-v 2* to see
  all enable/disable and preset values. Use with *-v 3* to
  additionally see all configuration items (long).
*-c COMMAND*, *--command COMMAND*::
  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.
*--device DEVICE*::
  The DEVICE on the *gpsd* to connect to. Defaults to all.
*-d OPTION*, *--disable OPTION*::
  Disable an option in the GPS. Accepts one parameter, OPTION, the
  option to disable. Run "ubxtool -h -v 2" to see all possible OPTIONs. A few
  possible OPTIONs are:

BEIDOU;;
Disable use of the BeiDou (COMPASS) constellation.
BINARY;;
Disable sending of the basic binary messages.
ECEF;;
Disable sending of ECEF binary messages.
GALILEO;;
Disable use of the GALILEO constellation.
GLONASS;;
Disable use of the GLONASS constellation.
GPS;;
Disable use of the GPS and QZSS constellations.
NED;;
Disable sending of NED binary messages. UBX-NAV-VELNED and
UBX-NAV-RELPOSNED.
NMEA;;
Disable sending basic NMEA messages. The messages are GBS, GGA, GSA,
GGL, GST, GSV, RMC, VTG, and ZDA.
PPS;;
Disable TIMEPULSE 0.
RAWX;;
Disable sending of the UBX-RXM-RAWX messages.
SBAS;;
Disable use of the SBAS constellation.
SFRBX;;
Disable use of the SFRBX messages.
SURVEYIN;;
Disable survey-in mode with TMODE2.
TP;;
Disable sending UBX-TIM-TP.

*-e OPTION*, *--enable OPTION*::
  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.
*-f FILE*, *--file FILE*::
  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.
*-g ITEM,LAYER,POSITION,END*, *--getitem ITEM,LAYER,POSITION,END*::
  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
*--host HOST*::
  Connect to the *gpsd* on HOST (server). Defaults to localhost.
*-i port*, *--portid port*::
  Specifies port ID # (interface) for port-related commands such as
  UBX_CFG-PRT.
*-p PRESET*, *--preset PRESET*::
  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.

Only the common PRESETS are shown here. To see the full list,
including optional parameters, run "ubxtool -h -v 2".

COLDBOOT;;
Coldboot the GPS (UBX-CFG-RST).
HOTBOOT;;
Hotboot the GPS (UBX-CFG-RST).
MODEL,model;;
Configure the Dynamic Platform Model to model. (UBX-CFG-NAV5). Model
is the decimal number of the desired mode.
PMS;;
Set power management settings (UBX-CFG-PMS). "PMS,pow" where pow is
powerSetupValue.
RATE;;
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.
RESET;;
Reset configuration to defaults (UBX-CFG-CFG).
SAVE;;
Save current configuration (UBX-CFG-CFG).
MON-RESETODO;;
Reset the odometer (UBX-MON-RESETODO).
MON-VER;;
Poll GPS version (UBX-MON-VER).
WARMBOOT;;
Warmboot the GPS (UBX-CFG-RST).

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.

*--port PORT*::
  Use PORT to connect to *gpsd*. Defaults to 2947.
*-P protver*, *--protver protver*::
  Sets the protocol version to use for sending commands. Minimum 6
  (Antaris 4). 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. Default 10 (u-blox 5).
*-r*, *-readonly*::
  Read only. Do not send anything to the GPS.
*-R RAW*, *--rawfile RAW*::
  Save all raw serial data received from the GPS into the file RAW.
*-s SPEED*, *--inspeed SPEED*::
  Set local serial port speed to SPEED bps. Default 9,600 bps.
*-S SPEED*, *--setspeed SPEED*::
  Set the GPS serial port speed to SPEED bps.
*-t*, *--timestamp*::
  Timestamp decoded messages with seconds since the epoch. Use it twice
  and also get UTC time.
*-v VERBOSITY*, *--verbosity VERBOSITY*::
  Set verbosity level to VERBOSITY. Verbosity can be from 0 (very
  quiet), 2 (decode messages), to 4 (very noisy). Default 1.
*-V*, *--version*::
  Print *ubxtool* version and exit.
*-w WAIT*, *--wait WAIT*::
  Wait for WAIT seconds before exiting. Default 2 seconds.
*-x ITEM,LAYERS*, *--delitem ITEM,LAYERS*::
  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
*-z ITEM,VAL,LAYERS*, *--setitem ITEM,VAL,LAYERS*::
  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

== ARGUMENTS

By default, clients collect data from the local *gpsd* daemon running
on localhost, using the default GPSD port 2947. The optional argument
to any client may override this behavior: *[server[:port[:device]]]*

For further explanation, and examples, see the *ARGUMENTS* section in
the *gps*(1) man page

[[configitems]]
== CONFIGURATION ITEMS

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.

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.

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* run: "ubxtool
-h -v 3".

To get the value related to an item, use "-g ITEM".

To reset the value related to an item to it default value, use "-x
ITEM".

To set an ITEM name to a value, use "-z ITEM,VAL".

If you only want to set an ITEM in one layer, use "-z ITEM,VAL,LAYER".

See the EXAMPLES section for concrete examples.

== EXAMPLES

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.

----
export UBXOPTS="-P 18"
----

Dump configuration and status of the GNSS recceiver. The "-w 4" is to
provide extra time for the operations to complete.

----
ubxtool -p CONFIG -p STATUS -w 4 -v 2
----

Decode raw log file:

----
ubxtool -r -f ublox-neo-m8n.log
----

Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:

----
ubxtool -S 230400 -f /dev/ttyAMA0
----

Watch entire GPS reset cycle, include $GPTXT messages:

----
ubxtool -p COLDBOOT -w 20 -v 2
----

Poll Enabled Constellations:

----
ubxtool -p CFG-GNSS
----

Dump *gpsd* data from a remote server named x.example.com:

----
ubxtool -w 5 x.example.com
----

=== CFG-TP5

Some of the "-p" and "--preset" commands can take multiple options.  One of
these is "--preset CFG-TP5".

Synopsis:
----
-p CFG-TP5,[tpIdx = 0],[antCableDelay = 2],[rfGroupDelay = 0],[freqPeriod = 1000000],[freqPeriodLock = 1000000],[pulseLenRatio = 0],[pulseLenRatioLock = 100000],[userConfigDelay = 0],[flags = 0x77]
----

Leave a positional parameter empty for it to take the default value.

To set the pulse period to 0.25 s and its length to 0.1 s:

----
$ ubxtool -p CFG-TP5,,,,250000,250000,100000,100000
----

To set the pulse period to 0.1 s and length to 0.1 s in the presence of lock:

----
$ ubxtool -p CFG-TP5,,,,,100000,,50000
----

=== Version 27+ examples

The following examples require a GPS supporting protocol 27 or greater.
Be sure to set your protocol version first:

----
    export UBXOPTS="-P 32"
----

To check the current dynamic model, change it to 6 (AIR1, Airborne with
<1g acceleration), revert to the default setting, and verify the faults
was restored.

----
$ 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
----

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".

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:

----
$ 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
[...]
----

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:

----
$ 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
[...]
----

Changing +CFG,0,0,1200+ to +CFG,7,0,1200+ would instead dump all the
configuration defaults, from the Default layer (7).

== ENVIRONMENT

Options can be placed in the UBXOPTS environment variable. UBXOPTS is
processed before the CLI options.

== RETURN VALUES

*0*:: on success.
*1*:: on failure

== SEE ALSO

*ubxtool* is written to conform to the official u-blox documentation for
the u-blox binary protocol.
https://www.u-blox.com/en/product-resources[]

*gpsd*(8), *gpsctl*(1), *gps*(1)

== RESOURCES

*Project web site:* {gpsdweb}

== COPYING

This file is Copyright 2013 by the GPSD project +
SPDX-License-Identifier: BSD-2-clause