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 #include "cfg/cfg_nmea.h"
  30
  31 /*
  32 ============================================
  33 COMPILE TIME CONFIGURATION CONSTANTS
  34 ============================================
  35 */
  36
  37 #define NDEBUG
  38
  39 /* these constants affect the size of the context object. tweak them as desired but know what you are doing */
  40
  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
  50
  51 /* predefined message ID's */
  52
  53 /* GGA MESSAGE ID */
  54 #define NMEAP_GPGGA 1
  55 /* RMC MESSAGE ID */
  56 #define NMEAP_GPRMC 2
  57
  58 /** user defined parsers should make ID numbers using NMEAP_USER as the base value, plus some increment */
  59 #define NMEAP_USER  100
  60
  61 /* forward references */
  62 struct nmeap_context;
  63 struct nmeap_sentence;
  64
  65 /*
  66 ============================================
  67 CALLOUTS
  68 ============================================
  69 */
  70
  71 /**
  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
  78 */
  79 typedef void (*nmeap_callout_t)(struct nmeap_context *context,void *sentence_data,void *user_data);
  80
  81 /**
  82  * sentence parser function type
  83  * stored in the object context and called internally when the sentence name matches
  84  * the specified value
  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)
  90 */
  91 typedef int (*nmeap_sentence_parser_t)(struct nmeap_context *context,struct nmeap_sentence *sentence);
  92
  93
  94 /* ==== opaque types === */
  95 #include "nmeap_def.h"
  96
  97
  98 /*
  99 ============================================
 100 STANDARD SENTENCE DATA STRUCTURES
 101 ============================================
 102 */
 103
 104 /** extracted data from a GGA message */
 105 struct nmeap_gga {
 106         double        latitude;
 107         double        longitude;
 108         double        altitude;
 109         unsigned long time;
 110         int           satellites;
 111         int           quality;
 112         double        hdop;
 113         double        geoid;
 114 };
 115 typedef struct nmeap_gga nmeap_gga_t;
 116
 117 /** extracted data from an RMC message */
 118 struct nmeap_rmc {
 119         unsigned long time;
 120         char          warn;
 121         double        latitude;
 122         double        longitude;
 123         double        speed;
 124         double        course;
 125         unsigned long date;
 126         double        magvar;
 127 };
 128
 129 typedef struct nmeap_rmc nmeap_rmc_t;
 130
 131 /*
 132 ============================================
 133 METHODS
 134 ============================================
 135 */
 136
 137 /**
 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
 142  */
 143 int nmeap_init(nmeap_context_t *context,void *user_data);
 144
 145 /**
 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
 156  */
 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,
 161                                          void                   *sentence_data
 162                                          );
 163
 164 /**
 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
 171  */
 172 int nmeap_parseBuffer(nmeap_context_t *context,const char *buffer,int *length);
 173
 174 /**
 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
 179  */
 180 int nmeap_parse(nmeap_context_t *context,char ch);
 181
 182
 183 /**
 184  * built-in parser for GGA sentences.
 185  * @param context                  nmea object context
 186  * @param sentence         sentence object for this parser
 187   */
 188 int nmeap_gpgga(nmeap_context_t *context,nmeap_sentence_t *sentence);
 189
 190 /**
 191  * built-in parser for RMC sentences.
 192  * @param context                  nmea object context
 193  * @param sentence         sentence object for this parser
 194  */
 195 int nmeap_gprmc(nmeap_context_t *context,nmeap_sentence_t *sentence);
 196
 197 /**
 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
 202  */
 203 double nmeap_latitude(const char *plat,const char *phem);
 204
 205
 206 /**
 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
 211  */
 212 double nmeap_longitude(const char *plat,const char *phem);
 213
 214
 215 /**
 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
 220  */
 221 double nmeap_altitude(const char *palt,const char *punits);
 222
 223 #ifdef __cplusplus
 224 } // extern C
 225 #endif
 226
 227
 228 #endif
 229