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 getLongitude(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.

bool getGeoidHeight(long &hgt) const

Height above WGS84 Geoid in millimetres, returns true if the height 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
per1234
Noah-Jonathan Rosa
Philipp Tölke

Class Documentation¶

class MicroNMEA¶

Process MicroNMEA sentences from GPS and GNSS receivers.

The user is responsible to allocating the buffer that MicroNMEA uses. This enables a static buffer to be used if desired so that malloc() is not required. Values returned are integers, floating-point maths is not used.

Public Functions

MicroNMEA(void)¶

Default constructor.

User must call setrBuffer() before use

MicroNMEA(void *buffer, uint8_t len)¶: Construct object and pass in the buffer allocated for MicroNMEA to use.

void setBuffer(void *buf, uint8_t len)¶

Set the buffer object.

Parameters

buf – Address of the buffer
len – Number of bytes allocated

void clear(void)¶

Clear all fix information.

isValid() will return false, year, month and day will all be zero. Hour, minute and second 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.

inline char getNavSystem(void) const¶

Get the navigation system in use.

N = GNSS, P = GPS, L = GLONASS, A = Galileo, \0 = none

Returns: char

inline uint8_t getNumSatellites(void) const¶

Get the number of satellites in use.

Returns: uint8_t

inline uint8_t getHDOP(void) const¶

Get the horizontal dilution of precision (HDOP), in tenths.

A HDOP value of 1.1 is returned as 11

Returns: uint8_t

inline bool isValid(void) const¶

Inquire if latest fix is valid.

Returns: true Valid
Returns: false Not valid

inline long getLatitude(void) const¶

Get the latitude, in millionths of a degree.

North is positive.

Returns: long

inline long getLongitude(void) const¶

Get the longitude, in millionths of a degree.

East is positive.

Returns: long

inline bool getAltitude(long &alt) const¶

Get the altitude in millmetres.

Parameters: alt – Reference to long value where altitude is to be stored
Returns: true Altitude is valid
Returns: false Altitude not valid

inline bool getGeoidHeight(long &alt) const¶

Get the height above WGS84 Geoid in millimetres.

Parameters: alt – Reference to long value where height is to be stored
Returns: uint16_t year
Returns: true Altitude is valid
Returns: false Altitude not valid

inline uint16_t getYear(void) const¶

Get the year.

Returns: uint16_t year

inline uint8_t getMonth(void) const¶

Get the month (1 - 12 inclusive)

Returns: uint8_t year

inline uint8_t getDay(void) const¶

Get the day of month (1 - 31 inclusive)

Returns: uint8_t month

inline uint8_t getHour(void) const¶

Get the hour.

Returns: uint8_t hour

inline uint8_t getMinute(void) const¶

Get the minute.

Returns: uint8_t minute

inline uint8_t getSecond(void) const¶

Get the integer part of the second.

Returns: uint8_t second

inline uint8_t getHundredths(void) const¶

Get the hundredths part of the second.

Returns: uint8_t hundredths

inline long getSpeed(void) const¶

Get the speed.

Returns: uint8_t speed

inline long getCourse(void) const¶

Get the direction of travel.

Returns: Direction in thousandths of a degree, clockwise from North

bool process(char c)¶

Instruct MicroNMEA to process a character.

Parameters: c – Character to process
Returns: true A complete non-empty sentence has been processed (may not be valid)
Returns: false End of sentence not detected

inline void setBadChecksumHandler(void (*handler)(MicroNMEA &nmea))¶

Register a handler to be called when bad checksums are detected.

Parameters: handler – pointer to handler function

inline void setUnknownSentenceHandler(void (*handler)(MicroNMEA &nmea))¶

Register a handler to be called when an unknown NMEA sentence is detected.

Parameters: handler – pointer to handler function

inline const char *getSentence(void) const¶

Get NMEA sentence.

Returns: const char*

Public Static Functions

static Stream &sendSentence(Stream &s, const char *sentence)¶

Send a NMEA sentence to the GNSS receiver.

The sentence must start with $; the checksum and \r\n terminators will be appended automatically.

Parameters

s – Stream to which the GNSS receiver is connected
sentence – The NMEA sentence to send

Returns

The GNSS stream

This documentation was built using ArduinoDocs.