<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright 2010 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='gpspipe.1'>
 <refentryinfo>
  <date>5 December 2020</date>
 </refentryinfo>
 <refmeta>
  <refentrytitle>gpspipe</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
 </refmeta>
 <refnamediv id='name'>
  <refname>gpspipe</refname>
  <refpurpose>tool to connect to gpsd and retrieve sentences</refpurpose>
 </refnamediv>
 <refsynopsisdiv id='synopsis'>
  <cmdsynopsis>
   <command>gpspipe</command>
   <arg choice='opt'>-?</arg>
   <arg choice='opt'>--count <replaceable>COUNT</replaceable>
   </arg>
   <arg choice='opt'>--daemonize</arg>
   <arg choice='opt'>--debug <replaceable>LVL</replaceable>
   </arg>
   <arg choice='opt'>--help</arg>
   <arg choice='opt'>--json</arg>
   <arg choice='opt'>--nmae</arg>
   <arg choice='opt'>--output <replaceable>FILE</replaceable>
   </arg>
   <arg choice='opt'>--pps</arg>
   <arg choice='opt'>--profile</arg>
   <arg choice='opt'>--raw</arg>
   <arg choice='opt'>--scaled</arg>
   <arg choice='opt'>--seconds <replaceable>SEC</replaceable>
   </arg>
   <arg choice='opt'>--serial <replaceable>DEV</replaceable>
   </arg>
   <arg choice='opt'>--sleep</arg>
   <arg choice='opt'>--spinner</arg>
   <arg choice='opt'>--split24</arg>
   <arg choice='opt'>--timefmt <replaceable>FMT</replaceable>
   </arg>
   <arg choice='opt'>--timestamp</arg>
   <arg choice='opt'>--usec</arg>
   <arg choice='opt'>--version</arg>
   <arg choice='opt'>--zulu</arg>
   <arg choice='opt'>-2</arg>
   <arg choice='opt'>-?</arg>
   <arg choice='opt'>-d</arg>
   <arg choice='opt'>-D <replaceable>LVL</replaceable>
   </arg>
   <arg choice='opt'>-h</arg>
   <arg choice='opt'>-l</arg>
   <arg choice='opt'>-n <replaceable>COUNT</replaceable>
   </arg>
   <arg choice='opt'>-o <replaceable>FILE</replaceable>
   </arg>
   <arg choice='opt'>-p</arg>
   <arg choice='opt'>-P</arg>
   <arg choice='opt'>-r</arg>
   <arg choice='opt'>-R</arg>
   <arg choice='opt'>-S</arg>
   <arg choice='opt'>-s <replaceable>serial-device</replaceable>
   </arg>
   <arg choice='opt'>-t</arg>
   <arg choice='opt'>-T <replaceable>timestamp-format</replaceable>
   </arg>
   <arg choice='opt'>-u</arg>
   <arg choice='opt'>-v</arg>
   <arg choice='opt'>-V</arg>
   <arg choice='opt'>-w</arg>
   <arg choice='opt'>-x <replaceable>seconds</replaceable>
   </arg>
   <arg choice='opt'>-Z</arg>
   <group>
    <replaceable>server</replaceable>
    <group>
     <replaceable>:port</replaceable>
     <group>
      <replaceable>:device</replaceable>
     </group>
    </group>
   </group>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1 id='description'>
  <title>DESCRIPTION</title>
  <para>
   <application>gpspipe</application> is a tool to connect
to <application>gpsd</application> and output the received
sentences to stdout.  This makes the program useful as a pipe from
<application>gpsd</application> to another program or file. </para>
  <para>
   <application>gpspipe</application> does not require root
privileges, and can be run concurrently with other tools connecting
to the local <application>gpsd</application> without causing problems.</para>
  <para>The output will consist of one or both of the raw NMEA or native
<application>gpsd</application> sentences.  Each line can be optionally
time stamped.  There is also an option to exit gracefully after a
given count of packets.</para>
  <para>Optionally a server, TCP/IP port number and remote device can be given.
If omitted, <application>gpspipe</application> connects to localhost on
the default port (2947) and watches all devices opened by
<application>gpsd</application>.</para>
  <para>
   <application>gpspipe</application> may be run as a daemon, but
requires the <option>-o, --output</option> flag for writing the output to
a file.</para>
 </refsect1>
 <refsect1 id='options'>
  <title>OPTIONS</title>
  <variablelist remap='TP'>
   <varlistentry>
    <term>
     <option>-?</option>
    </term>
    <term>
     <option>-h</option>
    </term>
    <term>
     <option>--help</option>
    </term>
    <listitem>
     <para>Print a usage message and exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-2</option>
    </term>
    <term>
     <option>--split24</option>
    </term>
    <listitem>
     <para>-2 sets the split24 flag on AIS reports.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-d</option>
    </term>
    <term>
     <option>--daemonize</option>
    </term>
    <listitem>
     <para>Run as a daemon.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-d LVL</option>
    </term>
    <term>
     <option>--debug LVL</option>
    </term>
    <listitem>
     <para>Set debug level to LVL.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-l</option>
    </term>
    <term>
     <option>--sleep</option>
    </term>
    <listitem>
     <para>Sleep for ten seconds before attempting to connect to gpsd.
