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 &lt;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