From e5548e974f42f2080a74ed2a30d1e2927fe0ad9f Mon Sep 17 00:00:00 2001 From: "Gary E. Miller" Date: Mon, 19 Nov 2018 19:56:24 -0800 Subject: man: Move man pages, source and result, into main/ part of cleaning up the root directory. --- man/gpsctl.xml | 284 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 man/gpsctl.xml (limited to 'man/gpsctl.xml') diff --git a/man/gpsctl.xml b/man/gpsctl.xml new file mode 100644 index 00000000..b0f9f6c0 --- /dev/null +++ b/man/gpsctl.xml @@ -0,0 +1,284 @@ + + + + +29 Oct 2006 + +gpsctl +1 +The GPSD Project +GPSD Documentation + + +gpsctl +control the modes of a GPS + + + + + gpsctl + -h + + -b + -n + + -x control + -e + -f + -l + -s speed + -t devicetype + -R + -D debuglevel + -V + serial-port + + + +DESCRIPTION + +gpsctl 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. + +If you have only one GPS attached to your machine, and gpsd is +running, it is not necessary to specify the device; +gpsctl does its work through +gpsd, which will locate it for you. + +When gpsd is not running, the device +specification is required, and you will need to be running as root or +be a member of the device's owning group in order to have write access +to the device. On many Unix variants the owning group will be named +'dialout'. + +The program accepts the following options: + + + +-b + +Put the GPS into native (binary) mode. + + + + +-c + +Change the GPS's cycle time. Units are seconds. Note, most +GPSes have a fixed cycle time of 1 second. + + + + +-e + +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 option without specifying a device. Note: +the packet data for a binary prototype will be raw, not ASCII-ized in +any way. + + + + +-f + +Force low-level access (not through the daemon). + + + + +-l + +List a table showing which option switches can be applied +to which device types, and exit. + + + + +-n + +Put GPS into NMEA mode. + + + + +-s + +Set the baud rate at which the GPS emits packets. + +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. + + + + +-t + +Force the device type. + + + + +-x + +Send a specified control string to the GPS; +gpsctl 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 \xNN +for hex, will be interpreted; additionally, \e will be replaced with +ESC. This switch implies . + + + + +-T + +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. + + + + +-R + +Remove the GPSD shared-memory segment used for SHM export. This +option will normally only be of interest to GPSD developers. + + + + +-h + +Display program usage and exit. + + + + +-D + +Set level of debug messages. + + + + +-V + +Display program version and exit. + + + + +The argument of the forcing option, , should be a +string which is contained in exactly one of the known driver +names; for a list, do gpsctl -l. + +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't match the +driver you specified, gpsctl exits with +a warning. (This may be useful in scripts.) + +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't respond to the normal SiRF ID +probe.) + +If no options are given, the program will display a message +identifying the GPS type of the selected device and exit. + +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. + + + +ENVIRONMENT VARIABLES + +By setting the environment variable GPSD_SHM_KEY, +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 gpsd from +production ones. + + + +EXAMPLES + + + +gpsctl /dev/ttyUSB0 + +Attempt to identify the device on USB serial device 0. Time out +after the default number of seconds. Adding the will +force low-level access and suppress the normal complaint when this +tool can't find a GPSD to work through. + + + + +gpsctl -f -n -s 9600 /dev/ttyUSB0 + +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. + + + + + + +BUGS + +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. + +Baud rate and mode changes work in direct mode but are not +reliable in client mode. This will be fixed in a future release. + + + +SEE ALSO + +gpsd8, +gpsdctl8, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + -- cgit v1.2.1