<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright 2020 by the GPSD project
SPDX-License-Identifier: BSD-2-clause
-->
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='gpssubframe.1'>
 <refentryinfo>
  <date>6 December 2020</date>
 </refentryinfo>
 <refmeta>
  <refentrytitle>gpssubframe</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
 </refmeta>
 <refnamediv id='name'>
  <refname>gpssubframe</refname>
  <refpurpose>tool to dump subframe sentences from gpsd</refpurpose>
 </refnamediv>
 <refsynopsisdiv id='synopsis'>
  <cmdsynopsis>
   <command>gpssubframe</command>
   <arg choice='opt'>-?</arg>
   <arg choice='opt'>--count <replaceable>COUNT</replaceable>
   </arg>
   <arg choice='opt'>--debug <replaceable>LVL</replaceable>
   </arg>
   <arg choice='opt'>--desc</arg>
   <arg choice='opt'>--device <replaceable>DEVICE</replaceable>
   </arg>
   <arg choice='opt'>--file <replaceable>FILE</replaceable>
   </arg>
   <arg choice='opt'>--help</arg>
   <arg choice='opt'>--host <replaceable>HOST</replaceable>
   </arg>
   <arg choice='opt'>--load <replaceable>FILE</replaceable>
   </arg>
   <arg choice='opt'>--port <replaceable>PORT</replaceable>
   </arg>
   <arg choice='opt'>--progress</arg>
   <arg choice='opt'>--satpos</arg>
   <arg choice='opt'>--save <replaceable>FILE</replaceable>
   </arg>
   <arg choice='opt'>--seconds <replaceable>SECONDS</replaceable>
   </arg>
   <arg choice='opt'>--test</arg>
   <arg choice='opt'>--time <replaceable>SECONDS</replaceable>
   </arg>
   <arg choice='opt'>--version</arg>
   <arg choice='opt'>-D <replaceable>LVL</replaceable>
   </arg>
   <arg choice='opt'>-f <replaceable>FILE</replaceable>
   </arg>
   <arg choice='opt'>-h</arg>
   <arg choice='opt'>-n <replaceable>COUNT</replaceable>
   </arg>
   <arg choice='opt'>-V</arg>
   <arg choice='opt'>-x <replaceable>SECONDS</replaceable>
   </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>gpssubframe</application> is a tool to connect
to <application>gpsd</application> and dump decoded subframe data
to stdout.  This is only useful if your GNSS receiver can output
GPS subframe messages, and is configured to do so.  A working
knowledge of IS-GPS-200 is also required.  Keep your copy close at
hand.</para>
  <para>
   <application>gpssubframe</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 program will accumulate subframe message and output them
by GPS satellite number on exit.  By default the program never exits
unless the user selects the number of seconds to run or number of
messages to capture.  </para>
  <para>By default <application>gpssubframe</application> connects to
a <application>gpsd</application> running on the local host.  Optionally
a host, TCP/IP port number and remote device can be given.  </para>
 </refsect1>
 <refsect1 id='options'>
  <title>OPTIONS</title>
  <variablelist remap='TP'>
   <varlistentry>
    <term>
     <option>-?</option>
    </term>
    <term>
     <option>-h</option>
    </term>
    <term>
     <option>--help</option>
    </term>
    <listitem>
     <para>-Print a usage message and exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-c COUNT</option>
    </term>
    <term>
     <option>--count COUNT</option>
    </term>
    <listitem>
     <para>Exit after COUNT subframe messages.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--device DEVICE</option>
    </term>
    <listitem>
     <para>Connect to device DEVICE on gpsd host.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-D LVL</option>
    </term>
    <term>
     <option>--debug LVL</option>
    </term>
    <listitem>
     <para>Set debug level to LVL.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--file FILE</option>
    </term>
    <listitem>
     <para>Read JSON from FILE instead of from gpsd..</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--host HOST</option>
    </term>
    <listitem>
     <para>Connect to gpsd on host HOST.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--port PORT</option>
    </term>
    <listitem>
     <para>Connect to gpsd on port PORT.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--progress</option>
    </term>
    <listitem>
     <para>Print progress reports as messages are received.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--satpos</option>
    </term>
    <listitem>
     <para>Compute GPS satellite positions before exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--time SEC</option>
    </term>
    <listitem>
     <para>Compute satellite position at time SEC in POSIX seconds.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--test</option>
    </term>
    <listitem>
     <para>Run <option>--satpos</option> selftest code.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-V</option>
    </term>
    <term>
     <option>--version</option>
    </term>
    <listitem>
     <para>Print the program version, then exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-x SEC</option>
    </term>
    <term>
     <option>--seconds SEC</option>
    </term>
    <listitem>
     <para>Seconds of messages to parse. 0 to disable.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1 id='examples'>
  <title>EXAMPLES</title>
  <para>
   First connfigure a u-blox 9-series to output subframe messages.
Then have <application>gpssubframe</application> gather one complete
set of subframes, then print the data organized by GPS satellite number.
Then calculate and print the known satellite positions as well as the
azimuth, elevation, and range from the current position:
   <programlisting>
ubxtool -P 22 -e SFRBX
gpssubframe -x 750 --satpos
   </programlisting>
  </para>
  <para>If staring at a blank screen for 12.5 minutes is too stressful,
then enable progress messages:
   <programlisting>
gpssubframe -x 750 --satpos --progress
   </programlisting>
  </para>
 </refsect1>
 <refsect1 id='see_also'>
  <title>SEE ALSO</title>
  <para>
   <citerefentry>
    <refentrytitle>gpsd</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gps</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsprof</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsfake</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsctl</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpscat</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>.
  </para>
  <para>
IS-GPS-200 "NAVSTAR GPS Space Segment/Navigation User Segment Interfaces"
  </para>
 </refsect1>
 <refsect1 id='maintainer'>
  <title>AUTHOR</title>
  <para>Gary E. Miller <email>gem@rellim.com</email>.</para>
 </refsect1>
</refentry>
