gpspipe.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for details.
   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><date>03 Aug 2005</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>gpspipe</refentrytitle>
  13 <manvolnum>1</manvolnum>
  14 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  15 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  16 </refmeta>
  17 <refnamediv id='name'>
  18 <refname>gpspipe</refname>
  19 <refpurpose>tool to connect to gpsd and retrieve sentences</refpurpose>
  20 </refnamediv>
  21 <refsynopsisdiv id='synopsis'>
  22
  23 <cmdsynopsis>
  24   <command>gpspipe</command>
  25       <arg choice='opt'>-h</arg>
  26       <arg choice='opt'>-d</arg>
  27       <arg choice='opt'>-l</arg>
  28       <arg choice='opt'>-o <replaceable>filename</replaceable></arg>
  29       <arg choice='opt'>-n <replaceable>count</replaceable></arg>
  30       <arg choice='opt'>-r</arg>
  31       <arg choice='opt'>-R</arg>
  32       <arg choice='opt'>-s <replaceable>serial-device</replaceable></arg>
  33       <arg choice='opt'>-t</arg>
  34       <arg choice='opt'>-T <replaceable>timestamp-format</replaceable></arg>
  35       <arg choice='opt'>-w</arg>
  36       <arg choice='opt'>-v</arg>
  37       <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  38       <group>
  39         <replaceable>server</replaceable>
  40           <group><replaceable>:port</replaceable>
  41             <group><replaceable>:device</replaceable></group>
  42         </group>
  43       </group>
  44 </cmdsynopsis>
  45 </refsynopsisdiv>
  46
  47 <refsect1 id='description'><title>DESCRIPTION</title>
  48
  49 <para><application>gpspipe</application> is a tool to connect
  50 to <application>gpsd</application> and output the received
  51 sentences to stdout.  This makes the program useful as a pipe from
  52 <application>gpsd</application> to another program or file. </para>
  53
  54 <para><application>gpspipe</application> does not require root
  55 privileges, and can be run concurrently with other tools connecting
  56 to the local <application>gpsd</application> without causing problems.</para>
  57
  58 <para>The output will consist of one or both of the raw NMEA or native
  59 <application>gpsd</application> sentences.  Each line can be optionally
  60 time stamped.  There is also an option to exit gracefully after a
  61 given count of packets.</para>
  62
  63 <para>Optionally a server, TCP/IP port number and remote device can be given.
  64 If omitted, <application>gpspipe</application> connects to localhost on
  65 the default port (2947) and watches all devices opened by
  66 <application>gpsd</application>.</para>
  67
  68 <para><application>gpspipe</application> may be run as a daemon, but
  69 requires the -o flag for writing the output to a file.</para>
  70
  71 </refsect1>
  72 <refsect1 id='options'><title>OPTIONS</title>
  73
  74 <para>-h makes <application>gpspipe</application> print
  75 a usage message and exit.</para>
  76
  77 <para>-d causes <application>gpspipe</application> to run as a daemon.</para>
  78
  79 <para>-l causes <application>gpspipe</application> to sleep for ten
  80 seconds before attempting to connect to gpsd.  This is very useful
  81 when running as a daemon, giving gpsd time to start before
  82 attempting a connection.</para>
  83
  84 <para>-r causes raw NMEA sentences to be output.</para>
  85
  86 <para>-R causes super-raw (gps binary) data to be output.  This overrides
  87 NMEA and gpsd output modes.</para>
  88
  89 <para>-s option causes the collected data to be written to the
  90 specified serial device with settings 4800 8N1.  Thus
  91 <application>gpspipe</application> can be used with -s and -r options
  92 to emulate a serial port hardwired to a GPS that
  93 <application>gpsd</application> is managing.</para>
  94
  95 <para>-o option causes the collected data to be written to the
  96 specified file.  Use of this option is mandatory
  97 if <application>gpspipe</application> is run as a daemon.</para>
  98
  99 <para>-w causes native <application>gpsd</application>sentences to be
 100 output.</para>
 101
 102 <para>-t adds a timestamp to each sentence output.</para>
 103
 104 <para>-T sets the format of the timestamp. See
 105 <citerefentry><refentrytitle>strftime</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 106 for the available placeholders. Setting this option implies -t.</para>
 107
 108 <para>-n [count] causes [count] sentences to be output.
 109 <application>gpspipe</application> will then exit gracefully.</para>
 110
 111 <para>-v causes <application>gpspipe</application> to show a spinning
 112 activity indicator on stderr. This is useful if stdout is redirected
 113 into a file or a pipe. By default the spinner is advanced with every
 114 messages written; specifying -v more than once will double the number
 115 of messages required to rotate the spinner.</para>
 116
 117 <para>-V prints the version, then exits.</para>
 118
 119 <para>At least one of -R, -r or -w must be specified.</para>
 120 </refsect1>
 121
 122 <refsect1 id='exampletitle'><title>EXAMPLE</title>
 123 <para>When <application>gpsd is running</application> <command>gpspipe
 124 -r -n 100</command> will send one hundred raw NMEA sentences to
 125 standard output, then exit.</para>
 126 </refsect1>
 127
 128 <refsect1 id='see_also'><title>SEE ALSO</title>
 129 <para>
 130 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 131 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 132 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 133 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 134 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 135 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 136 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 137 <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 138 <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 139 </para>
 140 </refsect1>
 141
 142 <refsect1 id='maintainer'><title>AUTHOR</title>
 143
 144 <para>Gary E. Miller <email>gem@rellim.com</email>.  There is a
 145 project page for <application>gpsd</application> <ulink
 146 url="http://gpsd.berlios.de/">here</ulink>.</para>
 147
 148 </refsect1>
 149
 150 </refentry>
 151