ubxtool(1)

1UBXTOOL(1)                    GPSD Documentation                    UBXTOOL(1)
2
3
4

NAME

6       ubxtool - u-blox tool
7

SYNOPSIS

9       ubxtool [OPTIONS} [server[:port[:device]]]
10
11       ubxtool -h
12
13       ubxtool -V
14

DESCRIPTION

16       ubxtool is a tool for u-blox GPS. If you do not have a u-blox GPS then
17       you can stop reading now.
18
19       This tool operates with your u-blox GPS at a very low level. To
20       understand ubxtool you must first be familiar with your u-blox GPS and
21       the documentation for the u-blox binary protocol. The u-blox protocol
22       varies greatly depending on GPS model and firmware revision. Use the
23       u-blox documentation for your model and firmware.
24
25       ubxtool can decode common u-blox binary messages, poll the GPS status,
26       enable and disable GPS features, and send user generated commands to
27       the GPS. It can read binary messages from a file. It can read and write
28       directly through a serial device, or through a running gpsd instance.
29
30       ubxtool does not require root privileges, except maybe to access the
31       serial port in direct access mode (-f FILE). It will run fine as root.
32       Running under sudo will cause loss of functionality.
33

OPTIONS

35       The program accepts the following options:
36
37       -?, -h, --help
38           Makes ubxtool print a usage message and exit. Use with -v 2 to see
39           all enable/disable and preset values. Use with -v 3 to additionally
40           see all configuration items (long).
41
42       -c COMMAND, --command COMMAND
43           Send a command to the GPS. Accepts one parameter, COMMAND, a
44           comma-separated list of hexadecimal bytes specifying the class, the
45           ID, and any needed payload. The header, length, and checksum are
46           added automatically.
47
48       --device DEVICE
49           The DEVICE on the gpsd to connect to. Defaults to all.
50
51       -d OPTION, --disable OPTION
52           Disable an option in the GPS. Accepts one parameter, OPTION, the
53           option to disable. Run "ubxtool -h -v 2" to see all possible
54           OPTIONs. A few possible OPTIONs are:
55
56           BEIDOU
57               Disable use of the BeiDou (COMPASS) constellation.
58
59           BINARY
60               Disable sending of the basic binary messages.
61
62           ECEF
63               Disable sending of ECEF binary messages.
64
65           GALILEO
66               Disable use of the GALILEO constellation.
67
68           GLONASS
69               Disable use of the GLONASS constellation.
70
71           GPS
72               Disable use of the GPS and QZSS constellations.
73
74           NED
75               Disable sending of NED binary messages. UBX-NAV-VELNED and
76               UBX-NAV-RELPOSNED.
77
78           NMEA
79               Disable sending basic NMEA messages. The messages are GBS, GGA,
80               GSA, GGL, GST, GSV, RMC, VTG, and ZDA.
81
82           PPS
83               Disable TIMEPULSE 0.
84
85           RAWX
86               Disable sending of the UBX-RXM-RAWX messages.
87
88           SBAS
89               Disable use of the SBAS constellation.
90
91           SFRBX
92               Disable use of the SFRBX messages.
93
94           SURVEYIN
95               Disable survey-in mode with TMODE2.
96
97           TP
98               Disable sending UBX-TIM-TP.
99
100       -e OPTION, --enable OPTION
101           Enable an option in the GPS. Accepts one parameter, OPTION, the
102           option to enable. -e accepts the same OPTIONs as -d, except the
103           action is to enable the option.
104
105       -f FILE, --file FILE
106           Connect directly to a file or device. Accepts one parameter, FILE,
107           the file or device to open. Files are opened read-only. Character
108           devices are opened read/write, unless the -r parameter is given.
109           Requires the pyserial module.
110
111       -g ITEM,LAYER,POSITION,END, --getitem ITEM,LAYER,POSITION,END
112           Get the value of ITEM from LAYER, starting at POSITION, up to END
113           key/value pairs (UBX-CFG-VALGET). All parameters past ITEM are
114           optional and decimal. If LAYER is absent, then layers 0, 1, 2 and 7
115           are all requested. See the section on CONFIGURATION ITEMS
116
117       --host HOST
118           Connect to the gpsd on HOST (server). Defaults to localhost.
119
120       -i port, --portid port
121           Specifies port ID # (interface) for port-related commands such as
122           UBX_CFG-PRT.
123
124       -p PRESET, --preset PRESET
125           Send a preset command to the GPS. Usually accepts one parameter,
126           PRESET, the name of the command to send. A few PRESETS, like
127           LOG-FINDTIME, accept additional comma separated parameters. More
128           than one -p may be used.
129
130       Only the common PRESETS are shown here. To see the full list, including
131       optional parameters, run "ubxtool -h -v 2".
132
133       COLDBOOT
134           Coldboot the GPS (UBX-CFG-RST).
135
136       HOTBOOT
137           Hotboot the GPS (UBX-CFG-RST).
138
139       MODEL,model
140           Configure the Dynamic Platform Model to model. (UBX-CFG-NAV5).
141           Model is the decimal number of the desired mode.
142
143       PMS
144           Set power management settings (UBX-CFG-PMS). "PMS,pow" where pow is
145           powerSetupValue.
146
147       RATE
148           Set measurement and nav rate (UBX-CFG-RATE). "RATE,meas,nav" meas
149           is the measRate in milli seconds. The nav argument is the navRate
150           in cycles and defaults to 1.
151
152       RESET
153           Reset configuration to defaults (UBX-CFG-CFG).
154
155       SAVE
156           Save current configuration (UBX-CFG-CFG).
157
158       MON-RESETODO
159           Reset the odometer (UBX-MON-RESETODO).
160
161       MON-VER
162           Poll GPS version (UBX-MON-VER).
163
164       WARMBOOT
165           Warmboot the GPS (UBX-CFG-RST).
166
167       Most PRESET parameters are simple poll commands. They merely poll the
168       GPS to respond with the associated message. For example "ubxtool -p
169       CFG-GNSS" asks the GPS to respond with a UBX-CFG-GNSS message
170       describing the current GNSS configuration. Increase the verbosity of
171       the output by adding the "-v 2" or "-v 3" options.
172
173       --port PORT
174           Use PORT to connect to gpsd. Defaults to 2947.
175
176       -P protver, --protver protver
177           Sets the protocol version to use for sending commands. Minimum 6
178           (Antaris 4). Use "ubxtool -p MON-VER" to see the version your
179           receiver supports. Many newer u-blox receivers will fail silently
180           or oddly if this is not set correctly. Default 10 (u-blox 5).
181
182       -r, -readonly
183           Read only. Do not send anything to the GPS.
184
185       -R RAW, --rawfile RAW
186           Save all raw serial data received from the GPS into the file RAW.
187
188       -s SPEED, --inspeed SPEED
189           Set local serial port speed to SPEED bps. Default 9,600 bps.
190
191       -S SPEED, --setspeed SPEED
192           Set the GPS serial port speed to SPEED bps.
193
194       -t, --timestamp
195           Timestamp decoded messages with seconds since the epoch. Use it
196           twice and also get UTC time.
197
198       -v VERBOSITY, --verbosity VERBOSITY
199           Set verbosity level to VERBOSITY. Verbosity can be from 0 (very
200           quiet), 2 (decode messages), to 4 (very noisy). Default 1.
201
202       -V, --version
203           Print ubxtool version and exit.
204
205       -w WAIT, --wait WAIT
206           Wait for WAIT seconds before exiting. Use 0 to wait forever.
207           Default 2 seconds.
208
209       -x ITEM,LAYERS, --delitem ITEM,LAYERS
210           Delete the value of ITEM name from LAYERS. The bit map LAYERS is
211           optional. By default, delete in both the BBR and FLASH layers in
212           the receiver (UBX_CFG-VALDEL). Returning to the reciver default for
213           that item. See the section on CONFIGURATION ITEMS
214
215       -z ITEM,VAL,LAYERS, --setitem ITEM,VAL,LAYERS
216           Set the value of ITEM name to VAL in LAYERS in the GPS
217           (UBX-CFG-VALSET). VAL and the bit mask LAYERS are decimal.
218           ",LAYERS" is optional. The default LAYERS are RAM and FLASH. See
219           the section on CONFIGURATION ITEMS
220