This is very useful when running as a daemon, giving gpsd time to start
before attempting a connection.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-n COUNT</option>
    </term>
    <term>
     <option>--count COUNT</option>
    </term>
    <listitem>
     <para>Exit after COUNT messages are output.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-o FILE</option>
    </term>
    <term>
     <option>--output FILE</option>
    </term>
    <listitem>
     <para>Cause the collected data to be written to the
specified file.  Use of this option is mandatory
if <application>gpspipe</application> is run as a daemon.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-p</option>
    </term>
    <term>
     <option>--profile</option>
    </term>
    <listitem>
     <para>Dump profiling information in JSON.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-P</option>
    </term>
    <term>
     <option>--pps</option>
    </term>
    <listitem>
     <para>Enables dumping of PPS drift JSON in NMEA and raw modes.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-r</option>
    </term>
    <term>
     <option>--nmea</option>
    </term>
    <listitem>
     <para>Cause NMEA sentences to be output. This may be NMEA,
pseudo NMEA built from binary data, or some combination of both.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-R</option>
    </term>
    <term>
     <option>--raw</option>
    </term>
    <listitem>
     <para>Causes super-raw (gps binary) data to be output. This will forward
exactly what the device sent.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-s DEV</option>
    </term>
    <term>
     <option>--serial DEV</option>
    </term>
    <listitem>
     <para>Cause the collected data to be written to the
specified serial device (DEV) with settings 4800 8N1. Thus
<application>gpspipe</application> can be used with <option>-s, --serial</option>
and <option>-r, --nmea</option> options to emulate a serial port hardwired to a
GPS that <application>gpsd</application> is managing.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-S</option>
    </term>
    <term>
     <option>--scaled</option>
    </term>
    <listitem>
     <para>Set the scaled flag.  This is for AIS and SUBFRAME data only.
Scaled data will be output in the JSON, instead of raw data in the JSON.
</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-t</option>
    </term>
    <term>
     <option>--timestamp</option>
    </term>
    <listitem>
     <para>Add a UTC timestamp to each sentence output.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-T FMT</option>
    </term>
    <term>
     <option>--timefmt FMT</option>
    </term>
    <listitem>
     <para>Set the format of the timestamp. See <citerefentry>
       <refentrytitle>strftime</refentrytitle>
       <manvolnum>3</manvolnum>
      </citerefentry> for the available placeholders. Setting this option
implies <option>-t, --timestamp</option>. Default setting is "%F
%T"</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-u</option>
    </term>
    <term>
     <option>--usec</option>
    </term>
    <listitem>
     <para>Use usec resolution time stamp, implies <option>-t,
--timestamp</option>. Use twice (<option>-uu</option>) to output sec.usec.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-v</option>
    </term>
    <term>
     <option>--spinner</option>
    </term>
    <listitem>
     <para>Show a spinning activity indicator on stderr. This is useful
if stdout is redirected into a file or a pipe. By default the spinner
is advanced with every messages written; specifying <option>-v,
--spinner</option> more than once will double the number of messages
required to rotate the spinner.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-V</option>
    </term>
    <term>
     <option>--version</option>
    </term>
    <listitem>
     <para>Print the program version and exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-w</option>
    </term>
    <term>
     <option>--json</option>
    </term>
    <listitem>
     <para>Cause native <application>gpsd</application> JSON sentences to be
output.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-x SEC</option>
    </term>
    <term>
     <option>--seconds SEC</option>
    </term>
    <listitem>
     <para>Exit after delay of SEC seconds.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-z</option>
    </term>
    <term>
     <option>--zulu</option>
    </term>
    <listitem>
     <para>Set the timestamp format iso8601: implies <option>-t</option>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
  <para>At least one of <option>-R, -r or -w</option> must be specified.</para>
  <para>You must use <option>-o</option> if you use <option>-d</option>.</para>
 </refsect1>
 <refsect1 id='exampletitle'>
  <title>EXAMPLES</title>
  <para>When <application>gpsd</application> is running,
   <command>gpspipe
-r -n 100</command> will send one hundred raw NMEA sentences to
standard output, then exit.</para>
  <para>When <application>gpsd</application> is running, <command>gpspipe
-x 5 -w|sed -n '/TPV/{p;q}'</command> will wait at most 5 seconds for a
TPV message, print it to stdout, then exit.</para>
 </refsect1>
 <refsect1 id='see_also'>
  <title>SEE ALSO</title>
  <para>
   <citerefentry>
    <refentrytitle>gpsd</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gps</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>libgps</refentrytitle>
    <manvolnum>3</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>libgpsmm</refentrytitle>
    <manvolnum>3</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsprof</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsfake</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsctl</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpscat</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>.
<citerefentry>
    <refentrytitle>gpsmon</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>.
</para>
 </refsect1>
 <refsect1 id='maintainer'>
  <title>AUTHOR</title>
  <para>Gary E. Miller <email>gem@rellim.com</email>.</para>
 </refsect1>
</refentry>
