gpsd/man/gpsplot.adoc

= gpsplot(1)
:author: Gary E. Miller
:date: 26 February 2021
:email: <gem@rellim.com.>
:keywords: gps, gpsplot, scatterplot. strip chart
:manmanual: GPSD Documentation
:mansource: GPSD {gpsdver}
:robots: index,follow
:sectlinks:
:toc: macro
:type: manpage
:webfonts!:

include::../www/inc-menu.adoc[]

== 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 varable *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:* {gpsdweb}

== COPYING

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