bertos/net/nmeap/inc/nmeap.h

   1 /*
   2 Copyright (c) 2005, David M Howard (daveh at dmh2000.com)
   3 All rights reserved.
   4
   5 This product is licensed for use and distribution under the BSD Open Source License.
   6 see the file COPYING for more details.
   7
   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.
  19
  20 */
  21
  22 #ifndef __NMEAP_H__
  23 #define __NMEAP_H__
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /*
  30 ============================================
  31 COMPILE TIME CONFIGURATION CONSTANTS
  32 ============================================
  33 */
  34
  35 #define NDEBUG
  36
  37 /* these constants affect the size of the context object. tweak them as desired but know what you are doing */
  38
  39 /** maximum number of sentence parsers supported */
  40 #define NMEAP_MAX_SENTENCES            8
  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      255
  46 /** max tokens in one sentence. 24 is enough for any standard sentence */
  47 #define NMEAP_MAX_TOKENS               24
  48
  49 /* predefined message ID's */
  50
  51 /* GGA MESSAGE ID */
  52 #define NMEAP_GPGGA 1
  53 /* RMC MESSAGE ID */
  54 #define NMEAP_GPRMC 2
  55
  56 /** user defined parsers should make ID numbers using NMEAP_USER as the base value, plus some increment */
  57 #define NMEAP_USER  100
  58
  59 /* forward references */
  60 struct nmeap_context;
  61 struct nmeap_sentence;
  62
  63 /*
  64 ============================================
  65 CALLOUTS
  66 ============================================
  67 */
  68
  69 /**
  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
  76 */
  77 typedef void (*nmeap_callout_t)(struct nmeap_context *context,void *sentence_data,void *user_data);
  78
  79 /**
  80  * sentence parser function type
  81  * stored in the object context and called internally when the sentence name matches
  82  * the specified value
  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)
  88 */
  89 typedef int (*nmeap_sentence_parser_t)(struct nmeap_context *context,struct nmeap_sentence *sentence);
  90
  91
  92 /* ==== opaque types === */
  93 #include "nmeap_def.h"
  94
  95
  96 /*
  97 ============================================
  98 STANDARD SENTENCE DATA STRUCTURES
  99 ============================================
 100 */
 101
 102 /** extracted data from a GGA message */
 103 struct nmeap_gga {
 104         double        latitude;
 105         double        longitude;
 106         double        altitude;
 107         unsigned long time;
 108         int           satellites;
 109         int           quality;
 110         double        hdop;
 111         double        geoid;
 112 };
 113 typedef struct nmeap_gga nmeap_gga_t;
 114
 115 /** extracted data from an RMC message */
 116 struct nmeap_rmc {
 117         unsigned long time;
 118         char          warn;
 119         double        latitude;
 120         double        longitude;
 121         double        speed;
 122         double        course;
 123         unsigned long date;
 124         double        magvar;
 125 };
 126
 127 typedef struct nmeap_rmc nmeap_rmc_t;
 128
 129 /*
 130 ============================================
 131 METHODS
 132 ============================================
 133 */
 134
 135 /**
 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
 140  */
 141 int nmeap_init(nmeap_context_t *context,void *user_data);
 142
 143 /**
 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
 154  */
 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,
 159                                          void                   *sentence_data
 160                                          );
 161
 162 /**
 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
 169  */
 170 int nmeap_parseBuffer(nmeap_context_t *context,const char *buffer,int *length);
 171
 172 /**
 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
 177  */
 178 int nmeap_parse(nmeap_context_t *context,char ch);
 179
 180
 181 /**
 182  * built-in parser for GGA sentences.
 183  * @param context                  nmea object context
 184  * @param sentence         sentence object for this parser
 185   */
 186 int nmeap_gpgga(nmeap_context_t *context,nmeap_sentence_t *sentence);
 187
 188 /**
 189  * built-in parser for RMC sentences.
 190  * @param context                  nmea object context
 191  * @param sentence         sentence object for this parser
 192  */
 193 int nmeap_gprmc(nmeap_context_t *context,nmeap_sentence_t *sentence);
 194
 195 /**
 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
 200  */
 201 double nmeap_latitude(const char *plat,const char *phem);
 202
 203
 204 /**
 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
 209  */
 210 double nmeap_longitude(const char *plat,const char *phem);
 211
 212
 213 /**
 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
 218  */
 219 double nmeap_altitude(const char *palt,const char *punits);
 220
 221 #ifdef __cplusplus
 222 } // extern C
 223 #endif
 224
 225
 226 #endif
 227