2 Copyright (c) 2005, David M Howard (daveh at dmh2000.com)
5 This product is licensed for use and distribution under the BSD Open Source License.
6 see the file COPYING for more details.
8 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
9 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
10 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
11 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
12 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
13 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
14 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
15 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
16 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
17 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
18 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 #include "cfg/cfg_nmea.h"
32 ============================================
33 COMPILE TIME CONFIGURATION CONSTANTS
34 ============================================
37 /* these constants affect the size of the context object. tweak them as desired but know what you are doing */
39 /** maximum number of sentence parsers supported */
40 #define NMEAP_MAX_SENTENCES CONFIG_NMEAP_MAX_SENTENCES
41 /** length of sentence name. leave this at 5 unless you really know what you are doing */
42 #define NMEAP_MAX_SENTENCE_NAME_LENGTH 5
43 /** max length of a complete sentence. the standard says 82 bytes, but its probably better to go at least 128 since
44 * some units don't adhere to the 82 bytes especially for proprietary sentences */
45 #define NMEAP_MAX_SENTENCE_LENGTH CONFIG_NMEAP_MAX_SENTENCE_LENGTH
46 /** max tokens in one sentence. 24 is enough for any standard sentence */
47 #define NMEAP_MAX_TOKENS CONFIG_NMEAP_MAX_TOKENS
49 /* predefined message ID's */
56 /** user defined parsers should make ID numbers using NMEAP_USER as the base value, plus some increment */
57 #define NMEAP_USER 100
59 /* forward references */
61 struct nmeap_sentence;
64 ============================================
66 ============================================
70 * sentence callout function type
71 * a callout is fired for each registered sentence type
72 * the callout gets the object context and a pointer to sentence specific data.
73 * the callout must cast the 'sentence_data' to the appropriate type for that callout
74 * @param context nmea object context
75 * @param sentence_data sentence specific data
77 typedef void (*nmeap_callout_t)(struct nmeap_context *context,void *sentence_data,void *user_data);
80 * sentence parser function type
81 * stored in the object context and called internally when the sentence name matches
83 * the callout gets the object context and a pointer to sentence specific data.
84 * the callout must cast the 'sentence_data' to the appropriate type for that callout
85 * @param context nmea object context
86 * @param sentence_data sentence specific data
87 * @return id of sentence (each sentence parser knows its own ID)
89 typedef int (*nmeap_sentence_parser_t)(struct nmeap_context *context,struct nmeap_sentence *sentence);
92 /* ==== opaque types === */
93 #include "nmeap_def.h"
97 ============================================
98 STANDARD SENTENCE DATA STRUCTURES
99 ============================================
102 /** extracted data from a GGA message */
113 typedef struct nmeap_gga nmeap_gga_t;
115 /** extracted data from an RMC message */
127 typedef struct nmeap_rmc nmeap_rmc_t;
130 ============================================
132 ============================================
136 * initialize an NMEA parser. call this function to initialize a user allocated context object
137 * @param context nmea object context. allocated by user statically or dynamically.
138 * @param user_data pointer to user defined data
139 * @return 0 if ok, -1 if initialization failed
141 int nmeap_init(nmeap_context_t *context,void *user_data);
144 * register an NMEA sentence parser
145 * @param context nmea object context
146 * @param sentence_name string matching the sentence name for this parser. e.g. "GPGGA". not including the '$'
147 * @param sentence_parser parser function for this sentence
148 * @param sentence_callout callout triggered when this sentence is received and parsed.
149 * if null, no callout is triggered for this sentence
150 * @param sentence_data user allocated sentence specific data defined by the application. the parser uses
151 this data item to store the extracted data. This data object needs to persist over the life
152 of the parser, so be careful if allocated on the stack.
153 * @return 0 if registered ok, -1 if registration failed
155 int nmeap_addParser(nmeap_context_t *context,
156 const char *sentence_name,
157 nmeap_sentence_parser_t sentence_parser,
158 nmeap_callout_t sentence_callout,
163 * parse a buffer of nmea data.
164 * @param context nmea object context
165 * @param buffer buffer of input characters
166 * @param length [in,out] pointer to length of buffer. on return, contains number of characters not used for
167 * the current sentence
168 * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
170 int nmeap_parseBuffer(nmeap_context_t *context,const char *buffer,int *length);
173 * parse one character of nmea data.
174 * @param context nmea object context
175 * @param ch input character
176 * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
178 int nmeap_parse(nmeap_context_t *context,char ch);
182 * built-in parser for GGA sentences.
183 * @param context nmea object context
184 * @param sentence sentence object for this parser
186 int nmeap_gpgga(nmeap_context_t *context,nmeap_sentence_t *sentence);
189 * built-in parser for RMC sentences.
190 * @param context nmea object context
191 * @param sentence sentence object for this parser
193 int nmeap_gprmc(nmeap_context_t *context,nmeap_sentence_t *sentence);
196 * extract latitude from 2 tokens in ddmm.mmmm,h format.
197 * @param plat pointer to token with numerical latitude
198 * @param phem pointer to token with hemisphere
199 * @return latitude in degrees and fractional degrees
201 double nmeap_latitude(const char *plat,const char *phem);
205 * extract longitude from 2 tokens in ddmm.mmmm,h format.
206 * @param plat pointer to token with numerical longitude
207 * @param phem pointer to token with hemisphere
208 * @return longitude in degrees and fractional degrees
210 double nmeap_longitude(const char *plat,const char *phem);
214 * extract altitude from 2 tokens in xx.x format.
215 * @param palt pointer to token with numerical altitude
216 * @param punits pointer to token with measure unint
217 * @return altitude in meter or feet
219 double nmeap_altitude(const char *palt,const char *punits);