table of contents
UBXTOOL(1) | GPSD Documentation | UBXTOOL(1) |
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 you 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 access mode (-f FILE). It will run fine as root. Running under sudo will cause loss of functionality.
OPTIONS¶
The program accepts the following options:
-?, -h, --help
-c COMMAND, --command COMMAND
--device DEVICE
-d OPTION, --disable OPTION
BEIDOU
BINARY
ECEF
GALILEO
GLONASS
GPS
NED
NMEA
PPS
RAWX
SBAS
SFRBX
SURVEYIN
TP
-e OPTION, --enable OPTION
-f FILE, --file FILE
-g ITEM,LAYER,POSITION,END, --getitem ITEM,LAYER,POSITION,END
--host HOST
-i port, --portid port
-p PRESET, --preset PRESET
Only the common PRESETS are shown here. To see the full list, including optional parameters, run "ubxtool -h -v 2".
COLDBOOT
HOTBOOT
MODEL,model
PMS
RATE
RESET
SAVE
MON-RESETODO
MON-VER
WARMBOOT
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
-P protver, --protver protver
-r, -readonly
-R RAW, --rawfile RAW
-s SPEED, --inspeed SPEED
-S SPEED, --setspeed SPEED
-t, --timestamp
-v VERBOSITY, --verbosity VERBOSITY
-V, --version
-w WAIT, --wait WAIT
-x ITEM,LAYERS, --delitem ITEM,LAYERS
-z ITEM,VAL,LAYERS, --setitem ITEM,VAL,LAYERS
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
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
1
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>
RESOURCES¶
Project web site: <https://gpsd.io/>
COPYING¶
This file is Copyright 2013 by the GPSD project
SPDX-License-Identifier: BSD-2-clause
AUTHOR¶
Gary E. Miller
2023-01-10 | GPSD, Version 3.25 |