dbfd133b54f3d8a14d1f931e414161a129963fba
[olsrd.git] / lib / pud / nmealib / include / nmea / sentence.h
1 /*
2  * This file is part of nmealib.
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program. If not, see <http://www.gnu.org/licenses/>.
16  */
17
18 /**
19  * Extended descriptions of sentences are taken from
20  *   http://www.gpsinformation.org/dale/nmea.htm
21  */
22
23 #ifndef __NMEA_SENTENCE_H__
24 #define __NMEA_SENTENCE_H__
25
26 #include <nmea/info.h>
27
28 #include <stdint.h>
29
30 #ifdef  __cplusplus
31 extern "C" {
32 #endif /* __cplusplus */
33
34 /**
35  * NMEA packets type which parsed and generated by library
36  */
37 enum nmeaPACKTYPE {
38         GPNON = 0,                      /**< Unknown packet type. */
39         GPGGA = (1 << 0),       /**< GGA - Essential fix data which provide 3D location and accuracy data. */
40         GPGSA = (1 << 1),       /**< GSA - GPS receiver operating mode, SVs used for navigation, and DOP values. */
41         GPGSV = (1 << 2),       /**< GSV - Number of SVs in view, PRN numbers, elevation, azimuth & SNR values. */
42         GPRMC = (1 << 3),       /**< RMC - Recommended Minimum Specific GPS/TRANSIT Data. */
43         GPVTG = (1 << 4)        /**< VTG - Actual track made good and speed over ground. */
44 };
45
46 /**
47  * GGA packet information structure (Global Positioning System Fix Data)
48  *
49  * <pre>
50  * GGA - essential fix data which provide 3D location and accuracy data.
51  *
52  * $GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47
53  *
54  * Where:
55  *      GGA          Global Positioning System Fix Data
56  *      123519       Fix taken at 12:35:19 UTC
57  *      4807.038,N   Latitude 48 deg 07.038' N
58  *      01131.000,E  Longitude 11 deg 31.000' E
59  *      1            Signal quality: 0 = invalid
60  *                                   1 = GPS fix (SPS)
61  *                                   2 = DGPS fix
62  *                                   3 = PPS fix
63  *                                               4 = Real Time Kinematic
64  *                                               5 = Float RTK
65  *                                   6 = estimated (dead reckoning) (2.3 feature)
66  *                                               7 = Manual input mode
67  *                                               8 = Simulation mode
68  *      08           Number of satellites being tracked
69  *      0.9          Horizontal dilution of position
70  *      545.4,M      Altitude, Meters, above mean sea level
71  *      46.9,M       Height of geoid (mean sea level) above WGS84
72  *                       ellipsoid
73  *      (empty field) time in seconds since last DGPS update
74  *      (empty field) DGPS station ID number
75  *      *47          the checksum data, always begins with *
76  *
77  * If the height of geoid is missing then the altitude should be suspect. Some
78  * non-standard implementations report altitude with respect to the ellipsoid
79  * rather than geoid altitude. Some units do not report negative altitudes at
80  * all. This is the only sentence that reports altitude.
81  * </pre>
82  */
83 typedef struct _nmeaGPGGA {
84         uint32_t present;                       /**< Mask specifying which fields are present, same as in nmeaINFO */
85         nmeaTIME utc;                           /**< UTC of position (just time) */
86         double lat;                                     /**< Latitude in NDEG - [degree][min].[sec/60] */
87         char ns;                                        /**< [N]orth or [S]outh */
88         double lon;                                     /**< Longitude in NDEG - [degree][min].[sec/60] */
89         char ew;                                        /**< [E]ast or [W]est */
90         int sig;                                        /**< GPS quality indicator (0 = Invalid; 1 = Fix; 2 = Differential, 3 = Sensitive) */
91         int satinuse;                           /**< Number of satellites in use (not those in view) */
92         double HDOP;                            /**< Horizontal dilution of precision */
93         double elv;                                     /**< Antenna altitude above/below mean sea level (geoid) */
94         char elv_units;                         /**< [M]eters (Antenna height unit) */
95         double diff;                            /**< Geoidal separation (Diff. between WGS-84 earth ellipsoid and mean sea level. '-' = geoid is below WGS-84 ellipsoid) */
96         char diff_units;                        /**< [M]eters (Units of geoidal separation) */
97         double dgps_age;                        /**< Time in seconds since last DGPS update */
98         int dgps_sid;                           /**< DGPS station ID number */
99 } nmeaGPGGA;
100
101 /**
102  * GSA packet information structure (Satellite status)
103  *
104  * <pre>
105  * GSA - GPS DOP and active satellites.
106  *
107  * This sentence provides details on the nature of the fix. It includes the
108  * numbers of the satellites being used in the current solution and the DOP.
109  *
110  * DOP (dilution of precision) is an indication of the effect of satellite
111  * geometry on the accuracy of the fix. It is a unitless number where smaller
112  * is better. For 3D fixes using 4 satellites a 1.0 would be considered to be
113  * a perfect number, however for overdetermined solutions it is possible to see
114  * numbers below 1.0.
115  *
116  * There are differences in the way the PRN's are presented which can effect the
117  * ability of some programs to display this data. For example, in the example
118  * shown below there are 5 satellites in the solution and the null fields are
119  * scattered indicating that the almanac would show satellites in the null
120  * positions that are not being used as part of this solution. Other receivers
121  * might output all of the satellites used at the beginning of the sentence with
122  * the null field all stacked up at the end. This difference accounts for some
123  * satellite display programs not always being able to display the satellites
124  * being tracked. Some units may show all satellites that have ephemeris data
125  * without regard to their use as part of the solution but this is non-standard.
126  *
127  * $GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39
128  *
129  * Where:
130  *      GSA      Satellite status
131  *      A        Auto selection of 2D or 3D fix (M = manual)
132  *      3        3D fix - values include: 1 = no fix
133  *                                        2 = 2D fix
134  *                                        3 = 3D fix
135  *      04,05... PRNs of satellites used for fix (space for 12)
136  *      2.5      PDOP (dilution of precision)
137  *      1.3      Horizontal dilution of precision (HDOP)
138  *      2.1      Vertical dilution of precision (VDOP)
139  *      *39      the checksum data, always begins with *
140  * </pre>
141  */
142 typedef struct _nmeaGPGSA {
143         uint32_t present;                       /**< Mask specifying which fields are present, same as in nmeaINFO */
144         char fix_mode;                          /**< Mode (M = Manual, forced to operate in 2D or 3D; A = Automatic, 3D/2D) */
145         int fix_type;                           /**< Type, used for navigation (1 = Fix not available; 2 = 2D; 3 = 3D) */
146         int sat_prn[NMEA_MAXSAT];       /**< PRNs of satellites used in position fix (0 for unused fields) */
147         double PDOP;                            /**< Dilution of precision */
148         double HDOP;                            /**< Horizontal dilution of precision */
149         double VDOP;                            /**< Vertical dilution of precision */
150 } nmeaGPGSA;
151
152 /**
153  * GSV packet information structure (Satellites in view)
154  *
155  * <pre>
156  * GSV - Satellites in View
157  *
158  * Shows data about the satellites that the unit might be able to find based on
159  * its viewing mask and almanac data. It also shows current ability to track
160  * this data. Note that one GSV sentence only can provide data for up to 4
161  * satellites and thus there may need to be 3 sentences for the full
162  * information. It is reasonable for the GSV sentence to contain more satellites
163  * than GGA might indicate since GSV may include satellites that are not used as
164  * part of the solution. It is not a requirement that the GSV sentences all
165  * appear in sequence. To avoid overloading the data bandwidth some receivers
166  * may place the various sentences in totally different samples since each
167  * sentence identifies which one it is.
168  *
169  * The field called SNR (Signal to Noise Ratio) in the NMEA standard is often
170  * referred to as signal strength. SNR is an indirect but more useful value than
171  * raw signal strength. It can range from 0 to 99 and has units of dB according
172  * to the NMEA standard, but the various manufacturers send different ranges of
173  * numbers with different starting numbers so the values themselves cannot
174  * necessarily be used to evaluate different units. The range of working values
175  * in a given gps will usually show a difference of about 25 to 35 between the
176  * lowest and highest values, however 0 is a special case and may be shown on
177  * satellites that are in view but not being tracked.
178  *
179  * $GPGSV,2,1,08,01,40,083,46,02,17,308,41,12,07,344,39,14,22,228,45*75
180  *
181  * Where:
182  *      GSV          Satellites in view
183  *      2            Number of sentences for full data
184  *      1            sentence 1 of 2
185  *      08           Number of satellites in view
186  *
187  *      01           Satellite PRN number
188  *      40           Elevation, degrees
189  *      083          Azimuth, degrees
190  *      46           SNR - higher is better
191  *           for up to 4 satellites per sentence
192  *
193  *      *75          the checksum data, always begins with *
194  * </pre>
195  */
196 typedef struct _nmeaGPGSV {
197         uint32_t present;                       /**< Mask specifying which fields are present, same as in nmeaINFO */
198         int pack_count;                         /**< Total number of messages of this type in this cycle */
199         int pack_index;                         /**< Message number */
200         int sat_count;                          /**< Total number of satellites in view */
201         nmeaSATELLITE sat_data[NMEA_SATINPACK];
202 } nmeaGPGSV;
203
204 /**
205  * RMC -packet information structure (Recommended Minimum sentence C)
206  *
207  * <pre>
208  * RMC - Recommended Minimum sentence C
209  *
210  * NMEA has its own version of essential gps pvt (position, velocity,
211  * time) data. It is called RMC, the Recommended Minimum, which will look
212  * similar to:
213  *
214  * $GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W*6A
215  * $GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W,A*6A (v2.3)
216  *
217  * Where:
218  *      RMC          Recommended Minimum sentence C
219  *      123519       Fix taken at 12:35:19 UTC
220  *      A            Status A=active or V=Void.
221  *      4807.038,N   Latitude 48 deg 07.038' N
222  *      01131.000,E  Longitude 11 deg 31.000' E
223  *      022.4        Speed over the ground in knots
224  *      084.4        Track angle in degrees True
225  *      230394       Date - 23rd of March 1994
226  *      003.1,W      Magnetic Variation
227  *      A            Mode A=autonomous, D=differential, E=Estimated,
228  *                        N=not valid, S=Simulator (NMEA v2.3)
229  *      *6A          The checksum data, always begins with *
230  * </pre>
231  */
232 typedef struct _nmeaGPRMC {
233         uint32_t present;                       /**< Mask specifying which fields are present, same as in nmeaINFO */
234         nmeaTIME utc;                           /**< UTC of position */
235         char status;                            /**< Status (A = active or V = void) */
236         double lat;                                     /**< Latitude in NDEG - [degree][min].[sec/60] */
237         char ns;                                        /**< [N]orth or [S]outh */
238         double lon;                                     /**< Longitude in NDEG - [degree][min].[sec/60] */
239         char ew;                                        /**< [E]ast or [W]est */
240         double speed;                           /**< Speed over the ground in knots */
241         double track;                           /**< Track angle in degrees True */
242         double magvar;                          /**< Magnetic variation degrees (Easterly var. subtracts from true course) */
243         char magvar_ew;                         /**< [E]ast or [W]est */
244         char mode;                                      /**< Mode indicator of fix type (A=autonomous, D=differential, E=Estimated, N=not valid, S=Simulator) */
245 } nmeaGPRMC;
246
247 /**
248  * VTG packet information structure (Track made good and ground speed)
249  *
250  * <pre>
251  * VTG - Velocity made good.
252  *
253  * The gps receiver may use the LC prefix instead of GP if it is emulating
254  * Loran output.
255  *
256  * $GPVTG,054.7,T,034.4,M,005.5,N,010.2,K*48
257  *
258  * where:
259  *      VTG          Track made good and ground speed
260  *      054.7,T      True track made good (degrees)
261  *      034.4,M      Magnetic track made good
262  *      005.5,N      Ground speed, knots
263  *      010.2,K      Ground speed, Kilometers per hour
264  *      *48          Checksum
265  * </pre>
266  */
267 typedef struct _nmeaGPVTG {
268         uint32_t present;                       /**< Mask specifying which fields are present, same as in nmeaINFO */
269         double track;                           /**< True track made good (degrees) */
270         char track_t;                           /**< Fixed text 'T' indicates that track made good is relative to true north */
271         double mtrack;                          /**< Magnetic track made good */
272         char mtrack_m;                          /**< Fixed text 'M' */
273         double spn;                                     /**< Ground speed, knots */
274         char spn_n;                                     /**< Fixed text 'N' indicates that speed over ground is in knots */
275         double spk;                                     /**< Ground speed, kilometers per hour */
276         char spk_k;                                     /**< Fixed text 'K' indicates that speed over ground is in kilometers/hour */
277 } nmeaGPVTG;
278
279 void nmea_zero_GPGGA(nmeaGPGGA *pack);
280 void nmea_zero_GPGSA(nmeaGPGSA *pack);
281 void nmea_zero_GPGSV(nmeaGPGSV *pack);
282 void nmea_zero_GPRMC(nmeaGPRMC *pack);
283 void nmea_zero_GPVTG(nmeaGPVTG *pack);
284
285 #ifdef  __cplusplus
286 }
287 #endif /* __cplusplus */
288
289 #endif /* __NMEA_SENTENCE_H__ */