summaryrefslogtreecommitdiff
path: root/gpspipe.xml
blob: c511d8bd5d7739fcb0b969ca943f36957cf8857c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd">
<refentry id='gpspipe.1'>
<refmeta>
<refentrytitle>gpspipe</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>03 Aug 2005</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'>-h</arg>
      <arg choice='opt'>-d</arg>
      <arg choice='opt'>-l</arg>
      <arg choice='opt'>-f <replaceable>filename</replaceable></arg>
      <arg choice='opt'>-n <replaceable>count</replaceable></arg>
      <arg choice='opt'>-r</arg>
      <arg choice='opt'>-R</arg>
      <arg choice='opt'>-s <replaceable>serial-device</replaceable></arg>
      <arg choice='opt'>-t</arg>
      <arg choice='opt'>-w</arg>
      <arg choice='opt'>-v</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 port number and remote device can be given.
If omitted, <application>gpspipe</application> connects to 127.0.0.1 on
the default port (2947) and uses the first device opened by 
<application>gpsd</application>.</para>

<para><application>gpspipe</application> may be run as a daemon, but
requires the -f flag for writing the output to a file.</para>

</refsect1>
<refsect1 id='options'><title>OPTIONS</title>

<para>-h makes <application>gpspipe</application> print
a usage message and exit.</para>

<para>-d causes <application>gpspipe</application> to run as a daemon.</para>

<para>-l causes <application>gpspipe</application> to 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>

<para>-r causes raw NMEA sentences to be output.</para>

<para>-R causes super-raw (gps binary) data to be output.  This overrides
NMEA and gpsd output modes.</para>

<para>-s option causes the collected data to be written to the
specified serial device with setttings 4800 8N1.  Thus
<application>gpspipe</application> can be used with -s and -r options
to emulate a serial port hardwired to a GPS that
<application>gpsd</application> is managing.</para>

<para>-f option causes 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>

<para>-w causes native <application>gpsd</application>sentences to be
output.</para>

<para>-t adds a timestamp to each sentence output.</para>

<para>-n [count] causes [count] sentences to be output.  
<application>gpspipe</application> will then exit gracefully.</para>

<para>-j makes the program send J=1 to the daemon, requesting
fix hold across cycles.</para>

<para>-v causes <application>gpspipe</application> to 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 -v more than once will double the number
of messages required to rotate the spinner.</para>

<para>-V prints the version, then exits.</para>

<para>At least one of -R -r or -w must be specified.</para>
</refsect1>

<refsect1 id='exampletitle'><title>EXAMPLE</title> 
<para>When <application>gpsd is running</application> <command>gpspipe
-r -n 100</command> will send one hundred raw NMEA sentences to
standard output, then exit.</para>
</refsect1>

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

<para>Gary E. Miller <email>gem@rellim.com</email>.  There is a
project page for <application>gpsd</application> <ulink
url="http://gpsd.berlios.de/">here</ulink>.</para>

</refsect1>

</refentry>