<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright 2010 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='gpsdecode.1'>
 <refentryinfo>
  <date>6 December 2020</date>
 </refentryinfo>
 <refmeta>
  <refentrytitle>gpsdecode</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
 </refmeta>
 <refnamediv id='name'>
  <refname>gpsdecode</refname>
  <refpurpose>decode GPS, RTCM or AIS streams into a readable format</refpurpose>
 </refnamediv>
 <refsynopsisdiv id='synopsis'>
  <cmdsynopsis>
   <command>gpsdecode</command>
   <arg choice='opt'>-?</arg>
   <arg choice='opt'>--ais</arg>
   <arg choice='opt'>--decode</arg>
   <arg choice='opt'>--debug <replaceable>LVL</replaceable>
   </arg>
   <arg choice='opt'>--encode</arg>
   <arg choice='opt'>--help</arg>
   <arg choice='opt'>--json</arg>
   <arg choice='opt'>--minlength</arg>
   <arg choice='opt'>--nmea</arg>
   <arg choice='opt'>--split24</arg>
   <arg choice='opt'>--types <replaceable>typelist</replaceable>
   </arg>
   <arg choice='opt'>--unscaled</arg>
   <arg choice='opt'>--verbose</arg>
   <arg choice='opt'>--version</arg>
   <arg choice='opt'>-c</arg>
   <arg choice='opt'>-d</arg>
   <arg choice='opt'>-D <replaceable>LVL</replaceable>
   </arg>
   <arg choice='opt'>-e</arg>
   <arg choice='opt'>-h</arg>
   <arg choice='opt'>-j</arg>
   <arg choice='opt'>-m</arg>
   <arg choice='opt'>-n</arg>
   <arg choice='opt'>-s</arg>
   <arg choice='opt'>-t <replaceable>typelist</replaceable>
   </arg>
   <arg choice='opt'>-u</arg>
   <arg choice='opt'>-v</arg>
   <arg choice='opt'>-V</arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1 id='description'>
  <title>DESCRIPTION</title>
  <para>This tool is a batch-mode decoder for NMEA and various binary
packet formats associated with GPS, AIS, and differential-correction
services.  It produces a JSON dump on standard output from binary on
standard input. The JSON is the same format documented in
<citerefentry>
    <refentrytitle>gpsd</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>;
this tool uses the same decoding logic as gpsd, but with a simpler
interface intended for batch processing of data files.</para>
  <para>All sensor-input formats known to the GPSD project can be
decoded by this tool.  These include: NMEA, AIVDM (the NMEA-derived
sentence format used by AIS, the marine Automatic Identification
System), RTCM2, and all supported GPS binary formats (notably
including SiRF). See
<citerefentry>
    <refentrytitle>gpsd</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>
for applicable standards and known limitations of the decoding
logic.</para>
  <para>You can use this tool with
<citerefentry>
    <refentrytitle>nc</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>
to examine AIS feeds from AIS pooling services, RTCM feeds from RTCM
receivers or NTRIP broadcasters.</para>
 </refsect1>
 <refsect1 id='options'>
  <title>OPTIONS</title>
  <variablelist>
   <varlistentry>
    <term>
     <option>-?</option>
    </term>
    <term>
     <option>-h</option>
    </term>
    <term>
     <option>--help</option>
    </term>
    <listitem>
     <para>Output a usage mssage, then exit.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-c</option>
    </term>
    <term>
     <option>--json</option>
    </term>
    <listitem>
     <para>Sets the AIS dump format to separate
fields with an ASCII pipe symbol.  Fields are dumped in the order they
occur in the AIS packet. Numerics are not scaled (<option>-u</option> is
forced). Strings are unpacked from six-bit to full ASCII</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-d</option>
    </term>
    <term>
     <option>--decode</option>
    </term>
    <listitem>
     <para>Decode
packets presented on standard input to standard output. This is the
default behavior.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-D LVL</option>
    </term>
    <term>
     <option>--debug LVL</option>
    </term>
    <listitem>
     <para>Set the debug verbosity
level to LVL. It is mainly of interest to for troubleshooting.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-e</option>
    </term>
    <term>
     <option>--encode</option>
    </term>
    <listitem>
     <para>Encode JSON on standard input to JSON on standard output. This option
is only useful for regression-testing of the JSON dumping and parsing
code.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-j</option>
    </term>
    <term>
     <option>--json</option>
    </term>
    <listitem>
     <para>Sets the output dump format to JSON (the default behavior).</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-m</option>
    </term>
    <term>
     <option>--minlength</option>
    </term>
    <listitem>
     <para>Dump minimum lengths for
each packet type in the input (ignoring comment packets).  This is
probably of interest only to GSD developers.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-n</option>
    </term>
    <term>
     <option>--nmea</option>
    </term>
    <listitem>
     <para>Dump the generated pseudo-NME0183.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-s</option>
    </term>
    <term>
     <option>--split24</option>
    </term>
    <listitem>
     <para>Report AIS Type 24 sentence halves separately rather than attempting to
aggregate them.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-t TYPES</option>
    </term>
    <term>
     <option>--types TYPES</option>
    </term>
    <listitem>
     <para>A comma-separated list of
numeric types.  Packets with a numeric AIS, RTCM2, or RTCM3 type are
passed through and output only if they match a type in the
list. Packets of other kinds (in particular GPS packets) are
passed through unconditionally.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-u</option>
    </term>
    <term>
     <option>--unsscaled</option>
    </term>
    <listitem>
     <para>Suppress scaling of AIS data
to float quantities and text expansion of numeric codes. A dump with
this option is lossless.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-v</option>
    </term>
    <term>
     <option>--verbose</option>
    </term>
    <listitem>
     <para>Dump textual packets
to output as they are received on input, immediately preceding
corresponding output.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-V</option>
    </term>
    <term>
     <option>--version</option>
    </term>
    <listitem>
     <para>Print version number, then exit.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1 id='json_ais'>
  <title>AIS DSV FORMAT</title>
  <para>With the <option>-c, --ais</option> option, dump lines are values of AIS
payload fields, pipe-separated, in the order that they occur in the
payload. Spans of fields expressing a date are emitted as an ISO8601
timestamp (look for colons and the trailing Z indicating Zulu/UTC
time), and the 19-bit group of TDMA status fields found at the end of
message types 1-4 are are dumped as a single unsigned integer (in hex
preceded by "0x"). Unused regional-authority fields are also dumped
(in hex preceded by "0x"). Variable-length binary fields are dumped as
an integer bit length, followed by a colon, followed by a hex
dump.</para>
 </refsect1>
 <refsect1 id='see_also'>
  <title>SEE ALSO</title>
  <para>
   <citerefentry>
    <refentrytitle>gpsd</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsctl</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsdctl</refentrytitle>
    <manvolnum>8</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gps</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>libgps</refentrytitle>
    <manvolnum>3</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>libgpsmm</refentrytitle>
    <manvolnum>3</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsprof</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
<citerefentry>
    <refentrytitle>gpsfake</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>,
</para>
 </refsect1>
 <refsect1 id='maintainer'>
  <title>AUTHOR</title>
  <para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para>
 </refsect1>
</refentry>
