UBXTOOL(1)

💖 UBXTOOL(1) 💖 the u-blox tool, bestie

okay so this is ubxtool, from the GPSD Documentation. it's giving low-level GPS whisperer, and honestly? iconic. grab a snack, we're going deep 🦋

---

✨ NAME ✨

ubxtool — the u-blox tool. that's the whole name. short, sweet, does numbers 💅

---

✨ SYNOPSIS ✨

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

ubxtool -h

ubxtool -V

nope, the } in [OPTIONS} isn't me being chaotic, that's literally how it's written in the original. not my mess, i'm just the messenger 😭

---

✨ DESCRIPTION ✨

so ubxtool is a tool for u-blox GPS. if you do not have a u-blox GPS then honestly? you can stop reading now, this page is not for you, go live your life 🌸

this tool talks to your u-blox GPS at a very low level. like, we're down in the basement. to actually understand ubxtool you first need to be familiar with your u-blox GPS and with the documentation for the u-blox binary protocol. and here's the tea: the u-blox protocol varies greatly depending on GPS model and firmware revision. so use the u-blox documentation for your model and your firmware, no borrowing someone else's docs, that's not gonna slay 🫶

what can it actually do, you ask? okay so:

• it can decode common u-blox binary messages
• it can poll the GPS status
• it can enable and disable GPS features
• it can 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

and the best part: 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. but — and this is important — running under sudo will cause loss of functionality. so like, don't do that. it's giving self-sabotage 💀

---

✨ OPTIONS ✨

the program accepts the following options:

• -?, -h, --help — makes ubxtool print a usage message and exit. use it with -v 2 to see all enable/disable and preset values. use it with -v 3 to additionally see all configuration items (long). yes, it's a whole iceberg, keep scrolling 🧊
• -c COMMAND, --command COMMAND — send a command to the GPS. takes 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. you don't gotta do the math, it does the math ✨
• --device DEVICE — the DEVICE on the gpsd to connect to. defaults to all.
• -d OPTION, --disable OPTION — disable an option in the GPS. takes one parameter, OPTION, the option to disable. run ubxtool -h -v 2 to see all possible *OPTION*s. a few possible *OPTION*s 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. takes one parameter, OPTION, the option to enable. -e accepts the same *OPTION*s as -d, except the action is to enable the option. yes, it's the same list, just the other direction, we love symmetry 💜
• -f FILE, --file FILE — connect directly to a file or device. takes 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. no module, no vibe 🫠
• -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 to the GPS. usually takes one parameter, PRESET, the name of the command to send. a few *PRESET*s, like LOG-FINDTIME, accept additional comma separated parameters. more than one -p may be used. stack 'em, bestie 📚

only the common *PRESET*s 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. more info, more better 🔍

• --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).

fail silently?? the worst kind of fail. set it right, babe 😭

• -r, -readonly — read only. do not send anything to the GPS. pure observer energy 👀
• -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. double tap for the bonus ✌️
• -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. use 0 to wait forever. 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 receiver 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. go read it, it's short, you got this 🫶

---

✨ CONFIGURATION ITEMS ✨

okay so configuring u-blox GPS with the traditional configuration messages is, and i'm quoting the vibes here, fraught with problems 😭 many configuration messages interact in odd ways. like, something as simple as changing the serial port speed requires you to read the current configuration using UBX-CFG-PRT for the proper port, merge in the change, and then write back the changed UBX-CFG-PRT message. or just guess at the current configuration and overwrite it all. which, bestie, is a choice 🙈

the u-blox 9 series, protocol version 27+, tries, but does not completely succeed, to solve the problem with Configuration Items. and heads up: if your GPS does not support protocol version 27+, then this whole section does not apply to you. scroll on, love 🌸

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

the quickie cheat sheet:

• to get the value related to an item, use -g ITEM.
• to reset the value related to an item to its 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. and yes, there's more coming, this page is long and we're only halfway through the lore 📖✨

---

✨ EXAMPLES ✨

Okay bestie, every single one of these examples assumes you've got UBXOPTS set to the protocol version of your receiver. And fr fr, swap that -P 18 for your actual correct prototype version. Don't just copy-paste and pray. 🙏

export UBXOPTS="-P 18"

Dump configuration and status of the GNSS recceiver. The -w 4 is there to give the operations extra time 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. Empty = default, periodt. 💅

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. No cap. 🧠

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. So yeah, env first, CLI after. Order matters bestie. ✨

💖 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: https://gpsd.io/

👑 COPYING 👑

This file is Copyright 2013 by the GPSD project.

SPDX-License-Identifier: BSD-2-clause

🦋 AUTHOR 🦋

Gary E. Miller

---

And that's the whole page, bestie. This iconic little manual page is from GPSD, Version 3.27.5, dated 2025-11-04, and it's the UBXTOOL(1) man page. Go forth and slay. 💅✨