GPSCSV(1)

📦
version 3.27.5 · 9 versions
, in arch rolling, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💖 GPSCSV(1) 💖

okay bestie, welcome to the gpscsv page, straight out of the GPSD Documentation ✨ this is the manual for gpscsv, and yes it's a whole vibe. grab a boba, we're doing CSV now 🧋

✨ NAME ✨

gpscsv — dump the JSON output from gpsd as CSV 🎀

🌸 SYNOPSIS 🌸

gpscsv [OPTIONS] [host[:port[:device]]]

gpscsv -h

gpscsv -V

🦋 DESCRIPTION 🦋

so gpscsv is literally just a simple Python program that reads gpsd JSON data streams and spits them back out as Comma Separated Values (CSV) 💅 it takes input from a gpsd that you specify, and reports to standard output. and it just... keeps going. it runs until the gpsd dies, or until -n COUNT messages are processed, or until -x SECONDS have passed, or until you interrupt it with ^C or some other means. main character energy, it does not stop on its own 😭

important bestie: gpscsv can only collect data that your gpsd is already sending. it can't make it send new stuff. use gpspipe to see what JSON message classes it is sending 👑

one genuinely good use of gpscsv is making CSV files for use with the gnuplot program. iconic combo fr fr 📈

and no cap: gpscsv does not need root, but it will run fine as root. she's low maintenance like that 🫶

💅 OPTIONS 💅

the program accepts the following options:

  • -?, -h, --help — show help information and exit. simple. elegant. ✨
  • -c MCLASS, --class MCLASS — select the JSON class messages of type MCLASS. this overrides the default class of TPV. see the CLASSES section below for more info 💖
  • --cvt-isotime — convert fields named "time" from ISO time to UNIX time. timezone glow-up 🕐
  • -D LVL, --debug LVL — set debug level to LVL. default 0. arguments higher than 0 produce more debug output 👀
  • --device DEVICE — the DEVICE on the gpsd to connect to. defaults to all.
  • -f FIELDS, -fields FIELDS — the FIELDS from the JSON message to dump to the output. set FIELD to empty ('') for all initially seen fields. default varies by CLASS.
  • --file FILE — read JSON from FILE instead of from gpsd. no daemon, no problem 🍓
  • --header HEADER — set header style to HEADER. 0 for no header, 1 output fields as header, 2 send fields as a comment ('#'). defaults to 1.
  • --host HOST — connect to the gpsd on HOST. defaults to localhost.
  • -n COUNT, --count COUNT — exit after outputting COUNT records. set COUNT to 0 to disable. default is 0
  • --port PORT — use PORT to connect to gpsd. defaults to 2947.
  • --separator SEPARATOR — use SEPARATOR as the field separator. default separator is a comma (',').
  • -V, --version — show gpscsv version, and exit.
  • -x SECONDS, --seconds SECONDS — exit after SECONDS number of seconds have passed. set SECONDS to 0 to disable. default is 0
heads up bestie: all the above individual options may be specified multiple times, but only the last one of each will be used. so like, no stacking, the final one eats the rest 💀

🌈 CLASSES 🌈

some of the gpsd JSON message classes include sub-classes. gpscsv allows direct access to them using a meta-class (MCLASS). here's the whole roster, no gatekeeping 🎀

  • ALMANAC — Class: SUBFRAME — ALMANAC from SUBFRAME JSON
  • HEALTH — Class: SUBFRAME — HEALTH from SUBFRAME JSON
  • HEALTH2 — Class: SUBFRAME — HEALTH2 from SUBFRAME JSON
  • IONO — Class: SUBFRAME — IONO from SUBFRAME JSON
  • NMCT — Class: SUBFRAME — NMCT from SUBFRAME JSON
  • SUBFRAME1 — Class: SUBFRAME — SUBFRAME1 (Ephemeris 1) from SUBFRAME JSON
  • SUBFRAME2 — Class: SUBFRAME — SUBFRAME2 (Ephemeris 2) from SUBFRAME JSON
  • SUBFRAME3 — Class: SUBFRAME — SUBFRAME3 (Ephemeris 3) from SUBFRAME JSON
  • SAT — Class: SKY — Individual satellites from SKY
  • SKY — Class: SKY — The basic parts of SKY JSON
  • TPV — Class: TPV — The basic parts of TPV JSON

🧚 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. go read it, it's giving lore 📚

🔥 EXAMPLES 🔥

some basic standalone examples:

grab three cycles of TPV data:

$ gpscsv -c TPV -n 3
time,lat,lon,altHAE
2021-07-28T22:38:37.000Z,44.0688638,-121.3140643,1108.223
2021-07-26T22:38:37.000Z,44.068863833,-121.314064333,1108.3
2021-07-28T22:38:38.000Z,44.0688637,-121.314065,1108.363

grab one set of satellite data:

