1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!-- 3This file is Copyright (c) 2018 by the GPSD project 4BSD terms apply: see the file COPYING in the distribution root for details. 5--> 6<!DOCTYPE refentry PUBLIC 7 "-//OASIS//DTD DocBook XML V4.1.2//EN" 8 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 9<refentry id='ubxtool.1'> 10 <refentryinfo> 11 <date>26 Jun 2019</date> 12 </refentryinfo> 13 <refmeta> 14 <refentrytitle>ubxtool</refentrytitle> 15 <manvolnum>1</manvolnum> 16 <refmiscinfo class="source">The GPSD Project</refmiscinfo> 17 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo> 18 </refmeta> 19 <refnamediv id='name'> 20 <refname>ubxtool</refname> 21 <refpurpose>u-blox tool</refpurpose> 22 </refnamediv> 23 <refsynopsisdiv id='synopsis'> 24 <cmdsynopsis> 25 <command>ubxtool</command> 26 <arg choice='opt'>-? </arg> 27 <arg choice='opt'>-c <replaceable>command</replaceable> </arg> 28 <arg choice='opt'>-d <replaceable>disable</replaceable> </arg> 29 <arg choice='opt'>-e <replaceable>enable</replaceable> </arg> 30 <arg choice='opt'>-f <replaceable>file/device</replaceable> </arg> 31 <arg choice='opt'>-g <replaceable>item</replaceable> </arg> 32 <arg choice='opt'>-h </arg> 33 <arg choice='opt'>-i <replaceable>port</replaceable></arg> 34 <arg choice='opt'>-m <replaceable>mode</replaceable></arg> 35 <arg choice='opt'>-P <replaceable>protver</replaceable></arg> 36 <arg choice='opt'>-p <replaceable>preset</replaceable></arg> 37 <arg choice='opt'>-R <replaceable>rawfile</replaceable></arg> 38 <arg choice='opt'>-r </arg> 39 <arg choice='opt'>-S <replaceable>setspeed</replaceable></arg> 40 <arg choice='opt'>-s <replaceable>speed</replaceable></arg> 41 <arg choice='opt'>-V </arg> 42 <arg choice='opt'>-v <replaceable>verbosity</replaceable></arg> 43 <arg choice='opt'>-w <replaceable>wait</replaceable></arg> 44 <arg choice='opt'>-x <replaceable>item</replaceable> </arg> 45 <arg choice='opt'>-z <replaceable>item,val</replaceable> </arg> 46 <arg choice='opt'>[server[:port[:device]]]</arg> 47 </cmdsynopsis> 48 </refsynopsisdiv> 49 <refsect1 id='description'> 50 <title>DESCRIPTION</title> 51 <para> 52 <application>ubxtool</application> is a tool for u-blox GPS. 53If you do not have a u-blox GPS then can stop reading now.</para> 54 <para>This tool operates with your u-blox GPS at a very low level. 55To understand <application>ubxtool</application> you must first be familiar 56with your u-blox GPS and the documentation for the u-blox binary protocol. 57The u-blox protocol varies greatly depending on GPS model and firmware 58revision. Use the u-blox documentation for your model and firmware. 59</para> 60 <para> 61 <application>ubxtool</application> can decode common u-blox binary 62 messages, poll the GPS status, enable and disable GPS features, and send user 63generated commands to the GPS. It can read binary messages from a file. It 64can read and write directly through a serial device, or through a 65running gpsd instance.</para> 66 </refsect1> 67 <refsect1 id='options'> 68 <title>OPTIONS</title> 69 <para>The program accepts the following options:</para> 70 <variablelist remap='TP'> 71 <varlistentry> 72 <term>-?</term> 73 <listitem> 74 <para>Makes <application>ubxtool</application> print 75a usage message and exit.</para> 76 </listitem> 77 </varlistentry> 78 <varlistentry> 79 <term>-c COMMAND</term> 80 <listitem> 81 <para>Send a command to the GPS. Accepts one parameter, COMMAND, 82a comma-separated list of hexadecimal bytes specifying the class, the ID, 83and any needed payload. The header, length, and checksum are added automatically. 84</para> 85 </listitem> 86 </varlistentry> 87 <varlistentry> 88 <term>-d OPTION</term> 89 <listitem> 90 <para>Disable an option in the GPS. Accepts one parameter, OPTION, 91the option to disable. 92</para> 93 <variablelist> 94 <varlistentry> 95 <term>BEIDOU</term> 96 <listitem> 97 <para>Disable use of the BeiDou (COMPASS) constellation.</para> 98 </listitem> 99 </varlistentry> 100 <varlistentry> 101 <term>BINARY</term> 102 <listitem> 103 <para>Disable sending of the basic binary messages.</para> 104 </listitem> 105 </varlistentry> 106 <varlistentry> 107 <term>ECEF</term> 108 <listitem> 109 <para>Disable sending of ECEF binary messages.</para> 110 </listitem> 111 </varlistentry> 112 <varlistentry> 113 <term>GALILEO</term> 114 <listitem> 115 <para>Disable use of the GALILEO constellation.</para> 116 </listitem> 117 </varlistentry> 118 <varlistentry> 119 <term>GLONASS</term> 120 <listitem> 121 <para>Disable use of the GLONASS constellation.</para> 122 </listitem> 123 </varlistentry> 124 <varlistentry> 125 <term>GPS</term> 126 <listitem> 127 <para>Disable use of the GPS and QZSS constellations.</para> 128 </listitem> 129 </varlistentry> 130 <varlistentry> 131 <term>NED</term> 132 <listitem> 133 <para>Disable sending of NED binary messages. UBX-NAV-VELNED 134and UBX-NAV-RELPOSNED.</para> 135 </listitem> 136 </varlistentry> 137 <varlistentry> 138 <term>NMEA</term> 139 <listitem> 140 <para>Disable sending basic NMEA messages. The messages are 141GBS, GGA, GSA, GGL, GST, GSV, RMC, VTG, and ZDA.</para> 142 </listitem> 143 </varlistentry> 144 <varlistentry> 145 <term>PPS</term> 146 <listitem> 147 <para>Disable TIMEPULSE 0.</para> 148 </listitem> 149 </varlistentry> 150 <varlistentry> 151 <term>RAWX</term> 152 <listitem> 153 <para>Disable sending of the UBX-RXM-RAWX messages.</para> 154 </listitem> 155 </varlistentry> 156 <varlistentry> 157 <term>SBAS</term> 158 <listitem> 159 <para>Disable use of the SBAS constellation.</para> 160 </listitem> 161 </varlistentry> 162 <varlistentry> 163 <term>SFRBX</term> 164 <listitem> 165 <para>Disable use of the SFRBX messages.</para> 166 </listitem> 167 </varlistentry> 168 <varlistentry> 169 <term>SURVEYIN</term> 170 <listitem> 171 <para>Disable survey-in mode with TMODE2.</para> 172 </listitem> 173 </varlistentry> 174 <varlistentry> 175 <term>TP</term> 176 <listitem> 177 <para>Disable sending UBX-TIM-TP.</para> 178 </listitem> 179 </varlistentry> 180 </variablelist> 181 </listitem> 182 </varlistentry> 183 <varlistentry> 184 <term>-e OPTION</term> 185 <listitem> 186 <para>Enable an option in the GPS. Accepts one parameter, OPTION, 187the option to enable. -e accepts the same OPTIONs as -d, except the action 188is to enable the option. 189</para> 190 </listitem> 191 </varlistentry> 192 <varlistentry> 193 <term>-f FILE</term> 194 <listitem> 195 <para>Connect to a file or device. Accepts one parameter, FILE, 196the file or device to open. Files are opened read-only. Character 197devices are opened read/write, unless the -r parameter is given. 198Requires the pyserial module. 199</para> 200 </listitem> 201 </varlistentry> 202 <varlistentry> 203 <term>-g ITEM</term> 204 <listitem> 205 <para>Get the value of ITEM name from the GPS (UBX-CFG-VALGET). 206 See the section on CONFIGURATION ITEMS</para> 207 </listitem> 208 </varlistentry> 209 <varlistentry> 210 <term>-h</term> 211 <listitem> 212 <para>Makes <application>ubxtool</application> print 213a usage message and exit.</para> 214 </listitem> 215 </varlistentry> 216 <varlistentry> 217 <term>-i port</term> 218 <listitem> 219 <para>Specifies port (interface) for port-related commands. 220</para> 221 </listitem> 222 </varlistentry> 223 <varlistentry> 224 <term>-m mode</term> 225 <listitem> 226 <para>Sets optional mode parameter to a -p PRESET command. 227</para> 228 </listitem> 229 </varlistentry> 230 <varlistentry> 231 <term>-P protver</term> 232 <listitem> 233 <para>Sets the protocol version to use for sending commands. 234Minimum 10 (ublox 5). Maximum 29 (u-blox 9). Use "ubxtool -p MON-VER" 235 to see the version your GPS supports. 236 </para> 237 </listitem> 238 </varlistentry> 239 <varlistentry> 240 <term>-p PRESET</term> 241 <listitem> 242 <para>Send a preset command the GPS. Accepts one parameter, PRESET, 243the name of the command to send. Only the common PRESETS are shown here. 244To see the full list run "ubxtool -h -v 2". 245</para> 246 <variablelist> 247 <varlistentry> 248 <term>COLDBOOT</term> 249 <listitem> 250 <para>Coldboot the GPS (UBX-CFG-RST).</para> 251 </listitem> 252 </varlistentry> 253 <varlistentry> 254 <term>HOTBOOT</term> 255 <listitem> 256 <para>Hotboot the GPS (UBX-CFG-RST).</para> 257 </listitem> 258 </varlistentry> 259 <varlistentry> 260 <term>MODEL</term> 261 <listitem> 262 <para>Configure the Dynamic Platform Model. (UBX-CFG-NAV5). 263</para> 264 </listitem> 265 </varlistentry> 266 <varlistentry> 267 <term>PMS</term> 268 <listitem> 269 <para>Set power management settings (UBX-CFG-PMS).</para> 270 </listitem> 271 </varlistentry> 272 <varlistentry> 273 <term>RESET</term> 274 <listitem> 275 <para>Reset configuration to defaults (UBX-CFG-CFG).</para> 276 </listitem> 277 </varlistentry> 278 <varlistentry> 279 <term>SAVE</term> 280 <listitem> 281 <para>Save current configuration (UBX-CFG-CFG).</para> 282 </listitem> 283 </varlistentry> 284 <varlistentry> 285 <term>MON-RESETODO</term> 286 <listitem> 287 <para>Reset the odometer (UBX-MON-RESETODO).</para> 288 </listitem> 289 </varlistentry> 290 <varlistentry> 291 <term>MON-VER</term> 292 <listitem> 293 <para>Poll GPS version (UBX-MON-VER).</para> 294 </listitem> 295 </varlistentry> 296 <varlistentry> 297 <term>WARMBOOT</term> 298 <listitem> 299 <para>Warmboot the GPS (UBX-CFG-RST).</para> 300 </listitem> 301 </varlistentry> 302 </variablelist> 303 <para>The PRESET parameters not shown above are all simple poll 304commands. They merely poll the GPS to respond with the associated 305message. For example "ubxtool -p CFG-GNSS" asks the GPS to respond with 306a UBX-CFG-GNSS message describing the current GNSS configuration. 307Increase the verbosity of the decode by adding the "-v 2" or "-v 3" 308options.</para> 309 </listitem> 310 </varlistentry> 311 <varlistentry> 312 <term>-R RAW</term> 313 <listitem> 314 <para>Save all raw serial data received from the GPS into the 315 file RAW.</para> 316 </listitem> 317 </varlistentry> 318 <varlistentry> 319 <term>-r</term> 320 <listitem> 321 <para>Read only. Do not send anything to the GPS.</para> 322 </listitem> 323 </varlistentry> 324 <varlistentry> 325 <term>-S SPEED</term> 326 <listitem> 327 <para>Set the GPS serial port speed to SPEED bps.</para> 328 </listitem> 329 </varlistentry> 330 <varlistentry> 331 <term>-s SPEED</term> 332 <listitem> 333 <para>Set local serial port speed to SPEED bps. Default 9,600 bps.</para> 334 </listitem> 335 </varlistentry> 336 <varlistentry> 337 <term>-V</term> 338 <listitem> 339 <para>Print <application>ubxtool</application> version and exit.</para> 340 </listitem> 341 </varlistentry> 342 <varlistentry> 343 <term>-v VERBOSITY</term> 344 <listitem> 345 <para>Set verbosity level to VERBOSITY. Verbosity can be from 0 346 (very quiet), 2 (decode messages), to 4 (very noisy). Default 1.</para> 347 </listitem> 348 </varlistentry> 349 <varlistentry> 350 <term>-w WAIT</term> 351 <listitem> 352 <para>Wait for WAIT seconds before exiting. Default 2 seconds.</para> 353 </listitem> 354 </varlistentry> 355 <varlistentry> 356 <term>-x ITEM</term> 357 <listitem> 358 <para>Delete the value of ITEM name from the GPS (UBX_CFG-VALDEL). 359 Returning to the GPS default for that item. See the section on 360 CONFIGURATION ITEMS</para> 361 </listitem> 362 </varlistentry> 363 <varlistentry> 364 <term>-z ITEM,VAL</term> 365 <listitem> 366 <para>Set the value of ITEM name to VAL in the GPS (UBX-CFG-VALSET). 367 See the section on CONFIGURATION ITEMS</para> 368 </listitem> 369 </varlistentry> 370 <varlistentry> 371 <term>[server[:port[:device]]]</term> 372 <listitem> 373 <para> 374 By default, <application>ubxtool</application> collects data 375 from all compatible devices on localhost, using the default GPSD 376 port 2947. An optional argument may specify a server to get data 377 from. A colon-separated suffix is taken as a port number. If 378 there is a second colon-separated suffix, that is taken as a 379 specific device name to be watched. Further details on the 380<citerefentry> 381 <refentrytitle>gps</refentrytitle> 382 <manvolnum>1</manvolnum> 383 </citerefentry> man page. 384 </para> 385 </listitem> 386 </varlistentry> 387 </variablelist> 388 </refsect1> 389 <refsect1 id='configitems'> 390 <title>CONFIGURATION ITEMS</title> 391 <para>Configuring u-blox GPS with the traditional configuration 392messages is fraught with problems. Many configuration messages 393interact in odd ways. Something as simple as changing the serial 394port speed requires you to read the curent configuration using 395UBX-CFG-PRT for the proper port, merging in the change, the 396writing back the changed UBX-CFG-PRT message. Or just guessing 397at the current configuration and overwriting it all.</para> 398 <para>The u-blox 9 series, protocol version 27+, tries, but does 399not completely succeed, to solve the problem with Configuration 400Items. If your GPS does not support protocol version 27+, then 401this section does not apply to you.</para> 402 <para>Most of the configuration variables in the GPS have been 403assigned a 32-bit Key ID. Each Key ID has been assigned a Key Name. 404Over 600 Key Names are supported by ubxtool. To see them all do: 405"ubxtool -h -v 3". Each Key references one specific value.</para> 406 <para>To get the value related to an item, use "-g ITEM".</para> 407 <para>To reset the value related to an item to it default value, use 408"-x ITEM".</para> 409 <para>To set an ITEM name to a value, use "-z ITEM,VAL".</para> 410 <para>See the EXAMPLES section for concrete examples.</para> 411 </refsect1> 412 <refsect1 id='examples'> 413 <title>EXAMPLES</title> 414 <para> 415Decode raw log file: 416<programlisting> 417ubxtool -r -f ublox-neo-m8n.log 418</programlisting> 419 </para> 420 <para> 421Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps: 422<programlisting> 423ubxtool -S 230400 -f /dev/ttyAMA0 424</programlisting> 425 </para> 426 <para> 427Watch entire GPS reset cycle, include $GPTXT messages: 428<programlisting> 429ubxtool -p COLDBOOT -w 20 -v 2 430</programlisting> 431 </para> 432 <para> 433Poll Enabled Constellations: 434<programlisting> 435ubxtool -p CFG-GNSS 436</programlisting> 437Dump gpsd data from a remote server named x.example.com: 438<programlisting> 439ubxtool -w 5 x.example.com 440</programlisting> 441 </para> 442 <refsect2> 443 <title>Version 27+ examples</title> 444 <para>The following examples require a GPS supporting protocol 27 or 445 greater.</para> 446 <para>To check the current dynamic model, change it to 6 (AIR1, Airborne 447 with <1g acceleration), revert to the default setting, and verify the 448 faults was restored.</para> 449<programlisting> 450$ ubxtool -g CFG-NAVSPG-DYNMODEL 451[...] 452UBX-CFG-VALGET: 453 version 1 layer 0 reserved 0,0 454 layers (ram) 455 item CFG-NAVSPG-DYNMODEL/0x20110021 val 2 456[...] 457$ ubxtool -z CFG-NAVSPG-DYNMODEL,6 458[...] 459UBX-ACK-ACK: 460 ACK to Class x6 (CFG) ID x8a (VALSET) 461[...] 462$ ubxtool -g CFG-NAVSPG-DYNMODEL 463[...] 464UBX-CFG-VALGET: 465 version 1 layer 0 reserved 0,0 466 layers (ram) 467 item CFG-NAVSPG-DYNMODEL/0x20110021 val 6 468[...] 469$ ubxtool -x CFG-NAVSPG-DYNMODEL 470[...] 471UBX-ACK-ACK: 472 ACK to Class x6 (CFG) ID x8c (VALDEL) 473[...] 474$ ubxtool -g CFG-NAVSPG-DYNMODEL 475[...] 476UBX-CFG-VALGET: 477 version 1 layer 0 reserved 0,0 478 layers (ram) 479 item CFG-NAVSPG-DYNMODEL/0x20110021 val 6 480</programlisting> 481 <para>Notice that the current DYNMODEL stayed at 6 (AIR1). The 482 "-x" only affects the saved setting, not the current setting. To 483 change the current setting you must set it with "-z".</para> 484 </refsect2> 485 </refsect1> 486 <refsect1 id='environment'> 487 <title>ENVIRONMENT</title> 488 <para>Options can be placed in the UBXOPTS environment variable. 489UBXOPTS is processed before the CLI options.</para> 490 </refsect1> 491 <refsect1 id='see_also'> 492 <title>SEE ALSO</title> 493 <para> 494 <application>ubxtool</application> is written to conform to the official 495u-blox documentation for the u-blox binary protocol. 496<ulink url="https://www.u-blox.com/en/product-resources"></ulink></para> 497 <para> 498 <citerefentry> 499 <refentrytitle>cgps</refentrytitle> 500 <manvolnum>1</manvolnum> 501 </citerefentry>, 502 <citerefentry> 503 <refentrytitle>gpscat</refentrytitle> 504 <manvolnum>1</manvolnum> 505 </citerefentry>, 506 <citerefentry> 507 <refentrytitle>gpsctl</refentrytitle> 508 <manvolnum>1</manvolnum> 509 </citerefentry>, 510 <citerefentry> 511 <refentrytitle>gpsfake</refentrytitle> 512 <manvolnum>1</manvolnum> 513 </citerefentry>, 514 <citerefentry> 515 <refentrytitle>xgps</refentrytitle> 516 <manvolnum>1</manvolnum> 517 </citerefentry>, 518 <citerefentry> 519 <refentrytitle>gpsd</refentrytitle> 520 <manvolnum>8</manvolnum> 521 </citerefentry>, 522</para> 523 </refsect1> 524 <refsect1 id='maintainer'> 525 <title>AUTHOR</title> 526 <para>Gary E. Miller<email>gem@rellim.com</email> 527 </para> 528 </refsect1> 529</refentry> 530