145 lines
5.6 KiB
ReStructuredText
145 lines
5.6 KiB
ReStructuredText
MicroNMEA
|
|
=========
|
|
|
|
MicroNMEA is a compact Arduino library to parse a subset of NMEA
|
|
sentences, which can originate from either GPS or GNSS receivers. Only
|
|
two types of messages are parsed, ``$GPGGA`` (and its GNSS
|
|
versions ``$GNGGA``, ``$GLGGA``, and ``$GAGGA``) and ``$GPRMC`` (and
|
|
its GNSS versions ``$GNRMC``, ``$GLRMC``, and ``$GARMC``). From these
|
|
two NMEA sentences MicroNMEA can output date, time, latitude,
|
|
longitude, altitude, number of satellites used, horizontal dilution of
|
|
precision (HDOP), course and speed. When other NMEA sentences are
|
|
detected they can be passed to an optional callback function for
|
|
decoding or logging. Checksum failures can be indicated with another
|
|
optional callback function.
|
|
|
|
NMEA sentences can easily be sent to an output stream with the
|
|
``sendSentence()`` function which computes and appends the checksum,
|
|
as well as the correct ``<CR><LF>`` terminators.
|
|
|
|
License
|
|
-------
|
|
|
|
The MicroNMEA library is released under the GNU Lesser General Public License, version 2.1.
|
|
http://www.gnu.org/licenses/lgpl-2.1.html
|
|
|
|
Initialization and basic usage
|
|
------------------------------
|
|
|
|
A ``MicroNMEA`` object must be defined with a pointer to a buffer and the buffer length::
|
|
|
|
char buffer[85];
|
|
MicroNMEA nmea(buffer, sizeof(buffer));
|
|
|
|
This approach enables the user to size the buffer appropriately according to use without requiring ``malloc()``; for instance the buffer size can be increased if the temporal and spatial resolution reported have been increased by some properietary NMEA command.
|
|
|
|
Output data from the GPS/GNSS device must be passed to the library for processing::
|
|
|
|
while (gps.available()) {
|
|
char c = gps.read();
|
|
if (nmea.process(c)) {
|
|
// Complete NMEA command read and processed, do something
|
|
...
|
|
}
|
|
}
|
|
|
|
In the code fragment above ``gps`` is the output stream of the GPS/GNSS device.
|
|
|
|
Retrieving information from MicroNMEA
|
|
-------------------------------------
|
|
Location, date, time and various status information can be requested using the appropriate member functions which are described below. To obtain all of the information listed below MicroNMEA must process both ``GxGGA`` and ``GxRMC`` sentences::
|
|
|
|
char getNavSystem() const
|
|
|
|
Returns a single character indicating the navigation system in use:
|
|
|
|
+--------+-----------------------------------------------------------------+
|
|
| ``P`` | Navigation results based only on GPS satellites. |
|
|
+--------+-----------------------------------------------------------------+
|
|
| ``L`` | Navigation results based only on GLONASS satellites. |
|
|
+--------+-----------------------------------------------------------------+
|
|
| ``A`` | Navigation results based only on Galileo satellites. |
|
|
+--------+-----------------------------------------------------------------+
|
|
| ``N`` | GNSS, navigation results from multiple satellite constellations.|
|
|
+--------+-----------------------------------------------------------------+
|
|
| ``\0`` | No valid fix |
|
|
+--------+-----------------------------------------------------------------+
|
|
|
|
::
|
|
|
|
uint8_t getHDOP(void) const
|
|
|
|
Horizontal dilution of precision in tenths (i.e., divide by 10 to get true HDOP). ::
|
|
|
|
bool isValid(void) const
|
|
|
|
Validity of latest fix. ::
|
|
|
|
long getLatitude(void) const
|
|
|
|
Latitude in millionths of a degree, North is positive. ::
|
|
|
|
long getLlongitude(void) const
|
|
|
|
Longitude in millionths of a degree, East is positive. ::
|
|
|
|
bool getAltitude(long &alt) const
|
|
|
|
Altitude in millimetres, returns true if the altitude was obtained from a valid fix. ::
|
|
|
|
uint16_t getYear(void) const
|
|
uint8_t getMonth(void) const
|
|
uint8_t getDay(void) const
|
|
uint8_t getHour(void) const
|
|
uint8_t getMinute(void) const
|
|
uint8_t getSecond(void) const
|
|
uint8_t getHundredths(void) const
|
|
|
|
Date and time. ::
|
|
|
|
long getCourse(void) const
|
|
|
|
Course over ground, in thousandths of a degree. ::
|
|
|
|
long getSpeed(void) const
|
|
|
|
Speed over ground, in thousandths of a knot. ::
|
|
|
|
void clear(void)
|
|
|
|
Clear all stored values. ``isValid()`` will return false. Year, month and day will all be zero. Hour, minute and second time will be set to 99. Speed, course and altitude will be set to ``LONG_MIN``; the altitude validity flag will be false. Latitude and longitude will be set to 999 degrees.
|
|
|
|
Callback and associated functions
|
|
---------------------------------
|
|
|
|
::
|
|
|
|
void setBadChecksumHandler(void (*handler)(MicroNMEA& nmea))
|
|
|
|
``setBadChecksumHandler()`` enables MicroNMEA to call a function when a bad NMEA checksum is detected. The callback function should accept a single parameter (a ``MicroNMEA`` object passed by reference) and return ``void``. ::
|
|
|
|
void setUnknownSentenceHandler(void (*handler)(MicroNMEA& nmea))
|
|
|
|
``setUnknownSentenceHandler()`` enables MicroNMEA to call a function when a valid but unknown NMEA command is
|
|
received. The callback function should accept a single parameter (a ``MicroNMEA`` object passed by reference) and return ``void``. ::
|
|
|
|
const char* getSentence(void) const
|
|
|
|
Return the current NMEA sentence. Useful when using callback functions. ::
|
|
|
|
char getTalkerID(void) const
|
|
|
|
Return the talker ID from the last processed NMEA sentence. The meaning is the same as the return value from ``getNavSystem()``. If ``$GxGSV`` messages are received then talker ID could be from any of the GNSS constellations. ::
|
|
|
|
const char* getMessageID(void) const
|
|
|
|
Return the message ID from the last processed NMEA sentence, e.g, ``RMC``, ``GGA``. Useful when using callback functions.
|
|
|
|
|
|
Contributors
|
|
------------
|
|
|
|
- Steve Marple
|
|
- Christopher Liebman
|
|
|
|
|