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 ============================================
39 /* these constants affect the size of the context object. tweak them as desired but know what you are doing */
41 /** maximum number of sentence parsers supported */
42 #define NMEAP_MAX_SENTENCES CONFIG_NMEAP_MAX_SENTENCES
43 /** length of sentence name. leave this at 5 unless you really know what you are doing */
44 #define NMEAP_MAX_SENTENCE_NAME_LENGTH 5
45 /** max length of a complete sentence. the standard says 82 bytes, but its probably better to go at least 128 since
46 * some units don't adhere to the 82 bytes especially for proprietary sentences */
47 #define NMEAP_MAX_SENTENCE_LENGTH CONFIG_NMEAP_MAX_SENTENCE_LENGTH
48 /** max tokens in one sentence. 24 is enough for any standard sentence */
49 #define NMEAP_MAX_TOKENS CONFIG_NMEAP_MAX_TOKENS
51 /* predefined message ID's */
58 /** user defined parsers should make ID numbers using NMEAP_USER as the base value, plus some increment */
59 #define NMEAP_USER 100
61 /* forward references */
63 struct nmeap_sentence;
66 ============================================
68 ============================================
72 * sentence callout function type
73 * a callout is fired for each registered sentence type
74 * the callout gets the object context and a pointer to sentence specific data.
75 * the callout must cast the 'sentence_data' to the appropriate type for that callout
76 * @param context nmea object context
77 * @param sentence_data sentence specific data
79 typedef void (*nmeap_callout_t)(struct nmeap_context *context,void *sentence_data,void *user_data);
82 * sentence parser function type
83 * stored in the object context and called internally when the sentence name matches
85 * the callout gets the object context and a pointer to sentence specific data.
86 * the callout must cast the 'sentence_data' to the appropriate type for that callout
87 * @param context nmea object context
88 * @param sentence_data sentence specific data
89 * @return id of sentence (each sentence parser knows its own ID)
91 typedef int (*nmeap_sentence_parser_t)(struct nmeap_context *context,struct nmeap_sentence *sentence);
94 /* ==== opaque types === */
95 #include "nmeap_def.h"
99 ============================================
100 STANDARD SENTENCE DATA STRUCTURES
101 ============================================
104 /** extracted data from a GGA message */
115 typedef struct nmeap_gga nmeap_gga_t;
117 /** extracted data from an RMC message */
129 typedef struct nmeap_rmc nmeap_rmc_t;
132 ============================================
134 ============================================
138 * initialize an NMEA parser. call this function to initialize a user allocated context object
139 * @param context nmea object context. allocated by user statically or dynamically.
140 * @param user_data pointer to user defined data
141 * @return 0 if ok, -1 if initialization failed
143 int nmeap_init(nmeap_context_t *context,void *user_data);
146 * register an NMEA sentence parser
147 * @param context nmea object context
148 * @param sentence_name string matching the sentence name for this parser. e.g. "GPGGA". not including the '$'
149 * @param sentence_parser parser function for this sentence
150 * @param sentence_callout callout triggered when this sentence is received and parsed.
151 * if null, no callout is triggered for this sentence
152 * @param sentence_data user allocated sentence specific data defined by the application. the parser uses
153 this data item to store the extracted data. This data object needs to persist over the life
154 of the parser, so be careful if allocated on the stack.
155 * @return 0 if registered ok, -1 if registration failed
157 int nmeap_addParser(nmeap_context_t *context,
158 const char *sentence_name,
159 nmeap_sentence_parser_t sentence_parser,
160 nmeap_callout_t sentence_callout,
165 * parse a buffer of nmea data.
166 * @param context nmea object context
167 * @param buffer buffer of input characters
168 * @param length [in,out] pointer to length of buffer. on return, contains number of characters not used for
169 * the current sentence
170 * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
172 int nmeap_parseBuffer(nmeap_context_t *context,const char *buffer,int *length);
175 * parse one character of nmea data.
176 * @param context nmea object context
177 * @param ch input character
178 * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
180 int nmeap_parse(nmeap_context_t *context,char ch);
184 * built-in parser for GGA sentences.
185 * @param context nmea object context
186 * @param sentence sentence object for this parser
188 int nmeap_gpgga(nmeap_context_t *context,nmeap_sentence_t *sentence);
191 * built-in parser for RMC sentences.
192 * @param context nmea object context
193 * @param sentence sentence object for this parser
195 int nmeap_gprmc(nmeap_context_t *context,nmeap_sentence_t *sentence);
198 * extract latitude from 2 tokens in ddmm.mmmm,h format.
199 * @param plat pointer to token with numerical latitude
200 * @param phem pointer to token with hemisphere
201 * @return latitude in degrees and fractional degrees
203 double nmeap_latitude(const char *plat,const char *phem);
207 * extract longitude from 2 tokens in ddmm.mmmm,h format.
208 * @param plat pointer to token with numerical longitude
209 * @param phem pointer to token with hemisphere
210 * @return longitude in degrees and fractional degrees
212 double nmeap_longitude(const char *plat,const char *phem);
216 * extract altitude from 2 tokens in xx.x format.
217 * @param palt pointer to token with numerical altitude
218 * @param punits pointer to token with measure unint
219 * @return altitude in meter or feet
221 double nmeap_altitude(const char *palt,const char *punits);