$ gpscsv -c SAT -n 1
time,gnssid,svid,PRN,az,el,ss,used,health
2021-07-28T22:37:46.000Z,0,8,8,311.0,28.0,33.0,True,1
2021-07-28T22:37:46.000Z,0,10,10,290.0,74.0,50.0,True,1
2021-07-28T22:37:46.000Z,0,15,15,45.0,18.0,31.0,False,1
2021-07-28T22:37:46.000Z,0,16,16,244.0,7.0,23.0,True,1
2021-07-28T22:37:46.000Z,0,18,18,109.0,43.0,37.0,True,1
2021-07-28T22:37:46.000Z,0,23,23,49.0,62.0,38.0,True,1
2021-07-28T22:37:46.000Z,0,24,24,87.0,16.0,28.0,True,1
2021-07-28T22:37:46.000Z,0,27,27,280.0,52.0,42.0,True,1
2021-07-28T22:37:46.000Z,0,32,32,188.0,32.0,42.0,True,1
2021-07-28T22:37:46.000Z,5,3,195,305.0,6.0,13.0,False,1
2021-07-28T22:37:46.000Z,6,2,66,38.0,8.0,21.0,False,1
2021-07-28T22:37:46.000Z,6,3,67,34.0,60.0,32.0,True,1
2021-07-28T22:37:46.000Z,6,4,68,226.0,63.0,34.0,True,1
2021-07-28T22:37:46.000Z,6,5,69,220.0,12.0,32.0,True,1
2021-07-28T22:37:46.000Z,6,11,75,-999,4.0,0.0,False,2
2021-07-28T22:37:46.000Z,6,12,76,47.0,0.0,0.0,False,1
2021-07-28T22:37:46.000Z,6,17,81,142.0,8.0,31.0,True,1
2021-07-28T22:37:46.000Z,6,18,82,138.0,57.0,40.0,True,1
2021-07-28T22:37:46.000Z,6,19,83,333.0,70.0,29.0,True,1
2021-07-28T22:37:46.000Z,6,20,84,323.0,10.0,0.0,False,1

🎀 Plot Examples 🎀

some plot examples — do them in exact order shown, bestie, don't freestyle it 🙈

grab 100 samples of time,lat,lon,altHAE:

$ gpscsv -n 100 --cvt-isotime  > tpv.dat

grab 100 samples of time,epx,epy,epv,eph,sep

$ gpscsv -n 100 --cvt-isotime -f time,epx,epy,epv,eph,sep > ep.dat

grab 100 samples of time,xdop,ydop,vdop,tdop,hdop,gdop,pdop

$ gpscsv -n 100 --cvt-isotime -c SKY  > sky.dat

grab 100 samples of time,nSat,uSat

$ gpscsv -n 100 --cvt-isotime -c SKY -f time,nSat,uSat  > sat.dat

💜 Viewing CSV data with gnuplot 💜

start gnuplot in interactive mode:

$ gnuplot

some gnuplot housekeeping:

# this are csv files
gnuplot> set datafile separator ','
# use the first line as title
gnuplot> set key autotitle columnhead
# X axis is UNIT time in seconds.
gnuplot> set xdata time
gnuplot> set timefmt "%s"

now to plot time vs latitude, using tpv.dat from above:

gnuplot> plot 'tpv.dat' using 1:2

then to plot longitude and altHAE, in separate plots:

gnuplot> plot 'tpv.dat' using 1:3
gnuplot> plot 'tpv.dat' using 1:4

put both latitude and longitude on one plot:

gnuplot> set y2tics
gnuplot> plot 'tpv.dat' using 1:2, '' using 1:3 axes x1y2

plot epx, epy, epv, eph, and sep in one plot, using ep.dat from above:

gnuplot> plot 'ep.dat' using 1:2, '' using 1:3, \
         '' using 1:4, '' using 1:5, '' using 1:6

plot all the DOPs on one plot, from sky.dat above:

gnuplot> plot 'sky.dat' using 1:2, '' using 1:3, '' using 1:4, \
         '' using 1:5, '' using 1:6, '' using 1:7, '' using 1:8

plot nSat and uSat together:

gnuplot> plot 'sat.dat' using 1:2, '' using 1:3

lat/lon scatter plot:

# x is no longer time
gnuplot> set xdata
gnuplot> plot 'tpv.dat' using 3:2 title 'fix'

⭐ RETURN VALUES ⭐

  • 0 — on success. we ate 💅
  • 1 — on failure. it's giving flop 😭

🌸 SEE ALSO 🌸

gpspipe(1), gpsd_json(5), gpsd(8), gnuplot(1) — the whole friend group 🫶

✨ RESOURCES ✨

project web site: https://gpsd.io/ — go touch grass (digitally) 🌱

🎀 COPYING 🎀

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

👑 AUTHOR 👑

Gary E. Miller

GPSD, Version 3.27.5 · 2025-11-04 — and that's the whole page bestie, you're officially a gpscsv girlie now 💖✨ no cap, go make some CSV files and slay 🦋💅

📦 where this page comes from