Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GPSCTL(1)		      GPSD Documentation		     GPSCTL(1)

       gpsctl -	control	the modes of a GPS

       gpsctl [-h] [-b | -n | -r] [-x control] [-e] [-f] [-l] [-s speed]
	      [-t devicetype] [-R] [-D debuglevel] [-V]	[serial-port]

       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:

	   Put the GPS into native (binary) mode.

	   Change the GPS's cycle time.	Units are seconds. Note, most GPSes
	   have	a fixed	cycle time of 1	second.

	   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 -t option without specifying a device. Note: the packet
	   data	for a binary prototype will be raw, not	ASCII-ized in any way.

	   Force low-level access (not through the daemon).

	   List	a table	showing	which option switches can be applied to	which
	   device types, and exit.

	   Put GPS into	NMEA mode.

	   Reset the GPS. Device port and type must be specified.

	   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.

	   Force the device type.

	   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 -f.

	   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.

	   Remove the GPSD shared-memory segment used for SHM export. This
	   option will normally	only be	of interest to GPSD developers.

	   Display program usage and exit.

	   Set level of	debug messages.

	   Display program version and exit.

       The argument of the forcing option, -t, 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)

       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.

       gpsctl /dev/ttyUSB0
	   Attempt to identify the device on USB serial	device 0. Time out
	   after the default number of seconds.	Adding the -f 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.

       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.

       gpsd(8),	gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),

       Eric S. Raymond <>.

The GPSD Project		  29 Oct 2006			     GPSCTL(1)


Want to link to this manual page? Use this URL:

home | help