gpsd/man/gpscsv.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright 2020 by the GPSD project
SPDX-License-Identifier: BSD-2-clause
-->
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='gpscat.1'>
<refentryinfo><date>26 August 2020</date></refentryinfo>
<refmeta>
<refentrytitle>gpscsv</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">The GPSD Project</refmiscinfo>
<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpscsv</refname>
<refpurpose>dump the JSON output from gpsd as CSV</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpscsv</command>
      <arg choice='opt'>--count<replaceable> COUNT</replaceable></arg>
      <arg choice='opt'>-c<replaceable> MCLASS</replaceable></arg>
      <arg choice='opt'>--cvt-isotime</arg>
      <arg choice='opt'>--device<replaceable> DEVICE</replaceable></arg>
      <arg choice='opt'>-D <replaceable> debuglevel</replaceable></arg>
      <arg choice='opt'>--fields<replaceable> FIELDS</replaceable></arg>
      <arg choice='opt'>-f <replaceable> FIELDS</replaceable></arg>
      <arg choice='opt'>-h</arg>
      <arg choice='opt'>--header<replaceable> HEADER</replaceable></arg>
      <arg choice='opt'>--help</arg>
      <arg choice='opt'>--host<replaceable> HOST</replaceable></arg>
      <arg choice='opt'>-n<replaceable> COUNT</replaceable></arg>
      <arg choice='opt'>--port<replaceable> PORT</replaceable></arg>
      <arg choice='opt'>--seconds<replaceable> FIELDS</replaceable></arg>
      <arg choice='opt'>--separator<replaceable> SEPARATOR</replaceable></arg>
      <arg choice='opt'>-V</arg>
      <arg choice='opt'>--version</arg>
      <arg choice='opt'>-x<replaceable> FIELDS</replaceable></arg>
      <arg choice='plain'><replaceable>[host[:port[:device]]]</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para><application>gpscsv</application> is a simple Python program
for reading a <application>gpsd</application> JSON data streams and
outputting them in Comma Separated Values (CSV) format.  It takes input
from a specified <application>gpsd</application> and reports to standard
output. The program runs until the <application>gpsd</application> dies,
"-n COUNT" messages are processed, "-x SECONDS" have passed, or it is
interrupted by ^C or other means.</para>

<para>One good use of <application>gpscsv</application> is to create
CSV files for use with the <application>gnuplot</application> program.
</para>
</refsect1>

<refsect1 id='options'><title>OPTIONS</title>
<para>The program accepts the following options:</para>
<variablelist remap='TP'>

<varlistentry>
<term>-h, --help</term>
<listitem>
<para>Show help information and exit.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-c CLASS, --class CLASS</term>
<listitem>
<para>Select the JSON class messages of type CLASS.  Default is TPV.
.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--cvt-isotime</term>
<listitem>
<para>Convert fields named "time" from ISO time to UNIX time.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-D DEBUG</term>
<listitem>
<para>Set debug level to DEBUG.  Default 0.  Higher arguments than D 
produce more debug output.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--device DEVICE</term>
<listitem>
<para>The DEVICE on the <application>gpsd</application> to connect to.
Defaults to all.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-f FIELDS, --fields FIELDS</term>
<listitem>
<para>The FIELDS from the JSON message to dump to the output.
Set FIELD to empty ('') for all fields Default varies by CLASS.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--header HEADER</term>
<listitem><para>Set header style to HEADER.  0 for no header, 1 output fields as
header, 2 send fields as a comment ('#').
Defaults to 1.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--host HOST</term>
<listitem>
<para>Connect to the <application>gpsd</application> on HOST.
Defaults to localhost.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-n COUNT, --count COUNT</term>
<listitem>
<para>Exit after outputting COUNT records.
Set COUNT to 0 to disable.  Default is 0</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--port PORT</term>
<listitem>
<para>Use PORT to connect to <application>gpsd</application>.
Defaults to 2947.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--separator SEPARATOR</term>
<listitem>
<para>Use SEPARATOR as the field separator.
Default separator is a comma (',').</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-V, --version</term>
<listitem>
<para>Show <application>gpscsv</application> version, and exit.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-x SECONDS, --seconds SECONDS</term>
<listitem>
<para>Exit after SECONDS number of seconds have passed.
Set SECONDS to 0 to disable.  Default is 0</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1 id='examples'><title>EXAMPLES</title>
<para>Some basic examples, do them in exact order shown:</para>

<para>
Grab 100 samples of time,lat,lon,altHAE:
</para>
<programlisting>
  $ gpscsv -n 100 --cvt-isotime  > tpv.dat
</programlisting>
<para>
Grab 100 samples of time,epx,epy,epv,eph,sep
</para>
<programlisting>
  $ gpscsv -n 100 --cvt-isotime -f time,epx,epy,epv,eph,sep > ep.dat
</programlisting>
<para>
Grab 100 samples of time,xdop,ydop,vdop,tdop,hdop,gdop,pdop
</para>
<programlisting>
  $ gpscsv -n 100 --cvt-isotime -c SKY  > sky.dat
</programlisting>
<para>
Grab 100 samples of time,nSat,uSat
</para>
<programlisting>
  $ gpscsv -n 100 --cvt-isotime -c SKY -f time,nSat,uSat  > sat.dat
</programlisting>
<para>

start gnuplot in interactive mode:
</para>
<programlisting>
  $ gnuplot
</programlisting>
<para>

Some gnuplot housekeeping:
</para>
<programlisting>
  # 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"
</programlisting>
<para>

Now to plot time vs latitude:
</para>
<programlisting>
  gnuplot> plot 'tpv.dat' using 1:2
</programlisting>
<para>

Then to plot longitude and altHAE, in separate plots:
</para>
<programlisting>
  gnuplot> plot 'tpv.dat' using 1:3
  gnuplot> plot 'tpv.dat' using 1:4
</programlisting>
<para>

Put both latitude and longitude on one plot:
</para>
<programlisting>
  gnuplot> set y2tics
  gnuplot> plot 'tpv.dat' using 1:2, '' using 1:3 axes x1y2
</programlisting>
<para>

Plot epx, epy, epv, eph, and sep in one plot:
</para>
<programlisting>
  gnuplot> plot 'ep.dat' using 1:2, '' using 1:3, \
           '' using 1:4, '' using 1:5, '' using 1:6
</programlisting>
<para>

Plot all the DOPs on one plot:
</para>
<programlisting>
  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
</programlisting>
<para>

Plot nSat and uSat together:
</para>
<programlisting>
  gnuplot> plot 'sat.dat' using 1:2, '' using 1:3
</programlisting>
<para>

Lat/lon scatter plot:
</para>
<programlisting>
  # x is no longer time
  gnuplot> set xdata
  gnuplot> plot 'tpv.dat' using 3:2 title 'fix'
</programlisting>

</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
</para>
</refsect1>

<refsect1 id='maintainer'><title>AUTHOR</title>

<para>Gary E. Miller <email>gem@rellim.com</email>.</para>
</refsect1>
</refentry>