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.

gpsctl.xml 12 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391
  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  2. <!--
  3. This file is Copyright 2010 by the GPSD project
  4. SPDX-License-Identifier: BSD-2-clause
  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='gpsctl.1'>
  10. <refentryinfo>
  11. <date>6 December 2020</date>
  12. </refentryinfo>
  13. <refmeta>
  14. <refentrytitle>gpsctl</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>gpsctl</refname>
  21. <refpurpose>control the modes of a GPS</refpurpose>
  22. </refnamediv>
  23. <refsynopsisdiv id='synopsis'>
  24. <cmdsynopsis>
  25. <command>gpsctl</command>
  26. <group>
  27. <arg choice='plain'>-?</arg>
  28. <arg choice='plain'>--binary</arg>
  29. <arg choice='plain'>--nmea</arg>
  30. <arg choice='plain'>--reset</arg>
  31. </group>
  32. <arg choice='opt'>--debug <replaceable>LVL</replaceable>
  33. </arg>
  34. <arg choice='opt'>--direct </arg>
  35. <arg choice='opt'>--echo </arg>
  36. <arg choice='opt'>--help </arg>
  37. <arg choice='opt'>--list </arg>
  38. <arg choice='opt'>--rate </arg>
  39. <arg choice='opt'>--rmshm </arg>
  40. <arg choice='opt'>--rate <replaceable>rate</replaceable>
  41. </arg>
  42. <arg choice='opt'>--ship <replaceable>control</replaceable>
  43. </arg>
  44. <arg choice='opt'>--speed <replaceable>speed</replaceable>
  45. </arg>
  46. <arg choice='opt'>--timeout <replaceable>devicetype</replaceable>
  47. </arg>
  48. <arg choice='opt'>--version </arg>
  49. <group>
  50. <arg choice='plain'>-b</arg>
  51. <arg choice='plain'>-n</arg>
  52. <arg choice='plain'>-r</arg>
  53. </group>
  54. <arg choice='opt'>-D <replaceable>LVL</replaceable>
  55. </arg>
  56. <arg choice='opt'>-c <replaceable>rate</replaceable>
  57. </arg>
  58. <arg choice='opt'>-e </arg>
  59. <arg choice='opt'>-f </arg>
  60. <arg choice='opt'>-h </arg>
  61. <arg choice='opt'>-l </arg>
  62. <arg choice='opt'>-R </arg>
  63. <arg choice='opt'>-s <replaceable>speed</replaceable>
  64. </arg>
  65. <arg choice='opt'>-t <replaceable>devicetype</replaceable>
  66. </arg>
  67. <arg choice='opt'>-V </arg>
  68. <arg choice='opt'>-x <replaceable>control</replaceable>
  69. </arg>
  70. <arg choice='opt'>
  71. <replaceable>serial-port</replaceable>
  72. </arg>
  73. </cmdsynopsis>
  74. </refsynopsisdiv>
  75. <refsect1 id='description'>
  76. <title>DESCRIPTION</title>
  77. <para>
  78. <application>gpsctl</application> can switch a dual-mode GPS
  79. between NMEA and vendor-binary modes. It can also be used to set the
  80. device baud rate. Note: Not all devices have these capabilities.</para>
  81. <para>If you have only one GPS attached to your machine, and gpsd is
  82. running, it is not necessary to specify the device;
  83. <application>gpsctl</application> does its work through
  84. <application>gpsd</application>, which will locate it for you.</para>
  85. <para>When <application>gpsd</application> is not running, the device
  86. specification is required, and you will need to be running as root or
  87. be a member of the device's owning group in order to have write access
  88. to the device. On many Unix variants the owning group will be named
  89. 'dialout'.</para>
  90. <para>The program accepts the following options:</para>
  91. <variablelist remap='TP'>
  92. <varlistentry>
  93. <term>
  94. <option>-?</option>
  95. </term>
  96. <term>
  97. <option>-h</option>
  98. </term>
  99. <term>
  100. <option>--help</option>
  101. </term>
  102. <listitem>
  103. <para>Display program usage and exit.</para>
  104. </listitem>
  105. </varlistentry>
  106. <varlistentry>
  107. <term>
  108. <option>-b</option>
  109. </term>
  110. <term>
  111. <option>--binary</option>
  112. </term>
  113. <listitem>
  114. <para>Put the GPS into native (binary) mode.</para>
  115. </listitem>
  116. </varlistentry>
  117. <varlistentry>
  118. <term>
  119. <option>-c RATE</option>
  120. </term>
  121. <term>
  122. <option>--rate RATE</option>
  123. </term>
  124. <listitem>
  125. <para>Change the GPS's cycle time. Units are seconds. Note, most
  126. GPSes have a fixed cycle time of 1 second.</para>
  127. </listitem>
  128. </varlistentry>
  129. <varlistentry>
  130. <term>
  131. <option>-D LVL</option>
  132. </term>
  133. <term>
  134. <option>--debug LVL</option>
  135. </term>
  136. <listitem>
  137. <para>Set level of debug messages.</para>
  138. </listitem>
  139. </varlistentry>
  140. <varlistentry>
  141. <term>
  142. <option>-e</option>
  143. </term>
  144. <term>
  145. <option>--echo</option>
  146. </term>
  147. <listitem>
  148. <para>Generate the packet from any other arguments specified and ship
  149. it to standard output instead of the device. This switch can be used
  150. with the <option>-t</option> option without specifying a device. Note:
  151. the packet data for a binary prototype will be raw, not ASCII-ized in
  152. any way.</para>
  153. </listitem>
  154. </varlistentry>
  155. <varlistentry>
  156. <term>
  157. <option>-f</option>
  158. </term>
  159. <term>
  160. <option>--force</option>
  161. </term>
  162. <listitem>
  163. <para>Force low-level access (not through the daemon).</para>
  164. </listitem>
  165. </varlistentry>
  166. <varlistentry>
  167. <term>
  168. <option>-l</option>
  169. </term>
  170. <term>
  171. <option>--list</option>
  172. </term>
  173. <listitem>
  174. <para>List a table showing which option switches can be applied
  175. to which device types, and exit.</para>
  176. </listitem>
  177. </varlistentry>
  178. <varlistentry>
  179. <term>
  180. <option>-n</option>
  181. </term>
  182. <term>
  183. <option>--nmea</option>
  184. </term>
  185. <listitem>
  186. <para>Put GPS into NMEA mode.</para>
  187. </listitem>
  188. </varlistentry>
  189. <varlistentry>
  190. <term>
  191. <option>-r</option>
  192. </term>
  193. <term>
  194. <option>--reset</option>
  195. </term>
  196. <listitem>
  197. <para>Reset the GPS. Device port and type must be specified.</para>
  198. </listitem>
  199. </varlistentry>
  200. <varlistentry>
  201. <term>
  202. <option>-R</option>
  203. </term>
  204. <term>
  205. <option>--rmshm</option>
  206. </term>
  207. <listitem>
  208. <para>Remove the GPSD shared-memory segment used for SHM export. This
  209. option will normally only be of interest to GPSD developers.</para>
  210. </listitem>
  211. </varlistentry>
  212. <varlistentry>
  213. <term>
  214. <option>-s SPEED</option>
  215. </term>
  216. <term>
  217. <option>--speed SPEED</option>
  218. </term>
  219. <listitem>
  220. <para>Set the baud rate at which the GPS emits packets.</para>
  221. <para>Use this option with caution. On USB and Bluetooth GPSes it is
  222. also possible for serial mode setting to fail either because the
  223. serial adaptor chip does not support non-8N1 modes or because the
  224. device firmware does not properly synchronize the serial adaptor chip
  225. with the UART on the GPS chipset when the speed changes. These
  226. failures can hang your device, possibly requiring a GPS power cycle or (in
  227. extreme cases) physically disconnecting the NVRAM backup battery.</para>
  228. </listitem>
  229. </varlistentry>
  230. <varlistentry>
  231. <term>
  232. <option>-t TYPE</option>
  233. </term>
  234. <term>
  235. <option>--type TYPE</option>
  236. </term>
  237. <listitem>
  238. <para>Force the device type.</para>
  239. </listitem>
  240. </varlistentry>
  241. <varlistentry>
  242. <term>
  243. <option>-T TIMEOUT</option>
  244. </term>
  245. <term>
  246. <option>--timeout TIMEOUT</option>
  247. </term>
  248. <listitem>
  249. <para>Change the sampling timeout. Defaults to 8 seconds, which should
  250. always be sufficient to get an identifying packet from a device
  251. emitting at the normal rate of 1 per second.</para>
  252. </listitem>
  253. </varlistentry>
  254. <varlistentry>
  255. <term>
  256. <option>-V</option>
  257. </term>
  258. <term>
  259. <option>--version</option>
  260. </term>
  261. <listitem>
  262. <para>Display program version and exit.</para>
  263. </listitem>
  264. </varlistentry>
  265. <varlistentry>
  266. <term>
  267. <option>-x STR</option>
  268. </term>
  269. <term>
  270. <option>--ship STR</option>
  271. </term>
  272. <listitem>
  273. <para>Send a specified control string to the GPS;
  274. <application>gpsctl</application> will provide packet headers and
  275. trailers and checksum as appropriate for binary packet types, and
  276. whatever checksum and trailer is required for text packet types. (You
  277. must include the leading $ for NMEA packets.) When sending to a UBX
  278. device, the first two bytes of the string supplied will become the
  279. message class and type, and the remainder the payload. When sending to
  280. a Navcom NCT or Trimble TSIP device, the first byte is interpreted as
  281. the command ID and the rest as payload. When sending to a Zodiac
  282. device, the first two bytes are used as a message ID of type
  283. little-endian short, and the remainder as payload in byte pairs
  284. interpreted as little-endian short. For all other supported binary
  285. GPSes (notably including SiRF) the string is taken as the entire
  286. message payload and wrapped with appropriate header, trailer and
  287. checksum bytes. C-style backslash escapes in the string, notably \xNN
  288. for hex, will be interpreted; additionally, \e will be replaced with
  289. ESC. This switch implies <option>-f</option>.</para>
  290. </listitem>
  291. </varlistentry>
  292. </variablelist>
  293. <para>The argument of the forcing option, <option>-t</option>, should be a
  294. string which is contained in exactly one of the known driver
  295. names; for a list, do <command>gpsctl -l</command>.</para>
  296. <para>Forcing the device type behaves somewhat differently depending
  297. on whether this tool is going through the daemon or not. In high-level
  298. mode, if the device that daemon selects for you doesn't match the
  299. driver you specified, <application>gpsctl</application> exits with
  300. a warning. (This may be useful in scripts.)</para>
  301. <para>In low-level mode, if the device identifies as a Generic NMEA,
  302. use the selected driver instead. This will be useful if you have a
  303. GPS device of known type that is in NMEA mode and not responding to
  304. probes. (This option was originally implemented for talking to
  305. SiRFStar I chips, which don't respond to the normal SiRF ID
  306. probe.)</para>
  307. <para>If no options are given, the program will display a message
  308. identifying the GPS type of the selected device and exit.</para>
  309. <para>Reset (<option>-r</option>) operations must stand alone; others can be combined.
  310. Multiple options will be executed in this order: mode changes (<option>-b</option> and
  311. -<option>n</option>) first, speed changes (<option>-s</option>) second, and control-string sends (<option>-c</option>)
  312. last.</para>
  313. </refsect1>
  314. <refsect1 id='environment'>
  315. <title>ENVIRONMENT VARIABLES</title>
  316. <para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>,
  317. you can control the key value used to designate the shared-memory
  318. segment removed with the -R option. This will be useful mainly when
  319. isolating test instances of <application>gpsd</application> from
  320. production ones.</para>
  321. </refsect1>
  322. <refsect1 id='examples'>
  323. <title>EXAMPLES</title>
  324. <variablelist>
  325. <varlistentry>
  326. <term>
  327. <command>gpsctl /dev/ttyUSB0</command>
  328. </term>
  329. <listitem>
  330. <para>Attempt to identify the device on USB serial device 0. Time out
  331. after the default number of seconds. Adding the <option>-f</option> will
  332. force low-level access and suppress the normal complaint when this
  333. tool can't find a GPSD to work through.</para>
  334. </listitem>
  335. </varlistentry>
  336. <varlistentry>
  337. <term>gpsctl -f -n -s 9600 /dev/ttyUSB0</term>
  338. <listitem>
  339. <para>Use low-level operations (not going through a gpsd instance) to
  340. switch a GPS to NMEA mode at 9600bps. The tool will identify the
  341. GPS type itself.</para>
  342. </listitem>
  343. </varlistentry>
  344. </variablelist>
  345. </refsect1>
  346. <refsect1 id='bugs'>
  347. <title>BUGS</title>
  348. <para>SiRF GPSes can only be identified by the success of an attempt
  349. to flip them into SiRF binary mode. Thus, the process of probing one of
  350. these running in NMEA will change its behavior.</para>
  351. <para>Baud rate and mode changes work in direct mode but are not
  352. reliable in client mode. This will be fixed in a future release.</para>
  353. </refsect1>
  354. <refsect1 id='see_also'>
  355. <title>SEE ALSO</title>
  356. <para>
  357. <citerefentry>
  358. <refentrytitle>gpsd</refentrytitle>
  359. <manvolnum>8</manvolnum>
  360. </citerefentry>,
  361. <citerefentry>
  362. <refentrytitle>gpsdctl</refentrytitle>
  363. <manvolnum>8</manvolnum>
  364. </citerefentry>,
  365. <citerefentry>
  366. <refentrytitle>gps</refentrytitle>
  367. <manvolnum>1</manvolnum>
  368. </citerefentry>,
  369. <citerefentry>
  370. <refentrytitle>libgps</refentrytitle>
  371. <manvolnum>3</manvolnum>
  372. </citerefentry>,
  373. <citerefentry>
  374. <refentrytitle>libgpsmm</refentrytitle>
  375. <manvolnum>3</manvolnum>
  376. </citerefentry>,
  377. <citerefentry>
  378. <refentrytitle>gpsprof</refentrytitle>
  379. <manvolnum>1</manvolnum>
  380. </citerefentry>,
  381. <citerefentry>
  382. <refentrytitle>gpsfake</refentrytitle>
  383. <manvolnum>1</manvolnum>
  384. </citerefentry>.
  385. </para>
  386. </refsect1>
  387. <refsect1 id='maintainer'>
  388. <title>AUTHOR</title>
  389. <para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para>
  390. </refsect1>
  391. </refentry>