1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright (c) 2010 by the GPSD project
BSD terms apply: see the file COPYING in the distribution root for details.
-->
<!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>13 Jul 2005</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 RTCM or AIVDM streams into a readable format</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>
<cmdsynopsis>
<command>gpsdecode</command>
<arg choice='opt'>-c</arg>
<arg choice='opt'>-d</arg>
<arg choice='opt'>-e</arg>
<arg choice='opt'>-j</arg>
<arg choice='opt'>-u</arg>
<arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
<arg choice='opt'>-V</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id='description'><title>DESCRIPTION</title>
<para>This tool is a decoder/encoder for 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>Two of the 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.</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>
</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 text dump on standard
output. This is the default behavior.</para>
<para>RTCM2 will be dumped in one of the formats of
<citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>
on standard output. </para>
<para>The <option>-e</option> option option tells the program to
encode a text dump in one of the formats of
<citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>
to standard output. This option is a placeholder: support for RTCM2
encoding from the Sager format has been removed</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>-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>
<para>The <option>-V</option> option directs the program to emit its
version number, then exit.</para>
<para>The <option>-D</option> option sets a debug verbosity level. It is
mainly of interest to developers.</para>
</refsect1>
<refsect1 id='json_ais'><title>AIS DUMP FORMATS</title>
<para>Without the <option>-j</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>
<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>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1 id='maintainer'><title>AUTHOR</title>
<para>Eric S. Raymond <email>esr@thyrsus.com</email>. This is a
somewhat hacked version of an RTCM decoder originally written by
Wolfgang Rupprecht. There is a project page for
<application>gpsd</application> <ulink
url="http://gpsd.berlios.de/">here</ulink>.</para>
</refsect1>
</refentry>
|
