gpsdecode.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='gpsdecode.1'>
  10 <refentryinfo><date>13 Jul 2005</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>gpsdecode</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>gpsdecode</refname>
  19 <refpurpose>decode RTCM or AIVDM streams into a readable format</refpurpose>
  20 </refnamediv>
  21 <refsynopsisdiv id='synopsis'>
  22
  23 <cmdsynopsis>
  24   <command>gpsdecode</command>
  25       <arg choice='opt'>-c</arg>
  26       <arg choice='opt'>-d</arg>
  27       <arg choice='opt'>-e</arg>
  28       <arg choice='opt'>-j</arg>
  29       <arg choice='opt'>-u</arg>
  30       <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  31       <arg choice='opt'>-V</arg>
  32 </cmdsynopsis>
  33 </refsynopsisdiv>
  34
  35 <refsect1 id='description'><title>DESCRIPTION</title>
  36
  37 <para>This tool is a decoder/encoder for various binary packet formats
  38 associated with GPS and differential-correction services.  It produces
  39 a text dump on standard output from binary on standard input, or
  40 binary packets on standard output from text on standard input, and
  41 aims to be 100% information-preserving in both directions.  As well as
  42 data, the decoder also prints decoder status messages to standard
  43 error as necessary.</para>
  44
  45 <para>Two of the supported formats are RTCM 2 and 3, a pair of obscure
  46 and complicated serial protocol used for broadcasting pseudorange
  47 corrections from differential-GPS reference stations. You can use this
  48 mode of the tool with
  49 <citerefentry><refentrytitle>nc</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  50 to examine RTCM feeds from DGPSIP servers or Ntrip broadcasters. The
  51 decoder dump formats for RTCM2 are described in
  52 <citerefentry><refentrytitle>rtcm</refentrytitle><manvolnum>5</manvolnum></citerefentry>;
  53 these lines go to standard output.</para>
  54
  55 <para>Another supported format is AIVDM.  This is the sentence format
  56 used by the marine Automatic Identification System.  This can be
  57 decoded, but not yet encoded.</para>
  58
  59 </refsect1>
  60 <refsect1 id='options'><title>OPTIONS</title>
  61
  62 <para>The <option>-d</option> option tells the program to decode
  63 packets presented on standard input to a text dump on standard
  64 output. This is the default behavior.</para>
  65
  66 <para>RTCM2 will be dumped in one of the formats of
  67 <citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  68 on standard output. </para>
  69
  70 <para>The <option>-e</option> option option tells the program to
  71 encode a text dump in one of the formats of
  72 <citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  73 to standard output. This option is a placeholder: support for RTCM2
  74 encoding from the Sager format has been removed</para>
  75
  76 <para>The <option>-u</option> suppresses scaling of AIS data to float quantities
  77 and text expansion of numeric codes.  A dump with this option is
  78 lossless.</para>
  79
  80 <para>The <option>-j</option> sets the dump format to JSON, with
  81 each each field preceded by a quoted label and colon and the
  82 entire dump line wrapped in curly braces.</para>
  83
  84 <para>The <option>-c</option> sets the AIS dump format to separate
  85 fields with an ASCII pipe symbol.  Fields are dumped in the order they
  86 occur in the AIS packet. Numerics are not scaled. Strings are unpacked
  87 from six-bit to full ASCII</para>
  88
  89 <para>The <option>-V</option> option directs the program to emit its
  90 version number, then exit.</para>
  91
  92 <para>The <option>-D</option> option sets a debug verbosity level.  It is
  93 mainly of interest to developers.</para>
  94
  95 </refsect1>
  96 <refsect1 id='json_ais'><title>AIS DUMP FORMATS</title>
  97
  98 <para>Without the <option>-j</option> option, dump lines are values of AIS
  99 payload fields, pipe-separated, in the order that they occur in the
 100 payload. Spans of fields expressing a date are emitted as an ISO8601
 101 timestamp (look for colons and the trailing Z indicating Zulu/UTC
 102 time), and the 19-bit group of TDMA status fields found at the end of
 103 message types 1-4 are are dumped as a single unsigned integer (in hex
 104 preceded by "0x"). Unused regional-authority fields are also dumped
 105 (in hex preceded by "0x"). Variable-length binary fields are dumped as
 106 an integer bit length, followed by a colon, followed by a hex
 107 dump.</para>
 108
 109 <para>By default, certain scaling and conversion operations are
 110 performed for the output.  Latitudes and longitudes are scaled to
 111 decimal degrees rather than the native AIS unit of 1/10000th of a
 112 minute of arc.  Ship (but not air) speeds are scaled to knots rather
 113 than tenth-of-knot units.  Navigation status and positioning-system
 114 type are dumped as text strings rather than IAS numeric codes. Rate of
 115 turn may appear as "nan" if is unavailable, or as one of the strings
 116 "fastright" or "fastleft" if it is out of the IAS encoding range;
 117 otherwise it is quadratically mapped back to the turn sensor number in
 118 degrees per minute. Vessel draughts are converted to decimal meters
 119 rather than native AIS decimeters.</para>
 120
 121 <para>With the <option>-j</option> option, the AIS dump format changes
 122 to JSON.  Data fields are handled as described above in scaled and
 123 unscaled modes, but are values attached to JSON attributes as
 124 described in <citetitle><ulink
 125 url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol
 126 decoding</ulink></citetitle>.</para>
 127
 128 </refsect1>
 129 <refsect1 id='standard'><title>APPLICABLE STANDARDS</title>
 130
 131 <para>The applicable standard for V2 is <citetitle>RTCM Recommended
 132 Standards for Differential NAVSTAR GPS Service</citetitle> RTCM Paper
 133 194-93/SC 104-STD.</para>
 134
 135 <para>Note that <application>gpsdecode</application> presently
 136 recognizes only the 2.1 level of RTCM; the protocol was revised up to
 137 a version 2.3 including additional messages relating to GLONASS and
 138 real-time kinematics before being deprecated in favor of V3. It is
 139 now semi-obsolete.</para>
 140
 141 <para>The applicable standard for V3 is <citetitle>RTCM Standard
 142 10403.1 for Differential GNSS Services - Version 3</citetitle> RTCM
 143 Paper 177-2006-SC104-STD.</para>
 144
 145 <para>Ordering instructions for the RTCM standards are accessible from
 146 the website of the <ulink url='http://www.rtcm.org/'>Radio Technical
 147 Commission for Maritime Services</ulink> under "Publications".</para>
 148
 149 <para>The applicable standard for AIVDM is <citetitle>ITU-R M.1371:
 150 ITU Recommendation on the Technical Characteristics for a Universal
 151 Shipborne Automatic Identification System (AIS) using Time Division
 152 Multiple Access in the Maritime Mobile Band</citetitle>, A more
 153 accessible description can be found at <citetitle><ulink
 154 url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol
 155 decoding</ulink></citetitle> on the references page of the
 156 GPSD project website.</para>
 157
 158 </refsect1>
 159 <refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title>
 160
 161 <para>AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.</para>
 162
 163 <para>RTCM3 decoding is buggy and incomplete.</para>
 164
 165 <para>RTCM2 represents floating-point quantities as an integer
 166 multiple of a fixed scale factor.  Editing an RTCM2 dump can produce
 167 numbers that are not an integer multiple of the scale factor for their
 168 field.  If you do this, the value actually packed into binary RTCM2
 169 will be rounded down to the nearest scale unit, and dumping will show
 170 slightly different numbers than those you entered.  This bug could be
 171 fixed by supporting the <option>-u</option> option to suppress
 172 scaling.</para>
 173
 174 <para>The RTCM2 decoder logic is sufficiently convoluted to confuse some
 175 compiler optimizers, notably in GCC 3.x at -O2, into generating bad
 176 code.</para>
 177
 178 <para>Older version of this utility used comma as a field separator with
 179 the <option>-c</option> option.  This was a mistake, as ship name and
 180 other string fields can contain commas.</para>
 181
 182 </refsect1>
 183 <refsect1 id='see_also'><title>SEE ALSO</title>
 184 <para>
 185 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 186 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 187 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 190 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 191 <citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 192 </para>
 193 </refsect1>
 194 <refsect1 id='maintainer'><title>AUTHOR</title>
 195
 196 <para>Eric S. Raymond <email>esr@thyrsus.com</email>.  This is a
 197 somewhat hacked version of an RTCM decoder originally written by
 198 Wolfgang Rupprecht.  There is a project page for
 199 <application>gpsd</application> <ulink
 200 url="http://gpsd.berlios.de/">here</ulink>.</para>
 201
 202 </refsect1>
 203
 204 </refentry>