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

FreeBSD Manual Pages


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

       gpsmon -	real-time GPS packet monitor and control utility

       gpsmon [-L] [-V]	[-h] [-n] [-a] [-l logfile] [-t	driver-prefix]
	      [[ server	[:port [:device]] | device]] [-D debuglevel]

       gpsmon is a monitor that	watches	packets	coming from a GPS and displays
       them along with diagnostic information. It supports commands that can
       be used to tweak	GPS settings in	various	ways; some are
       device-independent, some	vary with the GPS chipset type.	It will	behave
       sanely, just dumping packets, when connected to a GPS type it knows
       nothing about.

       gpsmon differs from a navigation	client in that it mostly dumps raw
       data from the GPS, with only enough data-massaging to allow checks
       against expected	output.	In particular, this tool does not do any
       interpolation or	modeling to derive climb/sink or error estimates. Nor
       does it discard altitude	reports	when the fix quality is	too low.

       Unlike gpsd, gpsmon never writes	control	or probe strings to the	device
       unless you explicitly tell it to. Thus, while it	will auto-sync to
       binary packet types, it won't automatically recognize a device shipping
       an extended NMEA	protocol as anything other than	a plain	NMEA device.
       Use the -t option or the	t to work around this.

       gpsmon is a designed to run in a	terminal emulator with a minimum 25x80
       size; the non-GUI interface is a	design choice made to accommodate
       users operating in constrained environments and over telnet or ssh
       connections. If run in a	larger window, the size	of the packet-log
       window will be increased	to fit.

       gpsmon accepts an -h option that	displays a usage message, or a -V
       option to dump the package version and exit.

       This program may	be run in either of two	modes, as a client for the
       gpsd daemon (and	its associated control socket) or directly connected
       to a specified serial device. When run with no argument,	it attempts to
       connect to the daemon. If the argument begins with a server:port
       specification it	will also attempt to connect to	the daemon. If the
       argument	looks like a bare server name it will attempt to connect to a
       daemon running on the default gpsd port on that server. Only if the
       device argument contains	slashes	but no colons will it be treated as a
       serial device for direct	connection. In direct-connect mode gpsmon will
       hunt for	a correct baud rate and	lock on	to it automatically. Possible
       cases look like this:

	   Look	at the default port of localhost, trying both IPv4 and IPv6
	   and watching	output from serial device 1.
	   Look	at port	2317 on, trying both IPv4 and IPv6.
	   Look	at port	2317 at	the specified IPv4 address, collecting data
	   from	attached serial	device 3.

	   Look	at port	2317 at	the specified IPv6 address, collecting data
	   from	attached serial	device 5.

       Unlike gpsd, gpsmon run in direct mode does not do its own device
       probing.	Thus, in particular, if	you point it at	a GPS with a native
       binary mode that	happens	to be emitting NMEA, it	won't identify the
       actual type unless the device emits a recognizable NMEA trigger
       sentence. The -t	and -i options may help	you.

       The -F option is	only valid in client mode; it specifies	a control
       socket to which the program should send device control strings. You
       must specify a valid pathname of	a Unix-domain socket on	your local

       The -D option enables packet-getter debugging output and	is probably
       only useful to developers of the	GPSD code. Consult the packet-getter
       source code for relevant	values.

       The -L option lists a table showing which GPS device types gpsmon has
       built-in	support	for, and which generic commands	can be applied to
       which GPS types,	and then exits.	Note that this does not	list
       type-specific commands associated with individual GPS types.

       The -l option sets up logging to	a specified file to start immediately
       on device open. This may	be useful is, for example, you want to capture
       the startup message from	a device that displays firmware	version
       information there.

       The -n option forces gpsmon to request NMEA0183 packets instead of the
       raw datastream from gpsd.

       The -t option sets up a fallback	type. Give it a	string that is a
       distinguishing prefix of	exactly	one driver type	name; this will	be
       used for	mode, speed, and rate switching	if the driver selected by the
       packet type lacks those capabilities. Most useful when the packet type
       is NMEA but the device is known to have a binary	mode, such as SiRF

       The -a option enables a special debugging mode that does	not use	screen
       painting. Packets are dumped normally; any character typed suspends
       packet dumping and brings up a command prompt. This feature will	mainly
       be of interest to GPSD developers.

       After startup (without -a), the top part	of the screen reports the
       contents	of several especially interesting packet types.	The "PPS"
       field, if nonempty, is the delta	between	the last 1PPS top of second
       and the system clock at that time.

       The bottom half of the screen is	a scrolling hex	dump of	all packets
       the GPS is issuing. If the packet type is textual, any trailing CR/LF
       is omitted. Dump	lines beginning	>>> represent control packets sent to
       the GPS.	Lines consisting of "PPS" surrounded by	dashes,	if present,
       indicate	1PPS and the start of the reporting cycle.

       The following device-independent	commands are available while gpsmon is

	   (Direct mode	only.) Enable/disable subtype probing and reinitialize
	   the driver. In normal operation, gpsmon does	not send configuration
	   strings to the device (except for wakeup strings needed to get it
	   to send data, if any). The command 'i1' causes it to	send the same
	   sequence of subtype probes that gpsd	would. The command 'i0'	turns
	   off probing;	'i' alone toggles the bit. In either case, the current
	   driver is re-selected; if the probe bit is enabled, probes will
	   begin to be issued immediately.

	   Note	that enabling probing might flip the device into another mode;
	   in particular, it will flip a SiRF chip into	binary mode as if you
	   had used the	"n" command. This is due to a limitation in the	SiRF
	   firmware that we can't fix.

	   This	command	will generally do nothing after	the first time you use
	   it, because the device type will already have been discovered.

	   (Direct mode	only.) Change cycle time. Follow it with a number
	   interpreted as a cycle time in seconds. Most	devices	have a fixed
	   cycle time of 1 second, so this command may fail with a message.

	   Toggle packet logging. If packet logging is on, it will be turned
	   off and the log closed. If it is off, logging to the	filename
	   following the l will	be enabled. Differs from simply	capturing the
	   data	from the GPS device in that only whole packets are logged. The
	   logfile is opened for append, so you	can log	more than one portion
	   of the packet stream	and they will be stitched together correctly.

	   (Direct mode	only.) With an argument	of 0, switch device to NMEA
	   mode	at current speed; with an argument of 1, change	to binary
	   (native) mode. With no argument, toggle the setting.	Will show an
	   error if the	device doesn't have such modes.

	   After you switch a dual-protocol GPS	to NMEA	mode with this
	   command, it retains the information about the original type and its
	   control capabilities. That is why the device	type listed before the
	   prompt doesn't change.

	   Quit	gpsmon.	Control-C, or whatever your current interrupt
	   character is, works as well.

	   (Direct mode	only.) Change baud rate. Follow	it with	a number
	   interpreted as bits per second, for example "s9600".	The speed
	   number may optionally be followed by	a colon	and a
	   wordlength-parity-stopbits specification in the traditional style,
	   e.g 8N1 (the	default), 7E1, etc. Some devices don't support serial
	   modes other than their default, so this command may fail with a

	   Use this command 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

	   (Direct mode	only.) Force a switch of monitoring type. Follow it
	   with	a string that is unique	to the name of a gpsd driver with
	   gpsmon support; gpsmon will switch to using that driver and display
	   code. Will show an error message if there is	no matching gpsd
	   driver, or multiple matches,	or the unique match has	no display
	   support in gpsmon.

	   (Direct mode	only.) Send hex	payload	to device. Following the
	   command letter you may type hex digit pairs;	end with a newline.
	   These will become the payload of a control packet shipped to	the
	   device. The packet will be wrapped with headers, trailers, and
	   checksum appropriate	for the	current	driver type. The first one or
	   two bytes of	the payload may	be specially interpreted, see the
	   description of the -x of gpsctl(1).

	   (Direct mode	only.) Send raw	hex bytes to device. Following the
	   command letter you may type hex digit pairs;	end with a newline.
	   These will be shipped to the	device.

	   Freeze display, suspend scrolling in	debug window.

	   Unfreeze display, resume normal operation.

   NMEA	support
       (These remarks apply to not just	generic	NMEA devices but all extended
       NMEA devices for	which gpsmon presently has support.)

       All fields are raw data from the	GPS except (a) the "Cooked PVT"	window
       near top	of screen, provided as a check and (b) the "PPS	offset"	field.

       There are no device-specific commands. Which generic commands are
       available may vary by type: examine the output of gpsmon	-l to learn

   SiRF	support
       Most information	is raw from the	GPS. Underlined	fields are derived by
       translation from	ECEF coordinates or application	of leap-second and
       local time-zone offsets.	1PPS is	the clock lag as usual.

       The following commands are supported for	SiRF GPSes only:

	   (Direct mode	only.) Toggle reporting	of 50BPS subframe data.

	   (Direct mode	only.) Set (M1)	or clear (M0) static navigation. The
	   SiRF	documentation says "Static navigation is a position filter
	   designed to be used with motor vehicles. When the vehicle's
	   velocity falls below	a threshold, the position and heading are
	   frozen, and velocity	is set to zero.	This condition will continue
	   until the computed velocity rises above 1.2 times the threshold or
	   until the computed position is at least a set distance from the
	   frozen place. The threshold velocity	and set	distance may vary with
	   software versions."

	   Non-static mode is designed for use with road navigation software,
	   which often snaps the reported position to the nearest road within
	   some	uncertainty radius. You	probably want to turn static
	   navigation off for pedestrian use, as it is likely to report	speed
	   zero	and position changing in large jumps.

	   (Direct mode	only.) Toggle navigation-parameter display mode.
	   Toggles between normal display and one that shows selected
	   navigation parameters from MID 19, including	the Static Navigation
	   bit toggled by the 'M' command.

       To interpret what you see, you will need	a copy of the SiRF Binary
       Protocol	Reference Manual.

   u-blox support
       Most information	is raw from the	GPS. Underlined	fields are derived by
       translation from	ECEF coordinates. 1PPS is the clock lag	as usual.
       There are no per-type special commands.

       The PPS Offset field will never be updated when running in client mode,
       even if you can see PPS events in the packet window. This limitation
       may be fixed in a future	release.

       gpsd(8),	gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),
       gpsfake(1), gpsctl(1), gpscat(1).  gpspipe(1).

       Eric S. Raymond <>.

The GPSD Project		  17 Feb 2009			     GPSMON(1)


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

home | help