1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!--
3This file is Copyright (c) 2010 by the GPSD project
4SPDX-License-Identifier: BSD-2-clause
5-->
6<!DOCTYPE refentry PUBLIC
7   "-//OASIS//DTD DocBook XML V4.1.2//EN"
8   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
9<refentry id='gpspipe.1'>
10 <refentryinfo>
11  <date>14 Dec 2018</date>
12 </refentryinfo>
13 <refmeta>
14  <refentrytitle>gpspipe</refentrytitle>
15  <manvolnum>1</manvolnum>
16  <refmiscinfo class="source">The GPSD Project</refmiscinfo>
17  <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
18 </refmeta>
19 <refnamediv id='name'>
20  <refname>gpspipe</refname>
21  <refpurpose>tool to connect to gpsd and retrieve sentences</refpurpose>
22 </refnamediv>
23 <refsynopsisdiv id='synopsis'>
24  <cmdsynopsis>
25   <command>gpspipe</command>
26   <arg choice='opt'>-2</arg>
27   <arg choice='opt'>-?</arg>
28   <arg choice='opt'>-d</arg>
29   <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
30   <arg choice='opt'>-h</arg>
31   <arg choice='opt'>-l</arg>
32   <arg choice='opt'>-n <replaceable>count</replaceable></arg>
33   <arg choice='opt'>-o <replaceable>filename</replaceable></arg>
34   <arg choice='opt'>-p</arg>
35   <arg choice='opt'>-P</arg>
36   <arg choice='opt'>-r</arg>
37   <arg choice='opt'>-R</arg>
38   <arg choice='opt'>-S</arg>
39   <arg choice='opt'>-s <replaceable>serial-device</replaceable></arg>
40   <arg choice='opt'>-t</arg>
41   <arg choice='opt'>-T <replaceable>timestamp-format</replaceable></arg>
42   <arg choice='opt'>-u</arg>
43   <arg choice='opt'>-v</arg>
44   <arg choice='opt'>-V</arg>
45   <arg choice='opt'>-w</arg>
46   <arg choice='opt'>-x <replaceable>seconds</replaceable></arg>
47   <arg choice='opt'>-Z</arg>
48   <group>
49    <replaceable>server</replaceable>
50    <group>
51     <replaceable>:port</replaceable>
52     <group>
53      <replaceable>:device</replaceable>
54     </group>
55    </group>
56   </group>
57  </cmdsynopsis>
58 </refsynopsisdiv>
59 <refsect1 id='description'>
60  <title>DESCRIPTION</title>
61  <para>
62   <application>gpspipe</application> is a tool to connect
63to <application>gpsd</application> and output the received
64sentences to stdout.  This makes the program useful as a pipe from
65<application>gpsd</application> to another program or file. </para>
66  <para>
67   <application>gpspipe</application> does not require root
68privileges, and can be run concurrently with other tools connecting
69to the local <application>gpsd</application> without causing problems.</para>
70  <para>The output will consist of one or both of the raw NMEA or native
71<application>gpsd</application> sentences.  Each line can be optionally
72time stamped.  There is also an option to exit gracefully after a
73given count of packets.</para>
74  <para>Optionally a server, TCP/IP port number and remote device can be given.
75If omitted, <application>gpspipe</application> connects to localhost on
76the default port (2947) and watches all devices opened by
77<application>gpsd</application>.</para>
78  <para>
79   <application>gpspipe</application> may be run as a daemon, but
80requires the -o flag for writing the output to a file.</para>
81 </refsect1>
82 <refsect1 id='options'>
83  <title>OPTIONS</title>
84  <para>-2 sets the split24 flag on AIS reports. Note: this option
85is experimental and may be changed or removed in a future release.</para>
86  <para>-? makes <application>gpspipe</application> print
87a usage message and exit.</para>
88  <para>-d causes <application>gpspipe</application> to run as a daemon.</para>
89  <para>-D [debug-level] set debug level..</para>
90  <para>-h makes <application>gpspipe</application> print
91a usage message and exit.</para>
92  <para>-l causes <application>gpspipe</application> to sleep for ten
93seconds before attempting to connect to gpsd.  This is very useful
94when running as a daemon, giving gpsd time to start before
95attempting a connection.</para>
96  <para>-n [count] causes [count] sentences to be output.
97<application>gpspipe</application> will then exit gracefully.</para>
98  <para>-o [filename] option causes the collected data to be written to the
99specified file.  Use of this option is mandatory
100if <application>gpspipe</application> is run as a daemon.</para>
101  <para>-p enables dumping of profiling information in JSON.</para>
102  <para>-P enables dumping of PPS drift JSON in NMEA and raw modes.</para>
103  <para>-r causes raw NMEA sentences to be output.</para>
104  <para>-R causes super-raw (gps binary) data to be output.  This overrides
105NMEA and gpsd output modes.</para>
106  <para>-s option causes the collected data to be written to the
107specified serial device with settings 4800 8N1.  Thus
108<application>gpspipe</application> can be used with -s and -r options
109to emulate a serial port hardwired to a GPS that
110<application>gpsd</application> is managing.</para>
111  <para>-S sets the scaled flag.  This is for AIS and subframe data, but
112currently appears to do nothing.</para>
113  <para>-t adds a UTC timestamp to each sentence output.</para>
114  <para>-T sets the format of the timestamp. See
115<citerefentry>
116    <refentrytitle>strftime</refentrytitle>
117    <manvolnum>3</manvolnum>
118   </citerefentry>
119for the available placeholders. Setting this option implies -t.
120Default setting is "%F %T"</para>
121  <para>-u usec resolution time stamp, implies -t. Use -uu to output
122 sec.usec.</para>
123  <para>-v causes <application>gpspipe</application> to show a spinning
124activity indicator on stderr. This is useful if stdout is redirected
125into a file or a pipe. By default the spinner is advanced with every
126messages written; specifying -v more than once will double the number
127of messages required to rotate the spinner.</para>
128  <para>-V prints the version, then exits.</para>
129  <para>-w causes native <application>gpsd</application> sentences to be
130output.</para>
131  <para>-x [seconds] Exit after delay of [seconds].</para>
132  <para>-Z sets the timestamp format iso8601: implies '-t'</para>
133  <para>At least one of -R, -r or -w must be specified.</para>
134  <para>You must use -o if you use -d.</para>
135 </refsect1>
136 <refsect1 id='exampletitle'>
137  <title>EXAMPLES</title>
138  <para>When <application>gpsd</application> is running,
139   <command>gpspipe
140-r -n 100</command> will send one hundred raw NMEA sentences to
141standard output, then exit.</para>
142  <para>When <application>gpsd</application> is running, <command>gpspipe
143-x 5 -w|sed -n '/TPV/{p;q}'</command> will wait at most 5 seconds for a
144TPV message, print it to stdout, then exit.</para>
145 </refsect1>
146 <refsect1 id='see_also'>
147  <title>SEE ALSO</title>
148  <para>
149   <citerefentry>
150    <refentrytitle>gpsd</refentrytitle>
151    <manvolnum>8</manvolnum>
152   </citerefentry>,
153<citerefentry>
154    <refentrytitle>gps</refentrytitle>
155    <manvolnum>1</manvolnum>
156   </citerefentry>,
157<citerefentry>
158    <refentrytitle>libgps</refentrytitle>
159    <manvolnum>3</manvolnum>
160   </citerefentry>,
161<citerefentry>
162    <refentrytitle>libgpsmm</refentrytitle>
163    <manvolnum>3</manvolnum>
164   </citerefentry>,
165<citerefentry>
166    <refentrytitle>gpsprof</refentrytitle>
167    <manvolnum>1</manvolnum>
168   </citerefentry>,
169<citerefentry>
170    <refentrytitle>gpsfake</refentrytitle>
171    <manvolnum>1</manvolnum>
172   </citerefentry>,
173<citerefentry>
174    <refentrytitle>gpsctl</refentrytitle>
175    <manvolnum>1</manvolnum>
176   </citerefentry>,
177<citerefentry>
178    <refentrytitle>gpscat</refentrytitle>
179    <manvolnum>1</manvolnum>
180   </citerefentry>.
181<citerefentry>
182    <refentrytitle>gpsmon</refentrytitle>
183    <manvolnum>1</manvolnum>
184   </citerefentry>.
185</para>
186 </refsect1>
187 <refsect1 id='maintainer'>
188  <title>AUTHOR</title>
189  <para>Gary E. Miller <email>gem@rellim.com</email>.</para>
190 </refsect1>
191</refentry>
192