TinyGPS.h

00001 /*
00002   TinyGPS - a small GPS library for Arduino providing basic NMEA parsing
00003   Copyright (C) 2008-9 Mikal Hart
00004   All rights reserved.
00005 
00006   This library is free software; you can redistribute it and/or
00007   modify it under the terms of the GNU Lesser General Public
00008   License as published by the Free Software Foundation; either
00009   version 2.1 of the License, or (at your option) any later version.
00010 
00011   This library is distributed in the hope that it will be useful,
00012   but WITHOUT ANY WARRANTY; without even the implied warranty of
00013   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014   Lesser General Public License for more details.
00015 
00016   You should have received a copy of the GNU Lesser General Public
00017   License along with this library; if not, write to the Free Software
00018   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00019   
00020   Ported to mbed by Michael Shimniok
00021 */
00022 
00023 #include "mbed.h"
00024 #include "types.h"
00025 
00026 #ifndef TinyGPS_h
00027 #define TinyGPS_h
00028 
00029 #define _GPS_VERSION 9 // software version of this library
00030 #define _GPS_MPH_PER_KNOT 1.15077945
00031 #define _GPS_MPS_PER_KNOT 0.51444444
00032 #define _GPS_KMPH_PER_KNOT 1.852
00033 #define _GPS_MILES_PER_METER 0.00062137112
00034 #define _GPS_KM_PER_METER 0.001
00035 //#define _GPS_NO_STATS
00036 
00037 class TinyGPS
00038 {
00039   public:
00040   
00041     /** Create a new GPS parsing object for parsing NMEA sentences
00042      */
00043     TinyGPS();
00044     
00045     /** Parse a single character received from GPS
00046      *
00047      * @param c is the character received from the GPS
00048      * @returns true if processing ok
00049      */
00050     bool encode(char c);
00051     
00052     /** Shorthand operator for encode()
00053      */
00054     TinyGPS &operator << (char c) {encode(c); return *this;}
00055     
00056     /** Return lat/long in hundred thousandths of a degree and age of fix in milliseconds
00057      * @returns latitude is the latitude of the most recent fix that was parsed
00058      * @returns longitude is the longitude of the most recent fix that was parsed
00059      * @returns fix_age is the age of the fix (if available from the NMEA sentences being parsed)
00060      */
00061     inline void get_position(long *latitude, long *longitude, unsigned long *fix_age = 0)
00062     {
00063       if (latitude) *latitude = _latitude;
00064       if (longitude) *longitude = _longitude;
00065       if (fix_age) *fix_age = _last_position_fix == GPS_INVALID_FIX_TIME ? 
00066         GPS_INVALID_AGE : millis() - _last_position_fix;
00067     }
00068 
00069     /** Return the date and time from the parsed NMEA sentences
00070      *
00071      * @returns date as an integer value
00072      * @returns time as an integer value
00073      * @returns fix_age in milliseconds if available
00074      */
00075     inline void get_datetime(unsigned long *date, unsigned long *time, unsigned long *fix_age = 0)
00076     {
00077       if (date) *date = _date;
00078       if (time) *time = _time;
00079       if (fix_age) *fix_age = _last_time_fix == GPS_INVALID_FIX_TIME ? 
00080         GPS_INVALID_AGE : millis() - _last_time_fix;
00081     }
00082 
00083     /** signed altitude in centimeters (from GPGGA sentence)
00084      * @returns altitude in centimeters, integer
00085      */
00086     inline long altitude() { return _altitude; }
00087 
00088     /** course in last full GPRMC sentence in 100th of a degree
00089      * @returns course as an integer, 100ths of a degree
00090      */
00091     inline unsigned long course() { return _course; }
00092     
00093     /** speed in last full GPRMC sentence in 100ths of a knot
00094      * @returns speed in 100ths of a knot
00095      */
00096     unsigned long speed() { return _speed; }
00097 
00098     /* horizontal dilution of position in last full GPGGA sentence in 100ths
00099      * @returns hdop in 100ths
00100      */
00101     unsigned long hdop() { return _hdop; }
00102 
00103     /** number of satellites tracked in last full GPGGA sentence
00104      * @returns number of satellites tracked 
00105      */
00106     unsigned long sat_count() { return _sat_count; }
00107 
00108 #ifndef _GPS_NO_STATS
00109     void stats(unsigned long *chars, unsigned short *good_sentences, unsigned short *failed_cs);
00110 #endif
00111 
00112     /** returns position as double precision
00113      *
00114      * @returns latitude as double precision
00115      * @returns longitude as double precision
00116      * @returns fix age in milliseconds if available
00117      */
00118     inline void f_get_position(double *latitude, double *longitude, unsigned long *fix_age = 0)
00119     {
00120       long lat, lon;
00121       get_position(&lat, &lon, fix_age);
00122       *latitude = lat / 100000.0;
00123       *longitude = lon / 100000.0;
00124     }
00125 
00126     /** Convert date and time of last parsed sentence to integers
00127      *
00128      * @returns year
00129      * @returns month
00130      * @returns day of month
00131      * @returns hour
00132      * @returns minute
00133      * @returns second
00134      * @returns hundreths
00135      * @returns fix_age in milliseconds if available
00136      */
00137     inline void crack_datetime(int *year, byte *month, byte *day, 
00138       byte *hour, byte *minute, byte *second, byte *hundredths = 0, unsigned long *fix_age = 0)
00139     {
00140       unsigned long date, time;
00141       get_datetime(&date, &time, fix_age);
00142       if (year) 
00143       {
00144         *year = date % 100;
00145         *year += *year > 80 ? 1900 : 2000;
00146       }
00147       if (month) *month = (date / 100) % 100;
00148       if (day) *day = date / 10000;
00149       if (hour) *hour = time / 1000000;
00150       if (minute) *minute = (time / 10000) % 100;
00151       if (second) *second = (time / 100) % 100;
00152       if (hundredths) *hundredths = time % 100;
00153     }
00154 
00155     /** returns altitude as a float
00156     */
00157     inline double f_altitude()    { return altitude() / 100.0; }
00158     
00159     /** returns course as a float
00160     */
00161     inline double f_course()      { return course() / 100.0; }
00162     
00163     /** returns speed in knots as a float
00164     */
00165     inline double f_speed_knots() { return speed() / 100.0; }
00166     
00167     /** returns speed in mph as a float 
00168     */
00169     inline double f_speed_mph()   { return _GPS_MPH_PER_KNOT * f_speed_knots(); }
00170     
00171     /** returns speed in meters per second as a float
00172     */
00173     inline double f_speed_mps()   { return _GPS_MPS_PER_KNOT * f_speed_knots(); }
00174     
00175     /** returns speed in km per hour as a float
00176     */
00177     inline double f_speed_kmph()  { return _GPS_KMPH_PER_KNOT * f_speed_knots(); }
00178     
00179     /** returns hdop as a float
00180     */
00181     inline double f_hdop()      { return hdop() / 100.0; }
00182 
00183     /** @returns library version
00184     */
00185     static int library_version() { return _GPS_VERSION; }
00186 
00187     /** determine if RMC sentence parsed since last reset_ready()
00188      */
00189     inline bool rmc_ready() { return _rmc_ready; }
00190 
00191     /** determine if GGA sentence parsed since last reset_ready()
00192      */
00193     inline bool gga_ready() { return _gga_ready; }
00194 
00195     /** determine if GSV sentence parsed since last reset_ready()
00196      */
00197     inline bool gsv_ready() { return _gsv_ready; }
00198     
00199     /** Reset the ready flags for all the parsed sentences
00200      */
00201     inline void reset_ready() { _gsv_ready = _rmc_ready = _gga_ready = false; }
00202 
00203     enum {GPS_INVALID_AGE = 0xFFFFFFFF, GPS_INVALID_ANGLE = 999999999, GPS_INVALID_ALTITUDE = 999999999, GPS_INVALID_DATE = 0,
00204       GPS_INVALID_TIME = 0xFFFFFFFF, GPS_INVALID_SPEED = 999999999, GPS_INVALID_FIX_TIME = 0xFFFFFFFF};
00205 
00206 private:
00207     enum {_GPS_SENTENCE_GPGGA, _GPS_SENTENCE_GPRMC, _GPS_SENTENCE_GPGSV, _GPS_SENTENCE_OTHER};
00208     
00209     // properties
00210     unsigned long _time, _new_time;
00211     unsigned long _date, _new_date;
00212     long _latitude, _new_latitude;
00213     long _longitude, _new_longitude;
00214     long _altitude, _new_altitude;
00215     unsigned long  _speed, _new_speed;
00216     unsigned long  _course, _new_course;
00217     unsigned long  _hdop, _new_hdop;
00218     unsigned int _sat_count, _new_sat_count;
00219     unsigned long _last_time_fix, _new_time_fix;
00220     unsigned long _last_position_fix, _new_position_fix;
00221 
00222     // parsing state variables
00223     byte _parity;
00224     bool _is_checksum_term;
00225     char _term[15];
00226     byte _sentence_type;
00227     byte _term_number;
00228     byte _term_offset;
00229     bool _gps_data_good;
00230     bool _rmc_ready;
00231     bool _gga_ready;
00232     bool _gsv_ready;
00233 
00234 #ifndef _GPS_NO_STATS
00235     // statistics
00236     unsigned long _encoded_characters;
00237     unsigned short _good_sentences;
00238     unsigned short _failed_checksum;
00239     unsigned short _passed_checksum;
00240 #endif
00241 
00242     // internal utilities
00243     int from_hex(char a);
00244     unsigned long parse_decimal();
00245     unsigned long parse_degrees();
00246     bool term_complete();
00247     bool gpsisdigit(char c) { return c >= '0' && c <= '9'; }
00248     long gpsatol(const char *str);
00249     int gpsstrcmp(const char *str1, const char *str2);
00250 };
00251 
00252 // Arduino 0012 workaround
00253 #undef int
00254 #undef char
00255 #undef long
00256 #undef byte
00257 #undef double
00258 #undef abs
00259 #undef round 
00260 
00261 #endif