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