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       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 mode. It will run fine as root. Running under
32       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 to a file or device. Accepts one parameter, FILE, the file
107           or device to open. Files are opened read-only. Character devices
108           are opened read/write, unless the -r parameter is given. Requires
109           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 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. Default 2 seconds.
207
208       -x ITEM,LAYERS, --delitem ITEM,LAYERS
209           Delete the value of ITEM name from LAYERS. The bit map LAYERS is
210           optional. By default, delete in both the BBR and FLASH layers in
211           the receiver (UBX_CFG-VALDEL). Returning to the reciver default for
212           that item. See the section on CONFIGURATION ITEMS
213
214       -z ITEM,VAL,LAYERS, --setitem ITEM,VAL,LAYERS
215           Set the value of ITEM name to VAL in LAYERS in the GPS
216           (UBX-CFG-VALSET). VAL and the bit mask LAYERS are decimal.
217           ",LAYERS" is optional. The default LAYERS are RAM and FLASH. See
218           the section on CONFIGURATION ITEMS
219

ARGUMENTS

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

CONFIGURATION ITEMS

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

EXAMPLES

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

ENVIRONMENT

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

RETURN VALUES

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

RESOURCES

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

COPYING

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

AUTHOR

418       Gary E. Miller
419
420
421
422GPSD, Version 3.23.1              2021-09-17                        UBXTOOL(1)