GPSPLOT(1)

GPSPLOT(1) 💖 the GPSD Documentation girlies present…

okay bestie, welcome to gpsplot, a tool to dynamically dump plot data from gpsd ✨ (yes that's the actual NAME line, i'm not being cute, that's just what it is 💅)

---

✨ SYNOPSIS ✨

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

gpsplot -h

gpsplot -V

like. three whole ways to summon her. iconic. 🎀

---

🌸 DESCRIPTION 🌸

gpsplot is a tool that connects to gpsd and dynamically plots data to your screen. plot types include scatterplots and stripcharts. that's it, that's the vibe 🦋

so for the plotting to actually happen, you need the Python Matplotlib module — and like, all of its many dependencies — installed on the display host. here's the cute part tho: if the display host isn't the same machine as the gpsd host, then Matplotlib does NOT need to be on the gpsd host. split the load, share the work, main character energy fr 💅

gpsplot does not require root privileges, but yeah you can run it as root if you want. > heads up tho: running under sudo will cause some loss of functionality 😭 so like, don't unless you have to.

and the bestie behaviour award goes to: it can be run concurrently with other tools connecting to the local gpsd without causing problems. she shares the aux cord. she's a good friend. 🫶

---

✨ OPTIONS ✨

• -?, -h, --help — prints a usage message and dips out. classic.
• -b BACKEND, --backend BACKEND — set the Matplotlib interactive backend to BACKEND.
• -B, --backends — print all the available Matplotlib interactive backends, then exit. ngl the Matplotlib backends vary wildly in how fast they run and how good they look, so like… try them all and see for yourself bestie 🔥
• -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 the plot as IMAGE.EXT. the EXT decides the image type (.jpg, .png, etc.). which EXT values 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 can override this behaviour:

[server[:port[:device]]]

for further explanation and examples, go read the ARGUMENTS section in the gps(1) man page. she's got the lore 📖✨

---

💜 ENVIRONMENT 💜

you can set the environment variable MPLBACKEND to whatever Matplotlib backend you're feeling that day. this saves you from typing -b BACKEND every single time you run gpsplot. literally a time-saver, we love efficiency 🎀

---

🌈 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 and see if it's 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

---

and that's the whole page bestie!! this was GPSD 3.27.5, dated 2025-11-04, brought to you by the gpsplot manual girlies. mwah 💖 stay plotted, stay iconic ✨🦋