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