ARGUMENTS

222       By default, clients collect data from the local gpsd daemon running on
223       localhost, using the default GPSD port 2947. The optional argument to
224       any client may override this behavior: [server[:port[:device]]]
225
226       For further explanation, and examples, see the ARGUMENTS section in the
227       gps(1) man page
228

CONFIGURATION ITEMS

230       Configuring u-blox GPS with the traditional configuration messages is
231       fraught with problems. Many configuration messages interact in odd
232       ways. Something as simple as changing the serial port speed requires
233       you to read the current configuration using UBX-CFG-PRT for the proper
234       port, merging in the change, the writing back the changed UBX-CFG-PRT
235       message. Or just guessing at the current configuration and overwriting
236       it all.
237
238       The u-blox 9 series, protocol version 27+, tries, but does not
239       completely succeed, to solve the problem with Configuration Items. If
240       your GPS does not support protocol version 27+, then this section does
241       not apply to you.
242
243       Most of the configuration variables in the GPS have been assigned a
244       32-bit Key ID. Each Key references one specific value. A typical
245       receiver may have over 1,100 Key IDs. Each Key ID has been assigned a
246       Key Name. Most of the Key Names are documented by u-blox and supported
247       by ubxtool. To see all the Key Name understood by ubxtool run: "ubxtool
248       -h -v 3".
249
250       To get the value related to an item, use "-g ITEM".
251
252       To reset the value related to an item to it default value, use "-x
253       ITEM".
254
255       To set an ITEM name to a value, use "-z ITEM,VAL".
256
257       If you only want to set an ITEM in one layer, use "-z ITEM,VAL,LAYER".
258
259       See the EXAMPLES section for concrete examples.
260

