1UBXTOOL(1) GPSD Documentation UBXTOOL(1)
2
6 ubxtool - u-blox tool
7
9 ubxtool [-?] [--command command] [--delitem item,layers]
10 [--device device] [--disable disable] [--enable enable]
11 [--file file/device] [--getitem item,layer,position,end]
12 [--help] [--host host] [--inspeed speed] [--port port]
13 [--portid port] [--preset preset] [--protver protver]
14 [--rawfile rawfile] [--readonly] [--setitem item,val,layers]
15 [--setspeed setspeed] [--timestamp] [--verbosity verbosity]
16 [--version] [--wait wait] [-c command] [-d disable] [-e enable]
17 [-f file/device] [-g item,layer,position,end] [-h] [-i port]
18 [-p preset] [-P protver] [-r] [-R rawfile] [-S setspeed]
19 [-s speed] [-t] [-V] [-v verbosity] [-w wait] [-x item,layers]
20 [-z item,val,layers] [[server[:port[:device]]]]
21
23 ubxtool is a tool for u-blox GPS. If you do not have a u-blox GPS then
24 can stop reading now.
25 This tool operates with your u-blox GPS at a very low level. To
27 understand ubxtool you must first be familiar with your u-blox GPS and
28 the documentation for the u-blox binary protocol. The u-blox protocol
29 varies greatly depending on GPS model and firmware revision. Use the
30 u-blox documentation for your model and firmware.
31 ubxtool can decode common u-blox binary messages, poll the GPS status,
33 enable and disable GPS features, and send user generated commands to
34 the GPS. It can read binary messages from a file. It can read and write
35 directly through a serial device, or through a running gpsd instance.
36
38 The program accepts the following options:
39 -?, -h, --help
41 Makes ubxtool print a usage message and exit. Use with -v 2 to see
42 all enable/disable and preset values. Use with -v 3 to additionally
43 see all configuration items (long).
44 -c COMMAND, --command COMMAND
46 Send a command to the GPS. Accepts one parameter, COMMAND, a
47 comma-separated list of hexadecimal bytes specifying the class, the
48 ID, and any needed payload. The header, length, and checksum are
49 added automatically.
50 --device DEVICE
52 The DEVICE on the gpsd to connect to. Defaults to all.
53 -d OPTION, --disable OPTION
55 Disable an option in the GPS. Accepts one parameter, OPTION, the
56 option to disable. Use -h -v 2 to see all possible OPTIONs. A few
57 possible OPTIONs are:
58 BEIDOU
60 Disable use of the BeiDou (COMPASS) constellation.
61 BINARY
63 Disable sending of the basic binary messages.
64 ECEF
66 Disable sending of ECEF binary messages.
67 GALILEO
69 Disable use of the GALILEO constellation.
70 GLONASS
72 Disable use of the GLONASS constellation.
73 GPS
75 Disable use of the GPS and QZSS constellations.
76 NED
78 Disable sending of NED binary messages. UBX-NAV-VELNED and
79 UBX-NAV-RELPOSNED.
80 NMEA
82 Disable sending basic NMEA messages. The messages are GBS, GGA,
83 GSA, GGL, GST, GSV, RMC, VTG, and ZDA.
84 PPS
86 Disable TIMEPULSE 0.
87 RAWX
89 Disable sending of the UBX-RXM-RAWX messages.
90 SBAS
92 Disable use of the SBAS constellation.
93 SFRBX
95 Disable use of the SFRBX messages.
96 SURVEYIN
98 Disable survey-in mode with TMODE2.
99 TP
101 Disable sending UBX-TIM-TP.
102 -e OPTION, --enable OPTION
104 Enable an option in the GPS. Accepts one parameter, OPTION, the
105 option to enable. -e accepts the same OPTIONs as -d, except the
106 action is to enable the option.
107 -f FILE, --file FILE
109 Connect to a file or device. Accepts one parameter, FILE, the file
110 or device to open. Files are opened read-only. Character devices
111 are opened read/write, unless the -r parameter is given. Requires
112 the pyserial module.
113 -g ITEM,LAYER,POSITION,END, --getitem ITEM,LAYER,POSITION,END
115 Get the value of ITEM from LAYER, starting at POSITION, up to END
116 key/value pairs (UBX-CFG-VALGET). All parameters past ITEM are
117 optional and decimal. If LAYER is absent, then layers 0, 1, 2 and 7
118 are all requested. See the section on CONFIGURATION ITEMS
119 --host HOST
121 Connect to the gpsd on HOST (server). Defaults to localhost.
122 -i port, --portid port
124 Specifies port ID # (interface) for port-related commands such as
125 UBX_CFG-PRT.
126 -p PRESET, --preset PRESET
128 Send a preset command the GPS. Usually accepts one parameter,
129 PRESET, the name of the command to send. A few PRESETS, like
130 LOG-FINDTIME, accept additional comma separated parameters. More
131 than one -p may be used.
132 Only the common PRESETS are shown here. To see the full list,
134 including optional parameters, run "ubxtool -h -v 2".
135 COLDBOOT
137 Coldboot the GPS (UBX-CFG-RST).
138 HOTBOOT
140 Hotboot the GPS (UBX-CFG-RST).
141 MODEL,model
143 Configure the Dynamic Platform Model to model. (UBX-CFG-NAV5).
144 Model is the decimal number of the desired mode.
145 PMS
147 Set power management settings (UBX-CFG-PMS). "PMS,pow" where
148 pow is powerSetupValue.
149 RATE
151 Set measurement and nav rate (UBX-CFG-RATE). "RATE,meas,nav"
152 meas is the measRate in milli seconds. The nav argument is the
153 navRate in cycles and defaults to 1
154 RESET
156 Reset configuration to defaults (UBX-CFG-CFG).
157 SAVE
159 Save current configuration (UBX-CFG-CFG).
160 MON-RESETODO
162 Reset the odometer (UBX-MON-RESETODO).
163 MON-VER
165 Poll GPS version (UBX-MON-VER).
166 WARMBOOT
168 Warmboot the GPS (UBX-CFG-RST).
169 Most PRESET parameters are simple poll commands. They merely poll
171 the GPS to respond with the associated message. For example
172 "ubxtool -p CFG-GNSS" asks the GPS to respond with a UBX-CFG-GNSS
173 message describing the current GNSS configuration. Increase the
174 verbosity of the output by adding the "-v 2" or "-v 3" options.
175 --port PORT
177 Use PORT to connect to gpsd. Defaults to 2947.
178 -P protver, --protver protver
180 Sets the protocol version to use for sending commands. Minimum 6
181 (Antaris 4). Use "ubxtool -p MON-VER" to see the version your
182 receiver supports. Many newer u-blox receivers will fail silently
183 or oddly if this is not set correctly. Default 10 (u-blox 5).
184 -r, -readonly
186 Read only. Do not send anything to the GPS.
187 -R RAW, --rawfile RAW
189 Save all raw serial data received from the GPS into the file RAW.
190 -s SPEED, --inspeed SPEED
192 Set local serial port speed to SPEED bps. Default 9,600 bps.
193 -S SPEED, --setspeed SPEED
195 Set the GPS serial port speed to SPEED bps.
196 -t, --timestamp
198 Timestamp decoded messages with seconds since the epoch. Use it
199 twice and also get UTC time.
200 -v VERBOSITY, --verbosity VERBOSITY
202 Set verbosity level to VERBOSITY. Verbosity can be from 0 (very
203 quiet), 2 (decode messages), to 4 (very noisy). Default 1.
204 -V, --version
206 Print ubxtool version and exit.
207 -w WAIT, --wait WAIT
209 Wait for WAIT seconds before exiting. Default 2 seconds.
210 -x ITEM,LAYERS, --delitem ITEM,LAYERS
212 Delete the value of ITEM name from LAYERS. The bit map LAYERS is
213 optional. By default, delete in both the BBR and FLASH layers in
214 the receiver (UBX_CFG-VALDEL). Returning to the reciver default for
215 that item. See the section on CONFIGURATION ITEMS
216 -z ITEM,VAL,LAYERS, --setitem ITEM,VAL,LAYERS
218 Set the value of ITEM name to VAL in LAYERS in the GPS
219 (UBX-CFG-VALSET). VAL and the bit mask LAYERS are decimal.
220 ",LAYERS" is optional. The default LAYERS are RAM and FLASH See the
221 section on CONFIGURATION ITEMS
222 [server[:port[:device]]]
224 By default, ubxtool collects data from all compatible devices on
225 localhost, using the default GPSD port 2947. An optional argument
226 may specify a server to get data from. A colon-separated suffix is
227 taken as a port number. If there is a second colon-separated
228 suffix, that is taken as a specific device name to be watched.
229 Further details on the gps(1) man page.
230
232 Configuring u-blox GPS with the traditional configuration messages is
233 fraught with problems. Many configuration messages interact in odd
234 ways. Something as simple as changing the serial port speed requires
235 you to read the current configuration using UBX-CFG-PRT for the proper
236 port, merging in the change, the writing back the changed UBX-CFG-PRT
237 message. Or just guessing at the current configuration and overwriting
238 it all.
239 The u-blox 9 series, protocol version 27+, tries, but does not
241 completely succeed, to solve the problem with Configuration Items. If
242 your GPS does not support protocol version 27+, then this section does
243 not apply to you.
244 Most of the configuration variables in the GPS have been assigned a
246 32-bit Key ID. Each Key references one specific value. A typical
247 receiver may have over 1,100 Key IDs. Each Key ID has been assigned a
248 Key Name. Most of the Key Names are documented by u-blox and supported
249 by ubxtool. To see all the Key Name understood by ubxtool do: "ubxtool
250 -h -v 3".
251 To get the value related to an item, use "-g ITEM".
253 To reset the value related to an item to it default value, use "-x
255 ITEM".
256 To set an ITEM name to a value, use "-z ITEM,VAL".
258 If you only want to set an ITEM in one layer, use "-z ITEM,VAL,LAYER".
260 See the EXAMPLES section for concrete examples.
262
264 All examples assume that UBXOPTS is set with the protocol version of
265 your receiver. Be sure to replace the "-P 18" with your correct
266 prototype version.
267 export UBXOPTS="-P 18"
269 Dump configuration and status of the GNSS recceiver. The "-w 4" is to
271 provide extra time for the operations to complete.
272 ubxtool -p CONFIG -p STATUS -w 4 -v 2
274 Decode raw log file:
276 ubxtool -r -f ublox-neo-m8n.log
278 Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:
280 ubxtool -S 230400 -f /dev/ttyAMA0
282 Watch entire GPS reset cycle, include $GPTXT messages:
284 ubxtool -p COLDBOOT -w 20 -v 2
286 Poll Enabled Constellations:
288 ubxtool -p CFG-GNSS
290 Dump gpsd data from a remote server named x.example.com:
292 ubxtool -w 5 x.example.com
294 Version 27+ examples
297 The following examples require a GPS supporting protocol 27 or greater.
298 Be sure to set your protocol version first:
299 export UBXOPTS="-P 32"
301 To check the current dynamic model, change it to 6 (AIR1, Airborne with
304 <1g acceleration), revert to the default setting, and verify the faults
305 was restored.
306 $ ubxtool -g CFG-NAVSPG-DYNMODEL
308 [...]
309 UBX-CFG-VALGET:
310 version 1 layer 0 reserved 0,0
311 layers (ram)
312 item CFG-NAVSPG-DYNMODEL/0x20110021 val 2
313 [...]
314 $ ubxtool -z CFG-NAVSPG-DYNMODEL,6
315 [...]
316 UBX-ACK-ACK:
317 ACK to Class x6 (CFG) ID x8a (VALSET)
318 [...]
319 $ ubxtool -g CFG-NAVSPG-DYNMODEL
320 [...]
321 UBX-CFG-VALGET:
322 version 1 layer 0 reserved 0,0
323 layers (ram)
324 item CFG-NAVSPG-DYNMODEL/0x20110021 val 6
325 [...]
326 $ ubxtool -x CFG-NAVSPG-DYNMODEL
327 [...]
328 UBX-ACK-ACK:
329 ACK to Class x6 (CFG) ID x8c (VALDEL)
330 [...]
331 $ ubxtool -g CFG-NAVSPG-DYNMODEL
332 [...]
333 UBX-CFG-VALGET:
334 version 1 layer 0 reserved 0,0
335 layers (ram)
336 item CFG-NAVSPG-DYNMODEL/0x20110021 val 6
337 Notice that the current DYNMODEL stayed at 6 (AIR1). The "-x" only
339 affects the saved setting, not the current setting. To change the
340 current setting you must set it with "-z".
341 Getting all the Configuration Items in a group one by one could be very
343 tedious. VAL-GET allows you to wild card the item number and dump all
344 the items in a group. To get all the CFG-TP items in ram, the currently
345 active ones, you can do this:
346 $ ubxtool -g CFG-TP,0
348 [...]
349 UBX-CFG-VALGET:
350 version 1 layer 0 position 0
351 layers (ram)
352 item CFG-TP-TP1_ENA/0x10050007 val 1
353 item CFG-TP-SYNC_GNSS_TP1/0x10050008 val 1
354 item CFG-TP-USE_LOCKED_TP1/0x10050009 val 1
355 [...]
356 The truly masochistic can dump all the Configuration Items by
358 wildcarding the group. Dumping all 1,000+ of them, 64 at a time, could
359 still be tedious. The -g parameter optionally allows you to specify the
360 starting position to get from, as well as the ending position. To get
361 all the known, and unknown, items supported by the receiver that are
362 currently in ram:
363 $ ubxtool -g CFG,0,0,1200 | fgrep "item CFG-"
365 item CFG-1-1/0x10010001 val 0
366 item CFG-1-1/0x10010101 val 0
367 item CFG-4-1/0x10040001 val 1
368 item CFG-4-2/0x10040002 val 0
369 item CFG-4-3/0x10040003 val 0
370 item CFG-4-4/0x10040004 val 0
371 item CFG-4-9/0x10040009 val 0
372 item CFG-TP-TP1_ENA/0x10050007 val 1
373 item CFG-TP-SYNC_GNSS_TP1/0x10050008 val 1
374 [...]
375 Changing CFG,0,0,1200 to CFG,7,0,1200 would instead dump all the
377 configuration defaults, from the Default layer (7).
378
380 Options can be placed in the UBXOPTS environment variable. UBXOPTS is
381 processed before the CLI options.
382
384 ubxtool is written to conform to the official u-blox documentation for
385 the u-blox binary protocol.
386 https://www.u-blox.com/en/product-resources
387 cgps(1), gpscat(1), gpsctl(1), gpsfake(1), xgps(1), gpsd(8),
389
391 Gary E. Miller<gem@rellim.com>
392The GPSD Project 5 December 2020 UBXTOOL(1)