'\" t
.\"     Title: gpspipe
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 5 December 2020
.\"    Manual: GPSD Documentation
.\"    Source: The GPSD Project
.\"  Language: English
.\"
.TH "GPSPIPE" "1" "5 December 2020" "The GPSD Project" "GPSD Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gpspipe \- tool to connect to gpsd and retrieve sentences
.SH "SYNOPSIS"
.HP \w'\fBgpspipe\fR\ 'u
\fBgpspipe\fR [\-?] [\-\-count\ \fICOUNT\fR] [\-\-daemonize] [\-\-debug\ \fILVL\fR] [\-\-help] [\-\-json] [\-\-nmae] [\-\-output\ \fIFILE\fR] [\-\-pps] [\-\-profile] [\-\-raw] [\-\-scaled] [\-\-seconds\ \fISEC\fR] [\-\-serial\ \fIDEV\fR] [\-\-sleep] [\-\-spinner] [\-\-split24] [\-\-timefmt\ \fIFMT\fR] [\-\-timestamp] [\-\-usec] [\-\-version] [\-\-zulu] [\-2] [\-?] [\-d] [\-D\ \fILVL\fR] [\-h] [\-l] [\-n\ \fICOUNT\fR] [\-o\ \fIFILE\fR] [\-p] [\-P] [\-r] [\-R] [\-S] [\-s\ \fIserial\-device\fR] [\-t] [\-T\ \fItimestamp\-format\fR] [\-u] [\-v] [\-V] [\-w] [\-x\ \fIseconds\fR] [\-Z] [\fIserver\fR [\fI:port\fR [\fI:device\fR]]]
.SH "DESCRIPTION"
.PP
gpspipe
is a tool to connect to
gpsd
and output the received sentences to stdout\&. This makes the program useful as a pipe from
gpsd
to another program or file\&.
.PP
gpspipe
does not require root privileges, and can be run concurrently with other tools connecting to the local
gpsd
without causing problems\&.
.PP
The output will consist of one or both of the raw NMEA or native
gpsd
sentences\&. Each line can be optionally time stamped\&. There is also an option to exit gracefully after a given count of packets\&.
.PP
Optionally a server, TCP/IP port number and remote device can be given\&. If omitted,
gpspipe
connects to localhost on the default port (2947) and watches all devices opened by
gpsd\&.
.PP
gpspipe
may be run as a daemon, but requires the
\fB\-o, \-\-output\fR
flag for writing the output to a file\&.
.SH "OPTIONS"
.PP
\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a usage message and exit\&.
.RE
.PP
\fB\-2\fR, \fB\-\-split24\fR
.RS 4
\-2 sets the split24 flag on AIS reports\&.
.RE
.PP
\fB\-d\fR, \fB\-\-daemonize\fR
.RS 4
Run as a daemon\&.
.RE
.PP
\fB\-d LVL\fR, \fB\-\-debug LVL\fR
.RS 4
Set debug level to LVL\&.
.RE
.PP
\fB\-l\fR, \fB\-\-sleep\fR
.RS 4
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\&.
.RE
.PP
\fB\-n COUNT\fR, \fB\-\-count COUNT\fR
.RS 4
Exit after COUNT messages are output\&.
.RE
.PP
\fB\-o FILE\fR, \fB\-\-output FILE\fR
.RS 4
Cause the collected data to be written to the specified file\&. Use of this option is mandatory if
gpspipe
is run as a daemon\&.
.RE
.PP
\fB\-p\fR, \fB\-\-profile\fR
.RS 4
Dump profiling information in JSON\&.
.RE
.PP
\fB\-P\fR, \fB\-\-pps\fR
.RS 4
Enables dumping of PPS drift JSON in NMEA and raw modes\&.
.RE
.PP
\fB\-r\fR, \fB\-\-nmea\fR
.RS 4
Cause NMEA sentences to be output\&. This may be NMEA, pseudo NMEA built from binary data, or some combination of both\&.
.RE
.PP
\fB\-R\fR, \fB\-\-raw\fR
.RS 4
Causes super\-raw (gps binary) data to be output\&. This will forward exactly what the device sent\&.
.RE
.PP
\fB\-s DEV\fR, \fB\-\-serial DEV\fR
.RS 4
Cause the collected data to be written to the specified serial device (DEV) with settings 4800 8N1\&. Thus
gpspipe
can be used with
\fB\-s, \-\-serial\fR
and
\fB\-r, \-\-nmea\fR
options to emulate a serial port hardwired to a GPS that
gpsd
is managing\&.
.RE
.PP
\fB\-S\fR, \fB\-\-scaled\fR
.RS 4
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\&.
.RE
.PP
\fB\-t\fR, \fB\-\-timestamp\fR
.RS 4
Add a UTC timestamp to each sentence output\&.
.RE
.PP
\fB\-T FMT\fR, \fB\-\-timefmt FMT\fR
.RS 4
Set the format of the timestamp\&. See
\fBstrftime\fR(3)
for the available placeholders\&. Setting this option implies
\fB\-t, \-\-timestamp\fR\&. Default setting is "%F %T"
.RE
.PP
\fB\-u\fR, \fB\-\-usec\fR
.RS 4
Use usec resolution time stamp, implies
\fB\-t, \-\-timestamp\fR\&. Use twice (\fB\-uu\fR) to output sec\&.usec\&.
.RE
.PP
\fB\-v\fR, \fB\-\-spinner\fR
.RS 4
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
\fB\-v, \-\-spinner\fR
more than once will double the number of messages required to rotate the spinner\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
Print the program version and exit\&.
.RE
.PP
\fB\-w\fR, \fB\-\-json\fR
.RS 4
Cause native
gpsd
JSON sentences to be output\&.
.RE
.PP
\fB\-x SEC\fR, \fB\-\-seconds SEC\fR
.RS 4
Exit after delay of SEC seconds\&.
.RE
.PP
\fB\-z\fR, \fB\-\-zulu\fR
.RS 4
Set the timestamp format iso8601: implies
\fB\-t\fR
.RE
.PP
At least one of
\fB\-R, \-r or \-w\fR
must be specified\&.
.PP
You must use
\fB\-o\fR
if you use
\fB\-d\fR\&.
.SH "EXAMPLES"
.PP
When
gpsd
is running,
\fBgpspipe \-r \-n 100\fR
will send one hundred raw NMEA sentences to standard output, then exit\&.
.PP
When
gpsd
is running,
\fBgpspipe \-x 5 \-w|sed \-n \*(Aq/TPV/{p;q}\*(Aq\fR
will wait at most 5 seconds for a TPV message, print it to stdout, then exit\&.
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8),
\fBgps\fR(1),
\fBlibgps\fR(3),
\fBlibgpsmm\fR(3),
\fBgpsprof\fR(1),
\fBgpsfake\fR(1),
\fBgpsctl\fR(1),
\fBgpscat\fR(1)\&.
\fBgpsmon\fR(1)\&.
.SH "AUTHOR"
.PP
Gary E\&. Miller
<gem@rellim\&.com>\&.