Devuan fork of gpsd
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

530 lines
17 KiB

  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  2. <!--
  3. This file is Copyright (c) 2018 by the GPSD project
  4. BSD 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.
  53. If 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.
  55. To understand <application>ubxtool</application> you must first be familiar
  56. with your u-blox GPS and the documentation for the u-blox binary protocol.
  57. The u-blox protocol varies greatly depending on GPS model and firmware
  58. revision. 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
  63. generated commands to the GPS. It can read binary messages from a file. It
  64. can read and write directly through a serial device, or through a
  65. running 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
  75. a 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,
  82. a comma-separated list of hexadecimal bytes specifying the class, the ID,
  83. and 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,
  91. the 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
  134. and 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
  141. GBS, 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,
  187. the option to enable. -e accepts the same OPTIONs as -d, except the action
  188. is 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,
  196. the file or device to open. Files are opened read-only. Character
  197. devices are opened read/write, unless the -r parameter is given.
  198. Requires 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
  213. a 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.
  234. Minimum 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,
  243. the name of the command to send. Only the common PRESETS are shown here.
  244. To 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
  304. commands. They merely poll the GPS to respond with the associated
  305. message. For example "ubxtool -p CFG-GNSS" asks the GPS to respond with
  306. a UBX-CFG-GNSS message describing the current GNSS configuration.
  307. Increase the verbosity of the decode by adding the "-v 2" or "-v 3"
  308. options.</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
  392. messages is fraught with problems. Many configuration messages
  393. interact in odd ways. Something as simple as changing the serial
  394. port speed requires you to read the curent configuration using
  395. UBX-CFG-PRT for the proper port, merging in the change, the
  396. writing back the changed UBX-CFG-PRT message. Or just guessing
  397. at the current configuration and overwriting it all.</para>
  398. <para>The u-blox 9 series, protocol version 27+, tries, but does
  399. not completely succeed, to solve the problem with Configuration
  400. Items. If your GPS does not support protocol version 27+, then
  401. this section does not apply to you.</para>
  402. <para>Most of the configuration variables in the GPS have been
  403. assigned a 32-bit Key ID. Each Key ID has been assigned a Key Name.
  404. Over 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>
  415. Decode raw log file:
  416. <programlisting>
  417. ubxtool -r -f ublox-neo-m8n.log
  418. </programlisting>
  419. </para>
  420. <para>
  421. Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:
  422. <programlisting>
  423. ubxtool -S 230400 -f /dev/ttyAMA0
  424. </programlisting>
  425. </para>
  426. <para>
  427. Watch entire GPS reset cycle, include $GPTXT messages:
  428. <programlisting>
  429. ubxtool -p COLDBOOT -w 20 -v 2
  430. </programlisting>
  431. </para>
  432. <para>
  433. Poll Enabled Constellations:
  434. <programlisting>
  435. ubxtool -p CFG-GNSS
  436. </programlisting>
  437. Dump gpsd data from a remote server named x.example.com:
  438. <programlisting>
  439. ubxtool -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. [...]
  452. UBX-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. [...]
  459. UBX-ACK-ACK:
  460. ACK to Class x6 (CFG) ID x8a (VALSET)
  461. [...]
  462. $ ubxtool -g CFG-NAVSPG-DYNMODEL
  463. [...]
  464. UBX-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. [...]
  471. UBX-ACK-ACK:
  472. ACK to Class x6 (CFG) ID x8c (VALDEL)
  473. [...]
  474. $ ubxtool -g CFG-NAVSPG-DYNMODEL
  475. [...]
  476. UBX-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.
  489. UBXOPTS 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
  495. u-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>