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.

183 lines
7.5 KiB

  1. '\" t
  2. .\" Title: gpsctl
  3. .\" Author: [see the "AUTHOR" section]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.1 <>
  5. .\" Date: 29 Oct 2006
  6. .\" Manual: GPSD Documentation
  7. .\" Source: The GPSD Project
  8. .\" Language: English
  9. .\"
  10. .TH "GPSCTL" "1" "29 Oct 2006" "The GPSD Project" "GPSD Documentation"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\"
  16. .\"
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. gpsctl \- control the modes of a GPS
  32. .SH "SYNOPSIS"
  33. .HP \w'\fBgpsctl\fR\ 'u
  34. \fBgpsctl\fR [\-h] [\-b | \-n | \-r] [\-x\ \fIcontrol\fR] [\-e] [\-f] [\-l] [\-s\ \fIspeed\fR] [\-t\ \fIdevicetype\fR] [\-R] [\-D\ \fIdebuglevel\fR] [\-V] [\fIserial\-port\fR]
  36. .PP
  37. gpsctl
  38. can switch a dual\-mode GPS between NMEA and vendor\-binary modes\&. It can also be used to set the device baudrate\&. Note: Not all devices have these capabilities\&.
  39. .PP
  40. If you have only one GPS attached to your machine, and gpsd is running, it is not necessary to specify the device;
  41. gpsctl
  42. does its work through
  43. gpsd, which will locate it for you\&.
  44. .PP
  45. When
  46. gpsd
  47. is not running, the device specification is required, and you will need to be running as root or be a member of the device\*(Aqs owning group in order to have write access to the device\&. On many Unix variants the owning group will be named \*(Aqdialout\*(Aq\&.
  48. .PP
  49. The program accepts the following options:
  50. .PP
  51. \-b
  52. .RS 4
  53. Put the GPS into native (binary) mode\&.
  54. .RE
  55. .PP
  56. \-c
  57. .RS 4
  58. Change the GPS\*(Aqs cycle time\&. Units are seconds\&. Note, most GPSes have a fixed cycle time of 1 second\&.
  59. .RE
  60. .PP
  61. \-e
  62. .RS 4
  63. Generate the packet from any other arguments specified and ship it to standard output instead of the device\&. This switch can be used with the
  64. \fB\-t\fR
  65. option without specifying a device\&. Note: the packet data for a binary prototype will be raw, not ASCII\-ized in any way\&.
  66. .RE
  67. .PP
  68. \-f
  69. .RS 4
  70. Force low\-level access (not through the daemon)\&.
  71. .RE
  72. .PP
  73. \-l
  74. .RS 4
  75. List a table showing which option switches can be applied to which device types, and exit\&.
  76. .RE
  77. .PP
  78. \-n
  79. .RS 4
  80. Put GPS into NMEA mode\&.
  81. .RE
  82. .PP
  83. \-r
  84. .RS 4
  85. Reset the GPS\&. Device port and type must be specified\&.
  86. .RE
  87. .PP
  88. \-s
  89. .RS 4
  90. Set the baud rate at which the GPS emits packets\&.
  91. .sp
  92. Use this option with caution\&. On USB and Bluetooth GPSes it is also possible for serial mode setting to fail either because the serial adaptor chip does not support non\-8N1 modes or because the device firmware does not properly synchronize the serial adaptor chip with the UART on the GPS chipset when the speed changes\&. These failures can hang your device, possibly requiring a GPS power cycle or (in extreme cases) physically disconnecting the NVRAM backup battery\&.
  93. .RE
  94. .PP
  95. \-t
  96. .RS 4
  97. Force the device type\&.
  98. .RE
  99. .PP
  100. \-x
  101. .RS 4
  102. Send a specified control string to the GPS;
  103. gpsctl
  104. will provide packet headers and trailers and checksum as appropriate for binary packet types, and whatever checksum and trailer is required for text packet types\&. (You must include the leading $ for NMEA packets\&.) When sending to a UBX device, the first two bytes of the string supplied will become the message class and type, and the remainder the payload\&. When sending to a Navcom NCT or Trimble TSIP device, the first byte is interpreted as the command ID and the rest as payload\&. When sending to a Zodiac device, the first two bytes are used as a message ID of type little\-endian short, and the remainder as payload in byte pairs interpreted as little\-endian short\&. For all other supported binary GPSes (notably including SiRF) the string is taken as the entire message payload and wrapped with appropriate header, trailer and checksum bytes\&. C\-style backslash escapes in the string, notably \exNN for hex, will be interpreted; additionally, \ee will be replaced with ESC\&. This switch implies
  105. \fB\-f\fR\&.
  106. .RE
  107. .PP
  108. \-T
  109. .RS 4
  110. Change the sampling timeout\&. Defaults to 8 seconds, which should always be sufficient to get an identifying packet from a device emitting at the normal rate of 1 per second\&.
  111. .RE
  112. .PP
  113. \-R
  114. .RS 4
  115. Remove the GPSD shared\-memory segment used for SHM export\&. This option will normally only be of interest to GPSD developers\&.
  116. .RE
  117. .PP
  118. \-h
  119. .RS 4
  120. Display program usage and exit\&.
  121. .RE
  122. .PP
  123. \-D
  124. .RS 4
  125. Set level of debug messages\&.
  126. .RE
  127. .PP
  128. \-V
  129. .RS 4
  130. Display program version and exit\&.
  131. .RE
  132. .PP
  133. The argument of the forcing option,
  134. \fB\-t\fR, should be a string which is contained in exactly one of the known driver names; for a list, do
  135. \fBgpsctl \-l\fR\&.
  136. .PP
  137. Forcing the device type behaves somewhat differently depending on whether this tool is going through the daemon or not\&. In high\-level mode, if the device that daemon selects for you doesn\*(Aqt match the driver you specified,
  138. gpsctl
  139. exits with a warning\&. (This may be useful in scripts\&.)
  140. .PP
  141. In low\-level mode, if the device identifies as a Generic NMEA, use the selected driver instead\&. This will be useful if you have a GPS device of known type that is in NMEA mode and not responding to probes\&. (This option was originally implemented for talking to SiRFStar I chips, which don\*(Aqt respond to the normal SiRF ID probe\&.)
  142. .PP
  143. If no options are given, the program will display a message identifying the GPS type of the selected device and exit\&.
  144. .PP
  145. Reset (\-r) operations must stand alone; others can be combined\&. Multiple options will be executed in this order: mode changes (\-b and \-n) first, speed changes (\-s) second, and control\-string sends (\-c) last\&.
  147. .PP
  148. By setting the environment variable
  149. \fBGPSD_SHM_KEY\fR, you can control the key value used to designate the shared\-memory segment removed with the \-R option\&. This will be useful mainly when isolating test instances of
  150. gpsd
  151. from production ones\&.
  152. .SH "EXAMPLES"
  153. .PP
  154. \fBgpsctl /dev/ttyUSB0\fR
  155. .RS 4
  156. Attempt to identify the device on USB serial device 0\&. Time out after the default number of seconds\&. Adding the
  157. \fB\-f\fR
  158. will force low\-level access and suppress the normal complaint when this tool can\*(Aqt find a GPSD to work through\&.
  159. .RE
  160. .PP
  161. gpsctl \-f \-n \-s 9600 /dev/ttyUSB0
  162. .RS 4
  163. Use low\-level operations (not going through a gpsd instance) to switch a GPS to NMEA mode at 9600bps\&. The tool will identify the GPS type itself\&.
  164. .RE
  165. .SH "BUGS"
  166. .PP
  167. SiRF GPSes can only be identified by the success of an attempt to flip them into SiRF binary mode\&. Thus, the process of probing one of these running in NMEA will change its behavior\&.
  168. .PP
  169. Baud rate and mode changes work in direct mode but are not reliable in client mode\&. This will be fixed in a future release\&.
  170. .SH "SEE ALSO"
  171. .PP
  172. \fBgpsd\fR(8),
  173. \fBgpsdctl\fR(8),
  174. \fBgps\fR(1),
  175. \fBlibgps\fR(3),
  176. \fBlibgpsmm\fR(3),
  177. \fBgpsprof\fR(1),
  178. \fBgpsfake\fR(1)\&.
  179. .SH "AUTHOR"
  180. .PP
  181. Eric S\&. Raymond
  182. <esr@thyrsus\&.com>\&.