1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
3<!--
4This file is Copyright (c) 2018 by the GPSD project
5SPDX-License-Identifier: BSD-2-clause
6--><refentry id="gpsrinex.1">
7  <refentryinfo>
8    <date>09 Nov 2018</date>
9  </refentryinfo>
10  <refmeta>
11    <refentrytitle>gpsrinex</refentrytitle>
12    <manvolnum>1</manvolnum>
13    <refmiscinfo class="source">The GPSD Project</refmiscinfo>
14    <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
15  </refmeta>
16  <refnamediv id="name">
17    <refname>gpsrinex</refname>
18    <refpurpose>Read data from gpsd convert to RINEX3 and save to a file.</refpurpose>
19  </refnamediv>
20  <refsynopsisdiv id="synopsis">
21    <cmdsynopsis>
22      <command>gpsrinex</command>
23      <arg choice="opt">-D <replaceable>debuglevel</replaceable></arg>
24      <arg choice="opt">-f <replaceable>filename</replaceable></arg>
25      <arg choice="opt">-h</arg>
26      <arg choice="opt">-i <replaceable>interval</replaceable></arg>
27      <arg choice="opt">-n <replaceable>count</replaceable></arg>
28      <arg choice="opt">-V</arg>
29      <group>
30        <replaceable>server</replaceable>
31        <group>
32          <replaceable>:port</replaceable>
33          <group>
34            <replaceable>:device</replaceable>
35          </group>
36        </group>
37      </group>
38    </cmdsynopsis>
39  </refsynopsisdiv>
40  <refsect1 id="description">
41    <title>DESCRIPTION</title>
42    <para>
43      <application>gpsrinex</application> is a tool to connect to
44<application>gpsd</application> and output the received raw measurements
45as a RINEX 3 observation file.  This is useful for sending raw measurements
46(pseudorange and carrierphase) from <application>gpsd</application> to
47a Precise Point Positioning (PPP) program or service.</para>
48    <para>
49      <application>gpsrinex</application> does not require root
50privileges, and can be run concurrently with other tools connecting
51to a local or remote <application>gpsd</application> without causing
52problems.</para>
53    <para>gpsrinex needs the GPS receiver to be sending raw measurements
54to <application>gpsd</application>.  Only a few GPS have this capability.
55In addition, the <application>gpsd</application> driver for that GPS
56must support raw mode.  Currently only the u-blox driver has this support.
57Only a few u-blox 8 GPS implment the required UBX-RXM-RAWX message.  The
58NEO-M8T is known to work, but requires configuration with
59<application>ubxtool</application>.</para>
60    <para>RINEX has its own definitions and abbreviations.  Be
61sure to consult their documentation.  An observation file (.obs)
62contains data sets, called epochs, that contain the pseudorange
63and carrierphase for each satellite seen.</para>
64    <para>
65      <application>gpsrinex</application> by default will acquire
6620 epochs spaced apart by 30 seconds.  That will take 10 minutes to
67complete.  Most users consider the 30 second interval to be optimal.
68Many PPP programs require at least 1 or 2 hours data, but no more than
6924 or 48 hours of data.  Most users consider 4 to 6 hours of data
70as a minimum for good accuracy.  Additional hours will not yield much
71improvement. </para>
72    <para>The output will consist of one RINEX 3 observation file that
73is ready to be read by your PPP program.  The default filename will be
74in the form: gpsrinexYYYYJJJHHMMSS.obs.  You can override this filename
75with the -f option.</para>
76    <para>Optionally a server, TCP/IP port number and remote device can
77be given.  If omitted, <application>gpsrinex</application> connects to
78localhost on the default port (2947) and watches all devices opened by
79<application>gpsd</application>.</para>
80  </refsect1>
81  <refsect1 id="options">
82    <title>OPTIONS</title>
83    <para>-D [debuglevel]  set debug level to [debuglevel].</para>
84    <para>-f [filename] save RINEX into [filename].</para>
85    <para>-h makes <application>gpsrinex</application> print
86a usage message and exit.</para>
87    <para>-i [interval] wait [interval] seconds between epochs.  OPUS
88accepts intervals of 1, 2, 3, 5, 10, 15 or,30 seconds.  OPUS then
89reduces the data to 30 second intervals.  Defeault is 30.</para>
90    <para>-n [count] causes [count] epochs to be output.  OPUS requires a
91minimum af 15 minutes, and a maximum of 48 hours, of data.</para>
92    <para>-V makes <application>gpsrinex</application> print
93its version and exit.</para>
94  </refsect1>
95  <refsect1 id="exampletitle">
96    <title>EXAMPLES</title>
97    <para>Example 1:</para>
98    <para>Create a 4 hour .obs file.  With a running
99<application>gpsd</application> accessible on the localhost do all of
100the following, in order.  Order matters.</para>
101    <para>The raw measurement messages are long.  Be sure your serial port
102speed is high enough:
103<programlisting>
104gpsctl -s 115200
105</programlisting></para>
106    <para>Disable all NMEA messages, and enable binary messages:
107<programlisting>
108ubxtool -d NMEA
109ubxtool -e BINARY
110</programlisting></para>
111    <para>The NEO-M8N will only reliably output raw measurements
112when only the GPS and QZSS constellations are enabled.  If your PPP
113service can use GLONASS, then enable that as well.  Be sure to
114disable, before enable, so as not to momentarily have too many
115constellations selected.
116<application>ubxtool</application>, as recommended by u-blox, enables
117the QZSS constellation in tandem with GPS.  Disable all constellations,
118except GPS (and QZSS):
119
120<programlisting>
121ubxtool -d BEIDOU
122ubxtool -d GALILEO
123ubxtool -d GLONASS
124ubxtool -d SBAS
125ubxtool -e GPS
126</programlisting></para>
127    <para>Verify the constellations enabled:
128<programlisting>
129ubxtool -p CFG-GNSS
130</programlisting></para>
131    <para>Enable the good stuff, the raw measurement messages:
132<programlisting>
133ubxtool -e RAWX
134</programlisting></para>
135    <para>Verify raw data messages are being sent:
136<programlisting>
137ubxtool | fgrep RAWX
138</programlisting>
139You should see this output:
140<programlisting>
141UBX-RXM-RAWX:
142UBX-RXM-RAWX:
143</programlisting></para>
144    <para>Collect 4 hours of samples at 30 second intervals, save the
145RINEX 3 observations in the file today.obs:
146<programlisting>
147gpsrinex -i 30 -n 480 -f today.obs
148</programlisting></para>
149    <para>Wait 4 hours.  Enjoy a meal, or do some exercise.  When
150<application>gpsrinex</application> finishes, upload the file today.obs
151to your favorite PPP service.</para>
152    <para>Example 2:</para>
153    <para>Collect raw masurement data from a remote gpsd.  The
154process it later with <application>gpsrinex</application> and
155<application>gpsprof</application>.</para>
156    <para>Ensure the GPS is configured properly, as shown in Example 1.</para>
157    <para>Grab 4 hours of raw live data from remote
158<application>gpsd</application> at 10.168.1.2:
159<programlisting>
160gpspipe -x 14400 -R 10.168.1.2 > 4h-raw.ubx
161</programlisting></para>
162    <para>When <application>gpspipe</application> is complete, feed the
163data to <application>gpsfake</application>:
164<programlisting>
165gpsfake -1 -P 3000 4h-raw.ubx
166</programlisting></para>
167    <para>In another window, feed the data to
168<application>gpsrinex</application>.  Use -n 10000000 so that
169all the data from the raw file is used::
170<programlisting>
171gpsrinex -i 30 -n 1000000
172</programlisting></para>
173    <para>Repeat the process with
174<application>gpsfake</application> to send the data to
175<application>gpsprof</application>.</para>
176  </refsect1>
177  <refsect1 id="see_also">
178    <title>SEE ALSO</title>
179    <para>One service known to work with obsrinex output is at:
180https://webapp.geod.nrcan.gc.ca/geod/tools-outils/ppp.php</para>
181    <para>OPUS requires 2 frequency observation files.
182https://www.ngs.noaa.gov/OPUS/</para>
183    <para>The curious can find the RINEX 3.03 format described here:
184ftp://igs.org/pub/data/format/rinex303_update1.pdf</para>
185    <para>
186      <citerefentry>
187        <refentrytitle>gpsd</refentrytitle>
188        <manvolnum>8</manvolnum>
189      </citerefentry>,
190<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
191<citerefentry><refentrytitle>ubxtool</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
192</para>
193  </refsect1>
194  <refsect1 id="maintainer">
195    <title>AUTHOR</title>
196    <para>Gary E. Miller <email>gem@rellim.com</email>.</para>
197  </refsect1>
198</refentry>
199