diff options
author | Eric S. Raymond <esr@thyrsus.com> | 2011-02-23 10:44:01 -0500 |
---|---|---|
committer | Eric S. Raymond <esr@thyrsus.com> | 2011-02-23 10:44:01 -0500 |
commit | 97309b267e03834b3abca9dd6160d9c51b195a0f (patch) | |
tree | 646c9b2b76e47f2d12fb323846acc40ffe0c1c2c | |
parent | ca30601d5ce27bcb5c47cb261d017347da3872fe (diff) | |
download | gpsd-97309b267e03834b3abca9dd6160d9c51b195a0f.tar.gz |
Documentation update.
-rw-r--r-- | gpsd.xml | 48 | ||||
-rw-r--r-- | gpsdecode.xml | 142 |
2 files changed, 73 insertions, 117 deletions
@@ -2229,11 +2229,26 @@ and a "scaled" field telling whether the remainder of the fields are dumped in scaled or unscaled form. It will also contain a "device" field naming the data source. Other fields have names and types as specified in the <ulink -url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO Protocol -Decoding</ulink> document; each message field table may be directly +url="http://gpsd.berlios.de/AIVDM.html">"AIVDM/AIVDO Protocol +Decoding"</ulink> document; each message field table may be directly interpreted as a specification for the members of the corresponding JSON object type.</para> +<para>By default, certain scaling and conversion operations are +performed for JSON output. Latitudes and longitudes are scaled to +decimal degrees rather than the native AIS unit of 1/10000th of a +minute of arc. Ship (but not air) speeds are scaled to knots rather +than tenth-of-knot units. Navigation status and positioning-system +type are dumped as text strings rather than IAS numeric codes. Rate of +turn may appear as "nan" if is unavailable, or as one of the strings +"fastright" or "fastleft" if it is out of the IAS encoding range; +otherwise it is quadratically mapped back to the turn sensor number in +degrees per minute. Vessel draughts are converted to decimal meters +rather than native AIS decimeters. Various other scaling conversions +are described in <ulink +url="http://gpsd.berlios.de/AIVDM.html">"AIVDM/AIVDO Protocol +Decoding"</ulink>.</para> + </refsect1> <refsect1 id='subframe'><title>SUBFRAME DUMP FORMATS</title> @@ -2567,6 +2582,14 @@ involves both a lot of mathematical black art and fragile device-dependent assumptions. This code has been bug-prone in tbe past and problems may still lurk there.</para> +<para>AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.</para> + +<para>RTCM3 decoding is buggy and incomplete.</para> + +<para>The RTCM2 decoder logic is sufficiently convoluted to confuse some +compiler optimizers, notably in GCC 3.x at -O2, into generating bad +code.</para> + </refsect1> <refsect1 id='files'><title>FILES</title> @@ -2631,23 +2654,36 @@ degrees, not the hybrid degree/minute format described in the NMEA standard.</para> <para>Differential-GPS corrections are conveyed by the RTCM-104 -proocol. The applicable standard for RTCM-104 V2 is <citetitle>RTCM +protocol. The applicable standard for RTCM-104 V2 is <citetitle>RTCM Recommended Standards for Differential NAVSTAR GPS Service</citetitle> RTCM Paper 194-93/SC 104-STD. The applicable standard for RTCM-104 V3 is <citetitle>RTCM Standard 10403.1 for Differential GNSS Services - Version 3</citetitle> RTCM Paper 177-2006-SC104-STD.</para> +<para>Note that GPSD presently recognizes only the 2.1 level of RTCM; +the protocol was revised up to a version 2.3 including additional +messages relating to GLONASS and real-time kinematics before being +deprecated in favor of V3. It is now semi-obsolete.</para> + +<para>Ordering instructions for the RTCM standards are accessible from +the website of the <ulink url='http://www.rtcm.org/'>Radio Technical +Commission for Maritime Services</ulink> under "Publications".</para> + <para>AIS is defined by ITU Recommendation M.1371, <citetitle>Technical Characteristics for a Universal Shipborne Automatic Identification System Using Time Division Multiple -Access</citetitle>. The AIVDM/AIVDO format understood by this progeam +Access</citetitle>. The AIVDM/AIVDO format understood by this program is defined by IEC-PAS 61162-100, <citetitle>Maritime navigation and -radiocommunication equipment and systems</citetitle></para> +radiocommunication equipment and systems</citetitle>.A more +accessible description of both can be found at <citetitle><ulink +url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol +decoding</ulink></citetitle> on the references page of the +GPSD project website.</para> <para>Subframe data is defined by IS-GPS-200E, <citetitle>GLOBAL POSITIONING SYSTEM WING (GPSW) SYSTEMS ENGINEERING & INTEGRATION, INTERFACE SPECIFICATION IS-GPS-200 Revision E</citetitle>. The format -understood by this progeam is defined in Section 20 (Appendix II) of +understood by this program is defined in Section 20 (Appendix II) of the IS-GPS-200E, <citetitle>GPS NAVIGATION DATA STRUCTURE FOR DATA, D(t)</citetitle></para> diff --git a/gpsdecode.xml b/gpsdecode.xml index c3cbfde9..2d46989f 100644 --- a/gpsdecode.xml +++ b/gpsdecode.xml @@ -34,58 +34,51 @@ BSD terms apply: see the file COPYING in the distribution root for details. <refsect1 id='description'><title>DESCRIPTION</title> -<para>This tool is a decoder/encoder for NMEA and various binary packet formats -associated with GPS and differential-correction services. It produces -a text dump on standard output from binary on standard input, or -binary packets on standard output from text on standard input, and -aims to be 100% information-preserving in both directions. As well as -data, the decoder also prints decoder status messages to standard -error as necessary.</para> - -<para>NMEA and GPS binary formats can be decoded to JSON (the same -format used by -<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>) -but not encoded.</para> - -<para>Two of the supported formats are RTCM 2 and 3, a pair of obscure +<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 +for batch processing of data files. +</para> + +<para>NMEA, AIVDM (the NMEA-derived sentence format +used by AIS, the marine Automatic Identification System), and all +GPS binary formats known to +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry> +can be decoded.</para> + +<para>Two more supported formats are RTCM 2 and 3, a pair of obscure and complicated serial protocol used for broadcasting pseudorange corrections from differential-GPS reference stations. You can use this mode of the tool with <citerefentry><refentrytitle>nc</refentrytitle><manvolnum>1</manvolnum></citerefentry> -to examine RTCM feeds from DGPSIP servers or Ntrip broadcasters. The -decoder dump formats for RTCM2 are described in -<citerefentry><refentrytitle>rtcm</refentrytitle><manvolnum>5</manvolnum></citerefentry>; -these lines go to standard output. RTCM2 can be decoded and encoded; RTCM3 -can only be decoded, and support is presently incomplete.</para> - -<para>Another supported format is AIVDM. This is the sentence format -used by the marine Automatic Identification System. This can be -decoded, but not yet encoded.</para> +to examine RTCM feeds from DGPSIP servers or NTRIP broadcasters.</para> </refsect1> <refsect1 id='options'><title>OPTIONS</title> <para>The <option>-d</option> option tells the program to decode -packets presented on standard input to a JSON dump on standard -output. This is the default behavior.</para> +packets presented on standard input to standard output. This is the +default behavior.</para> <para>The <option>-e</option> option option tells the program to -encode a text dump to binary on standard output. This option is a -placeholder: support for RTCM2 encoding from the Sager format has been -removed</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> -<para>The <option>-u</option> suppresses scaling of AIS data to float quantities -and text expansion of numeric codes. A dump with this option is -lossless.</para> +<para>The <option>-u</option> suppresses scaling of AIS data to float +quantities and text expansion of numeric codes. A dump with this +option is lossless.</para> -<para>The <option>-j</option> sets the dump format to JSON, with -each each field preceded by a quoted label and colon and the -entire dump line wrapped in curly braces.</para> +<para>The <option>-j</option> explicitly sets the output dump format +to JSON (the default behavior).</para> <para>The <option>-c</option> 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. Strings are unpacked -from six-bit to full ASCII</para> +occur in the AIS packet. Numerics are not scaled (-u is +forced). Strings are unpacked from six-bit to full ASCII</para> <para>The <option>-V</option> option directs the program to emit its version number, then exit.</para> @@ -94,9 +87,9 @@ version number, then exit.</para> mainly of interest to developers.</para> </refsect1> -<refsect1 id='json_ais'><title>AIS DUMP FORMATS</title> +<refsect1 id='json_ais'><title>AIS DSV FORMAT</title> -<para>Without the <option>-j</option> option, dump lines are values of AIS +<para>With the <option>-c</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 @@ -107,79 +100,6 @@ preceded by "0x"). Unused regional-authority fields are also dumped an integer bit length, followed by a colon, followed by a hex dump.</para> -<para>By default, certain scaling and conversion operations are -performed for the output. Latitudes and longitudes are scaled to -decimal degrees rather than the native AIS unit of 1/10000th of a -minute of arc. Ship (but not air) speeds are scaled to knots rather -than tenth-of-knot units. Navigation status and positioning-system -type are dumped as text strings rather than IAS numeric codes. Rate of -turn may appear as "nan" if is unavailable, or as one of the strings -"fastright" or "fastleft" if it is out of the IAS encoding range; -otherwise it is quadratically mapped back to the turn sensor number in -degrees per minute. Vessel draughts are converted to decimal meters -rather than native AIS decimeters.</para> - -<para>With the <option>-j</option> option, the AIS dump format changes -to JSON. Data fields are handled as described above in scaled and -unscaled modes, but are values attached to JSON attributes as -described in <citetitle><ulink -url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol -decoding</ulink></citetitle>.</para> - -</refsect1> -<refsect1 id='standard'><title>APPLICABLE STANDARDS</title> - -<para>The applicable standard for V2 is <citetitle>RTCM Recommended -Standards for Differential NAVSTAR GPS Service</citetitle> RTCM Paper -194-93/SC 104-STD.</para> - -<para>Note that <application>gpsdecode</application> presently -recognizes only the 2.1 level of RTCM; the protocol was revised up to -a version 2.3 including additional messages relating to GLONASS and -real-time kinematics before being deprecated in favor of V3. It is -now semi-obsolete.</para> - -<para>The applicable standard for V3 is <citetitle>RTCM Standard -10403.1 for Differential GNSS Services - Version 3</citetitle> RTCM -Paper 177-2006-SC104-STD.</para> - -<para>Ordering instructions for the RTCM standards are accessible from -the website of the <ulink url='http://www.rtcm.org/'>Radio Technical -Commission for Maritime Services</ulink> under "Publications".</para> - -<para>The applicable standard for AIVDM is <citetitle>ITU-R M.1371: -ITU Recommendation on the Technical Characteristics for a Universal -Shipborne Automatic Identification System (AIS) using Time Division -Multiple Access in the Maritime Mobile Band</citetitle>, A more -accessible description can be found at <citetitle><ulink -url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol -decoding</ulink></citetitle> on the references page of the -GPSD project website.</para> - -</refsect1> -<refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title> - -<para>AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.</para> - -<para>RTCM3 decoding is buggy and incomplete.</para> - -<para>RTCM2 represents floating-point quantities as an integer -multiple of a fixed scale factor. Editing an RTCM2 dump can produce -numbers that are not an integer multiple of the scale factor for their -field. If you do this, the value actually packed into binary RTCM2 -will be rounded down to the nearest scale unit, and dumping will show -slightly different numbers than those you entered. This bug could be -fixed by supporting the <option>-u</option> option to suppress -scaling.</para> - -<para>The RTCM2 decoder logic is sufficiently convoluted to confuse some -compiler optimizers, notably in GCC 3.x at -O2, into generating bad -code.</para> - -<para>Older version of this utility used comma as a field separator with -the <option>-c</option> option. This was a mistake, as ship name and -other string fields can contain commas.</para> - </refsect1> <refsect1 id='see_also'><title>SEE ALSO</title> <para> |