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 /* these constants affect the size of the context object. tweak them as desired but know what you are doing */
  36
  37 /** maximum number of sentence parsers supported */
  38 #define NMEAP_MAX_SENTENCES            8
  39 /** length of sentence name. leave this at 5 unless you really know what you are doing */
  40 #define NMEAP_MAX_SENTENCE_NAME_LENGTH 5
  41 /** max length of a complete sentence. the standard says 82 bytes, but its probably better to go at least 128 since
  42  * some units don't adhere to the 82 bytes especially for proprietary sentences */
  43 #define NMEAP_MAX_SENTENCE_LENGTH      255
  44 /** max tokens in one sentence. 24 is enough for any standard sentence */
  45 #define NMEAP_MAX_TOKENS               24
  46
  47 /* predefined message ID's */
  48
  49 /* GGA MESSAGE ID */
  50 #define NMEAP_GPGGA 1
  51 /* RMC MESSAGE ID */
  52 #define NMEAP_GPRMC 2
  53
  54 /** user defined parsers should make ID numbers using NMEAP_USER as the base value, plus some increment */
  55 #define NMEAP_USER  100
  56
  57 /* forward references */
  58 struct nmeap_context;
  59 struct nmeap_sentence;
  60
  61 /*
  62 ============================================
  63 CALLOUTS
  64 ============================================
  65 */
  66
  67 /**
  68  * sentence callout function type
  69  * a callout is fired for each registered sentence type
  70  * the callout gets the object context and a pointer to sentence specific data.
  71  * the callout must cast the 'sentence_data' to the appropriate type for that callout
  72  * @param context                       nmea object context
  73  * @param sentence_data         sentence specific data
  74 */
  75 typedef void (*nmeap_callout_t)(struct nmeap_context *context,void *sentence_data,void *user_data);
  76
  77 /**
  78  * sentence parser function type
  79  * stored in the object context and called internally when the sentence name matches
  80  * the specified value
  81  * the callout gets the object context and a pointer to sentence specific data.
  82  * the callout must cast the 'sentence_data' to the appropriate type for that callout
  83  * @param context                       nmea object context
  84  * @param sentence_data         sentence specific data
  85  * @return id of sentence  (each sentence parser knows its own ID)
  86 */
  87 typedef int (*nmeap_sentence_parser_t)(struct nmeap_context *context,struct nmeap_sentence *sentence);
  88
  89
  90 /* ==== opaque types === */
  91 #include "nmeap_def.h"
  92
  93
  94 /*
  95 ============================================
  96 STANDARD SENTENCE DATA STRUCTURES
  97 ============================================
  98 */
  99
 100 /** extracted data from a GGA message */
 101 struct nmeap_gga {
 102         double        latitude;
 103         double        longitude;
 104         double        altitude;
 105         unsigned long time;
 106         int           satellites;
 107         int           quality;
 108         double        hdop;
 109         double        geoid;
 110 };
 111 typedef struct nmeap_gga nmeap_gga_t;
 112
 113 /** extracted data from an RMC message */
 114 struct nmeap_rmc {
 115         unsigned long time;
 116         char          warn;
 117         double        latitude;
 118         double        longitude;
 119         double        speed;
 120         double        course;
 121         unsigned long date;
 122         double        magvar;
 123 };
 124
 125 typedef struct nmeap_rmc nmeap_rmc_t;
 126
 127 /*
 128 ============================================
 129 METHODS
 130 ============================================
 131 */
 132
 133 /**
 134  * initialize an NMEA parser. call this function to initialize a user allocated context object
 135  * @param context               nmea object context. allocated by user statically or dynamically.
 136  * @param user_data     pointer to user defined data
 137  * @return 0 if ok, -1 if initialization failed
 138  */
 139 int nmeap_init(nmeap_context_t *context,void *user_data);
 140
 141 /**
 142  * register an NMEA sentence parser
 143  * @param context                  nmea object context
 144  * @param sentence_name    string matching the sentence name for this parser. e.g. "GPGGA". not including the '$'
 145  * @param sentence_parser  parser function for this sentence
 146  * @param sentence_callout callout triggered when this sentence is received and parsed.
 147  *                         if null, no callout is triggered for this sentence
 148  * @param sentence_data    user allocated sentence specific data defined by the application. the parser uses
 149                            this data item to store the extracted data. This data object needs to persist over the life
 150                                                    of the parser, so be careful if allocated on the stack.
 151  * @return 0 if registered ok, -1 if registration failed
 152  */
 153 int nmeap_addParser(nmeap_context_t         *context,
 154                                          const char             *sentence_name,
 155                                          nmeap_sentence_parser_t sentence_parser,
 156                                          nmeap_callout_t         sentence_callout,
 157                                          void                   *sentence_data
 158                                          );
 159
 160 /**
 161  * parse a buffer of nmea data.
 162  * @param context                  nmea object context
 163  * @param buffer          buffer of input characters
 164  * @param length          [in,out] pointer to length of buffer. on return, contains number of characters not used for
 165  *                        the current sentence
 166  * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
 167  */
 168 int nmeap_parseBuffer(nmeap_context_t *context,const char *buffer,int *length);
 169
 170 /**
 171  * parse one character of nmea data.
 172  * @param context                  nmea object context
 173  * @param ch              input character
 174  * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
 175  */
 176 int nmeap_parse(nmeap_context_t *context,char ch);
 177
 178
 179 /**
 180  * built-in parser for GGA sentences.
 181  * @param context                  nmea object context
 182  * @param sentence         sentence object for this parser
 183   */
 184 int nmeap_gpgga(nmeap_context_t *context,nmeap_sentence_t *sentence);
 185
 186 /**
 187  * built-in parser for RMC sentences.
 188  * @param context                  nmea object context
 189  * @param sentence         sentence object for this parser
 190  */
 191 int nmeap_gprmc(nmeap_context_t *context,nmeap_sentence_t *sentence);
 192
 193 /**
 194  * extract latitude from 2 tokens in ddmm.mmmm,h format.
 195  * @param plat pointer to token with numerical latitude
 196  * @param phem pointer to token with hemisphere
 197  * @return latitude in degrees and fractional degrees
 198  */
 199 double nmeap_latitude(const char *plat,const char *phem);
 200
 201
 202 /**
 203  * extract longitude from 2 tokens in ddmm.mmmm,h format.
 204  * @param plat pointer to token with numerical longitude
 205  * @param phem pointer to token with hemisphere
 206  * @return longitude in degrees and fractional degrees
 207  */
 208 double nmeap_longitude(const char *plat,const char *phem);
 209
 210 #ifdef __cplusplus
 211 } // extern C
 212 #endif
 213
 214
 215 #endif
 216