TinyGPSPlus.h

00001 /*
00002 TinyGPS++ - a small GPS library for Arduino providing universal NMEA parsing
00003 Based on work by and "distanceBetween" and "courseTo" courtesy of Maarten Lamers.
00004 Suggestion to add satellites, courseTo(), and cardinal() by Matt Monson.
00005 Location precision improvements suggested by Wayne Holder.
00006 Copyright (C) 2008-2013 Mikal Hart
00007 All rights reserved.
00008 
00009 This library is free software; you can redistribute it and/or
00010 modify it under the terms of the GNU Lesser General Public
00011 License as published by the Free Software Foundation; either
00012 version 2.1 of the License, or (at your option) any later version.
00013 
00014 This library is distributed in the hope that it will be useful,
00015 but WITHOUT ANY WARRANTY; without even the implied warranty of
00016 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017 Lesser General Public License for more details.
00018 
00019 You should have received a copy of the GNU Lesser General Public
00020 License along with this library; if not, write to the Free Software
00021 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00022 */
00023 
00024 #ifndef __TinyGPSPlus_h
00025 #define __TinyGPSPlus_h
00026 
00027 #include <inttypes.h>
00028 unsigned long millis(void);
00029 
00030 #include <limits.h>
00031 
00032 #define _GPS_VERSION "1.0.2" // software version of this library
00033 #define _GPS_MPH_PER_KNOT 1.15077945
00034 #define _GPS_MPS_PER_KNOT 0.51444444
00035 #define _GPS_KMPH_PER_KNOT 1.852
00036 #define _GPS_MILES_PER_METER 0.00062137112
00037 #define _GPS_KM_PER_METER 0.001
00038 #define _GPS_FEET_PER_METER 3.2808399
00039 #define _GPS_MAX_FIELD_SIZE 15
00040 
00041 struct RawDegrees
00042 {
00043    uint16_t deg;
00044    uint32_t billionths;
00045    bool negative;
00046 public:
00047    RawDegrees() : deg(0), billionths(0), negative(false)
00048    {}
00049 };
00050 
00051 struct TinyGPSLocation
00052 {
00053    friend class TinyGPSPlus;
00054 public:
00055    bool isValid() const    { return valid; }
00056    bool isUpdated() const  { return updated; }
00057    uint32_t age() const    { return valid ? millis() - lastCommitTime : (uint32_t)ULONG_MAX; }
00058    const RawDegrees &rawLat()     { updated = false; return rawLatData; }
00059    const RawDegrees &rawLng()     { updated = false; return rawLngData; }
00060    double lat();
00061    double lng();
00062 
00063    TinyGPSLocation() : valid(false), updated(false)
00064    {}
00065 
00066 private:
00067    bool valid, updated;
00068    RawDegrees rawLatData, rawLngData, rawNewLatData, rawNewLngData;
00069    uint32_t lastCommitTime;
00070    void commit();
00071    void setLatitude(const char *term);
00072    void setLongitude(const char *term);
00073 };
00074 
00075 struct TinyGPSDate
00076 {
00077    friend class TinyGPSPlus;
00078 public:
00079    bool isValid() const       { return valid; }
00080    bool isUpdated() const     { return updated; }
00081    uint32_t age() const       { return valid ? millis() - lastCommitTime : (uint32_t)ULONG_MAX; }
00082 
00083    uint32_t value()           { updated = false; return date; }
00084    uint16_t year();
00085    uint8_t month();
00086    uint8_t day();
00087 
00088    TinyGPSDate() : valid(false), updated(false), date(0)
00089    {}
00090 
00091 private:
00092    bool valid, updated;
00093    uint32_t date, newDate;
00094    uint32_t lastCommitTime;
00095    void commit();
00096    void setDate(const char *term);
00097 };
00098 
00099 struct TinyGPSTime
00100 {
00101    friend class TinyGPSPlus;
00102 public:
00103    bool isValid() const       { return valid; }
00104    bool isUpdated() const     { return updated; }
00105    uint32_t age() const       { return valid ? millis() - lastCommitTime : (uint32_t)ULONG_MAX; }
00106 
00107    uint32_t value()           { updated = false; return time; }
00108    uint8_t hour();
00109    uint8_t minute();
00110    uint8_t second();
00111    uint8_t centisecond();
00112 
00113    TinyGPSTime() : valid(false), updated(false), time(0)
00114    {}
00115 
00116 private:
00117    bool valid, updated;
00118    uint32_t time, newTime;
00119    uint32_t lastCommitTime;
00120    void commit();
00121    void setTime(const char *term);
00122 };
00123 
00124 struct TinyGPSDecimal
00125 {
00126    friend class TinyGPSPlus;
00127 public:
00128    bool isValid() const    { return valid; }
00129    bool isUpdated() const  { return updated; }
00130    uint32_t age() const    { return valid ? millis() - lastCommitTime : (uint32_t)ULONG_MAX; }
00131    int32_t value()         { updated = false; return val; }
00132 
00133    TinyGPSDecimal() : valid(false), updated(false), val(0)
00134    {}
00135 
00136 private:
00137    bool valid, updated;
00138    uint32_t lastCommitTime;
00139    int32_t val, newval;
00140    void commit();
00141    void set(const char *term);
00142 };
00143 
00144 struct TinyGPSInteger
00145 {
00146    friend class TinyGPSPlus;
00147 public:
00148    bool isValid() const    { return valid; }
00149    bool isUpdated() const  { return updated; }
00150    uint32_t age() const    { return valid ? millis() - lastCommitTime : (uint32_t)ULONG_MAX; }
00151    uint32_t value()        { updated = false; return val; }
00152 
00153    TinyGPSInteger() : valid(false), updated(false), val(0)
00154    {}
00155 
00156 private:
00157    bool valid, updated;
00158    uint32_t lastCommitTime;
00159    uint32_t val, newval;
00160    void commit();
00161    void set(const char *term);
00162 };
00163 
00164 struct TinyGPSSpeed : TinyGPSDecimal
00165 {
00166    double knots()    { return value() / 100.0; }
00167    double mph()      { return _GPS_MPH_PER_KNOT * value() / 100.0; }
00168    double mps()      { return _GPS_MPS_PER_KNOT * value() / 100.0; }
00169    double kmph()     { return _GPS_KMPH_PER_KNOT * value() / 100.0; }
00170 };
00171 
00172 struct TinyGPSCourse : public TinyGPSDecimal
00173 {
00174    double deg()      { return value() / 100.0; }
00175 };
00176 
00177 struct TinyGPSAltitude : TinyGPSDecimal
00178 {
00179    double meters()       { return value() / 100.0; }
00180    double miles()        { return _GPS_MILES_PER_METER * value() / 100.0; }
00181    double kilometers()   { return _GPS_KM_PER_METER * value() / 100.0; }
00182    double feet()         { return _GPS_FEET_PER_METER * value() / 100.0; }
00183 };
00184 
00185 struct TinyGPSHDOP : TinyGPSDecimal
00186 {
00187    double hdop() { return value() / 100.0; }
00188 };
00189 
00190 class TinyGPSPlus;
00191 class TinyGPSCustom
00192 {
00193 public:
00194    TinyGPSCustom() {};
00195    TinyGPSCustom(TinyGPSPlus &gps, const char *sentenceName, int termNumber);
00196    void begin(TinyGPSPlus &gps, const char *_sentenceName, int _termNumber);
00197 
00198    bool isUpdated() const  { return updated; }
00199    bool isValid() const    { return valid; }
00200    uint32_t age() const    { return valid ? millis() - lastCommitTime : (uint32_t)ULONG_MAX; }
00201    const char *value()     { updated = false; return buffer; }
00202 
00203 private:
00204    void commit();
00205    void set(const char *term);
00206 
00207    char stagingBuffer[_GPS_MAX_FIELD_SIZE + 1];
00208    char buffer[_GPS_MAX_FIELD_SIZE + 1];
00209    unsigned long lastCommitTime;
00210    bool valid, updated;
00211    const char *sentenceName;
00212    int termNumber;
00213    friend class TinyGPSPlus;
00214    TinyGPSCustom *next;
00215 };
00216 
00217 class TinyGPSPlus
00218 {
00219 public:
00220   TinyGPSPlus();
00221   bool encode(char c); // process one character received from GPS
00222   TinyGPSPlus &operator << (char c) {encode(c); return *this;}
00223 
00224   TinyGPSLocation location;
00225   TinyGPSDate date;
00226   TinyGPSTime time;
00227   TinyGPSSpeed speed;
00228   TinyGPSCourse course;
00229   TinyGPSAltitude altitude;
00230   TinyGPSInteger satellites;
00231   TinyGPSHDOP hdop;
00232 
00233   static const char *libraryVersion() { return _GPS_VERSION; }
00234 
00235   static double distanceBetween(double lat1, double long1, double lat2, double long2);
00236   static double courseTo(double lat1, double long1, double lat2, double long2);
00237   static const char *cardinal(double course);
00238 
00239   static int32_t parseDecimal(const char *term);
00240   static void parseDegrees(const char *term, RawDegrees &deg);
00241 
00242   uint32_t charsProcessed()   const { return encodedCharCount; }
00243   uint32_t sentencesWithFix() const { return sentencesWithFixCount; }
00244   uint32_t failedChecksum()   const { return failedChecksumCount; }
00245   uint32_t passedChecksum()   const { return passedChecksumCount; }
00246 
00247 private:
00248   enum {GPS_SENTENCE_GPGGA, GPS_SENTENCE_GPRMC, GPS_SENTENCE_OTHER};
00249 
00250   // parsing state variables
00251   uint8_t parity;
00252   bool isChecksumTerm;
00253   char term[_GPS_MAX_FIELD_SIZE];
00254   uint8_t curSentenceType;
00255   uint8_t curTermNumber;
00256   uint8_t curTermOffset;
00257   bool sentenceHasFix;
00258 
00259   // custom element support
00260   friend class TinyGPSCustom;
00261   TinyGPSCustom *customElts;
00262   TinyGPSCustom *customCandidates;
00263   void insertCustom(TinyGPSCustom *pElt, const char *sentenceName, int index);
00264 
00265   // statistics
00266   uint32_t encodedCharCount;
00267   uint32_t sentencesWithFixCount;
00268   uint32_t failedChecksumCount;
00269   uint32_t passedChecksumCount;
00270 
00271   // internal utilities
00272   int fromHex(char a);
00273   bool endOfTermHandler();
00274 };
00275 
00276 #endif // def(__TinyGPSPlus_h)