EXAMPLES

262       All examples assume that UBXOPTS is set with the protocol version of
263       your receiver. Be sure to replace the "-P 18" with your correct
264       prototype version.
265
266           export UBXOPTS="-P 18"
267
268       Dump configuration and status of the GNSS recceiver. The "-w 4" is to
269       provide extra time for the operations to complete.
270
271           ubxtool -p CONFIG -p STATUS -w 4 -v 2
272
273       Decode raw log file:
274
275           ubxtool -r -f ublox-neo-m8n.log
276
277       Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:
278
279           ubxtool -S 230400 -f /dev/ttyAMA0
280
281       Watch entire GPS reset cycle, include $GPTXT messages:
282
283           ubxtool -p COLDBOOT -w 20 -v 2
284
285       Poll Enabled Constellations:
286
287           ubxtool -p CFG-GNSS
288
289       Dump gpsd data from a remote server named x.example.com:
290
291           ubxtool -w 5 x.example.com
292
293   CFG-TP5
294       Some of the "-p" and "--preset" commands can take multiple options. One
295       of these is "--preset CFG-TP5".
296
297       Synopsis:
298
299           -p CFG-TP5,[tpIdx = 0],[antCableDelay = 2],[rfGroupDelay = 0],[freqPeriod = 1000000],[freqPeriodLock = 1000000],[pulseLenRatio = 0],[pulseLenRatioLock = 100000],[userConfigDelay = 0],[flags = 0x77]
300
301       Leave a positional parameter empty for it to take the default value.
302
303       To set the pulse period to 0.25 s and its length to 0.1 s:
304
305           $ ubxtool -p CFG-TP5,,,,250000,250000,100000,100000
306
307       To set the pulse period to 0.1 s and length to 0.1 s in the presence of
308       lock:
309
310           $ ubxtool -p CFG-TP5,,,,,100000,,50000
311
312   Version 27+ examples
313       The following examples require a GPS supporting protocol 27 or greater.
314       Be sure to set your protocol version first:
315
316               export UBXOPTS="-P 32"
317
318       To check the current dynamic model, change it to 6 (AIR1, Airborne with
319       <1g acceleration), revert to the default setting, and verify the faults
320       was restored.
321
322           $ ubxtool -g CFG-NAVSPG-DYNMODEL
323           [...]
324           UBX-CFG-VALGET:
325            version 1 layer 0 reserved 0,0
326             layers (ram)
327               item CFG-NAVSPG-DYNMODEL/0x20110021 val 2
328           [...]
329           $ ubxtool -z CFG-NAVSPG-DYNMODEL,6
330           [...]
331           UBX-ACK-ACK:
332            ACK to Class x6 (CFG) ID x8a (VALSET)
333           [...]
334           $ ubxtool -g CFG-NAVSPG-DYNMODEL
335           [...]
336           UBX-CFG-VALGET:
337            version 1 layer 0 reserved 0,0
338             layers (ram)
339               item CFG-NAVSPG-DYNMODEL/0x20110021 val 6
340           [...]
341           $ ubxtool -x CFG-NAVSPG-DYNMODEL
342           [...]
343           UBX-ACK-ACK:
344            ACK to Class x6 (CFG) ID x8c (VALDEL)
345           [...]
346           $ ubxtool -g CFG-NAVSPG-DYNMODEL
347           [...]
348           UBX-CFG-VALGET:
349            version 1 layer 0 reserved 0,0
350             layers (ram)
351               item CFG-NAVSPG-DYNMODEL/0x20110021 val 6
352
353       Notice that the current DYNMODEL stayed at 6 (AIR1). The "-x" only
354       affects the saved setting, not the current setting. To change the
355       current setting you must set it with "-z".
356
357       Getting all the Configuration Items in a group one by one could be very
358       tedious. VAL-GET allows you to wild card the item number and dump all
359       the items in a group. To get all the CFG-TP items in ram, the currently
360       active ones, you can do this:
361
362           $ ubxtool -g CFG-TP,0
363           [...]
364           UBX-CFG-VALGET:
365            version 1 layer 0 position 0
366             layers (ram)
367               item CFG-TP-TP1_ENA/0x10050007 val 1
368               item CFG-TP-SYNC_GNSS_TP1/0x10050008 val 1
369               item CFG-TP-USE_LOCKED_TP1/0x10050009 val 1
370           [...]
371
372       The truly masochistic can dump all the Configuration Items by
373       wildcarding the group. Dumping all 1,000+ of them, 64 at a time, could
374       still be tedious. The -g parameter optionally allows you to specify the
375       starting position to get from, as well as the ending position. To get
376       all the known, and unknown, items supported by the receiver that are
377       currently in ram:
378
379           $ ubxtool -g CFG,0,0,1200 | fgrep "item CFG-"
380               item CFG-1-1/0x10010001 val 0
381               item CFG-1-1/0x10010101 val 0
382               item CFG-4-1/0x10040001 val 1
383               item CFG-4-2/0x10040002 val 0
384               item CFG-4-3/0x10040003 val 0
385               item CFG-4-4/0x10040004 val 0
386               item CFG-4-9/0x10040009 val 0
387               item CFG-TP-TP1_ENA/0x10050007 val 1
388               item CFG-TP-SYNC_GNSS_TP1/0x10050008 val 1
389           [...]
390
391       Changing CFG,0,0,1200 to CFG,7,0,1200 would instead dump all the
392       configuration defaults, from the Default layer (7).
393

ENVIRONMENT

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

RETURN VALUES

399       0
400           on success.
401
402       1
403           on failure
404

RESOURCES

412       Project web site: https://gpsd.io/
413

COPYING

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

AUTHOR

419       Gary E. Miller
420
421
422
423GPSD, Version 3.25                2023-01-10                        UBXTOOL(1)