GPSPLOT(1)		      GPSD Documentation		    GPSPLOT(1)

NAME
       gpsplot - tool to dynamically dump plot data from gpsd

SYNOPSIS
       gpsplot [OPTIONS] [server[:port[:device]]]

       gpsplot -h

       gpsplot -V

DESCRIPTION
       gpsplot is a tool to connect to gpsd and dynamically plot data to the
       users screen. Plot types include scatterplots and stripcharts.

       Plotting requires the Python Matplotlib module, and its many
       dependencies be installed on the display host. If the display host is
       not the gpsd host, then Matplotlib is not required to be on the gpsd
       host.

       gpslot does not require root privileges, but can be run as root.
       Running under sudo will cause some loss of functionality. It can be run
       concurrently with other tools connecting to the local gpsd without
       causing problems.

OPTIONS
       -?, -h, --help
	   Print a usage message and exit.

       -b BACKEND, --backend BACKEND
	   Set the Matplotlib interactive backend to BACKEND.

       -B, --backends
	   Print available Matplotlib interactive backends, then exit.	The
	   Matplotlib backends vary wildly in how fst they run and how good
	   they look.  Try them all to see for yourself.

       -d LVL, --debug LVL
	   Set debug level to LVL.

       --device DEVICE
	   The DEVICE on the gpsd to connect to. Defaults to all.

       --exit
	   Exit after --count, --file, or --file completes.

       --fields FIELDS
	   The code for the fields to plot. FIELDS is one of: llh
	   (lat/lon/altHAE) or llm (lat/lon/altMSL).

       --file FILE
	   Read JSON from FILE instead of from gpsd..

       --host HOST
	   Connect to the gpsd on HOST (server). Defaults to localhost.

       --image IMAGE.EXT
	   Save plot as IMAGE.EXT. EXT determines image type (.jpg, .png,
	   etc.).  Which EXT are supported is installation dependent.

       -n COUNT, --count COUNT
	   Stop after COUNT plot messages. 0 to disable. Default 0',

       --plottype PLOTTYPE
	   The type of plot to make. PLOTTYPE is one of 'scatterplot' or
	   'stripchart'.

       -p PORT, --port PORT
	   Use PORT to connect to gpsd. Defaults to 2947.

       -V, --version
	   Print the program version and exit.

       -x SECONDS, --seconds SECONDS
	   Stop after SECONDS. 0 to disable. Default 0',

ARGUMENTS
       By default, clients collect data from the local gpsd daemon running on
       localhost, using the default GPSD port 2947. The optional argument to
       any client may override this behavior: [server[:port[:device]]]

       For further explanation, and examples, see the ARGUMENTS section in the
       gps(1) man page

ENVIRONMENT
       You can set the environment variable MPLBACKEND to your desired
       Matplotlib backend.  This save you from using -b BACKEND every time you
       run gpsplot.

EXAMPLES
       Generate a scatterplot of Latitude, Longitude and the Altitude above
       Mean Sea Level (altMSL). Stop after 60 seconds:

	   gpsplot --seconds 60 --fields llm

       Generate a scatterplot of Latitude, Longitude and the Height Above
       Ellipsoid (altHAE). Stop after 60 fixes:

	   gpsplot --count 60 --plottype stripchart

       Use the WXAgg backend to repeat the last experiment to see if it is
       faster or looks better to you.

	   export MPLBACKEND=WX
	   gpsplot --count 60 --plottype stripchart

       Generate a scatterplot locally of Latitude, Longitude and altMSL from a
       remote gpsd instance at host "example.com" and the remote device
       "/dev/ttyS0". Collect 60 fixes, Stop, save the plot as "save.jpg, and
       exit:

	   gpsplot --count 60 --exit --fields llm --image save.jpg example.com::/dev/ttyS0

RETURN VALUES
       0
	   on success.

       1
	   on failure

SEE ALSO
       gpsd(8), gpsprof(1), gpsfake(1).

RESOURCES
       Project web site:  <https://gpsd.io/>

COPYING
       This file is Copyright 2020 by the GPSD project
       SPDX-License-Identifier: BSD-2-clause

AUTHOR
       Gary E. Miller

GPSD 3.26.1			  2025-05-06			    GPSPLOT(1)