GPSParser

This library is a parser for standard NMEA sentences used by GPS devices.

All data is transmitted in the form of sentences. Only printable Ascii characters plus CR (carriage return) and LF (line feed) are allowed in a GPS sentence. The expected sentence format starts with $, which is followed by five characters. The first two characters are the talker identifier. The next three characters are the sentence identifier. Following the identifiers are a number of data fields separated by commas, then an optional checksum, and finally a carriage return and a line feed (CRLF). The data fields are uniquely defined for each sentence type.

For information on formats used in satellite data packets, please see this page.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To add this library to your project, add #require "GPSParser.device.lib.nut:1.0.0" to the top of your device code.

GPSParser Usage

GPSParser has no constructor. There is no need to create an instance. All of the methods listed below should be called on GPSParser directly.

GPSParser Methods

hasCheckSum(sentence)

This method is used to indicate whether a GPS sentence contains a checksum value.

Parameters

Parameter	Type	Required	Description
sentence	String	Yes	A GPS sentence

Return Value

Boolean — true if the sentence contains a checksum, otherwise false.

Example

local sentence = "$GPVTG,054.7,T,034.4,M,005.5,N,010.2,K*48\r\n";
local hasChecksum = GPSParser.hasCheckSum(sentence);
if (hasChecksum) {
  local checksum = GPSParser.getFields.top();
  server.log(format("0x%s", checksum));
}

isValid(sentence)

This method is used to check whether a GPS sentence is valid — ie. its checksum, if it has one, is correct.

Parameters

Parameter	Type	Required	Description
sentence	String	Yes	A GPS sentence

Return Value

Boolean — true if the sentence contains a checksum and the checksum is correct, otherwise false.

Example

local sentence = "$GPGLL,4916.45,N,12311.12,W,225444,A,*1D\r\n";
server.log("GPS sentence check sum is " + (GPSParser.isValid(sentence) ? "" : "in") + "valid.");

getGPSDataTable(sentence)

This method parses a GPS sentence into a table containing specific keys. It does not support all data types received by GPS. Currently it supports VTG, RMC, GLL, GGA, GSV and GSA. The data table will always contain the keys talkerId and sentenceId, which indicate the type of GPS message. However, all other keys will only be included if the GPS sentence contains data. See below for details on the possible key, value pairs for each of the supported data types.

Parameters

Parameter	Type	Required	Description
sentence	String	Yes	A GPS sentence

Return Value

Table — A table containing any of the following keys (the keys talkerId and sentenceId are always included):

VTG: Vector Track and Speed over Ground

Key	Type	Description
talkerId	String	Talker identifier, ie. "GP" or "GN"
sentenceId	String	Sentence identifier: "VTG" (constant GPS_PARSER_VTG)
tTrack	String	True track made good (degrees)
mTrack	String	Magnetic track made good
speedKnots	String	Ground speed in knots
speedKPH	String	Ground speed in kilometers per hour
modeIndicator	String	Signal integrity: "A" (autonomous), "D" (differential), "E" (estimated), "N" (not valid) or "S" (simulated)
error	String	Error description

RMC: Recommended Minimum Data for GPS (Position, Velocity, Time)

Key	Type	Description
talkerId	String	Talker identifier, ie. "GP" or "GN"
sentenceId	String	Sentence identifier: "RMC" (constant GPS_PARSER_RMC)
time	String	UTC Time fix taken in the form "hhmmss"
date	String	Date fix taken in the form "ddmmyy"
speedKnots	String	Speed over the ground in knots
trackAngle	String	Track angle in degrees true
latitude	String	The latitude received in decimal degrees
longitude	String	The longitude received in decimal degrees
status	String	The status of the satellite: "A" (active) or "V" (void)
mVar	String	Magnetic variation in degrees
modeIndicator	String	Signal integrity: "A" (autonomous), "D" (differential), "E" (estimated), "N" (not valid) or "S" (simulated)
error	String	Error description

GLL: Geographic Position, Latitude and Longitude

Key	Type	Description
talkerId	String	Talker identifier, ie. "GP" or "GN"
sentenceId	String	Sentence identifie: "GLL" (constant GPS_PARSER_GLL)
time	String	UTC Time fix taken in the form "hhmmss"
status	String	The status of the satellite: "A" (active) or "V" (void)
latitude	String	The latitude received in decimal degrees
longitude	String	The longitude received in decimal degrees
modeIndicator	String	Signal integrity: "A" (autonomous), "D" (differential), "E" (estimated), "N" (not valid) or "S" (simulated)
error	String	Error description

GGA: Global Positioning System Fix Data

Key	Type	Description
talkerId	String	Talker identifier, ie. "GP" or "GN"
sentenceId	String	Sentence identifier: "GGA" (constant GPS_PARSER_GGA)
time	String	UTC Time fix taken in the form "hhmmss"
latitude	String	The latitude received in decimal degrees
longitude	String	The longitude received in decimal degrees
fixQuality	String	The quality of the satellite fix: "0" (invalid) or "1"-"8" (fix info)
numSatellites	String	The number of satellites being tracked
HDOP	String	Horizontal dilution of position
altitude	String	Altitude above mean sea level in meters
geoSeparation	String	Height of geoid (mean sea level) above WGS84 ellipsoid in meters
lastDGPSUpdate	String	Time since last DGPS update in seconds
DGPSStationID	String	DGPS station ID number
error	String	Error description

GSV: Satellites in View

Key	Type	Description
talkerId	String	Talker identifier, ie. "GP" or "GN"
sentenceId	String	Sentence identifier: "GSV" (constant GPS_PARSER_GSV)
numMsgs	String	Total number of messages
msgNum	String	Message number
numSatellites	String	Number of satellites in view
satelliteInfo	Array	Array of tables with detailed satellite info (satellite PRN, elevation, azimuth, SNR)
error	String	Error description

GSA: Overall Satellite Data

Key	Type	Description
talkerId	String	Talker identifier, ie. "GP" or "GN"
sentenceId	String	Sentence identifier: "GSA" (constant GPS_PARSER_GSA)
selMode	String	Selection mode: "A" (auto) or "M" (manual)
mode	String	Mode: "1" (no fix), "2" (2D fix) or "3" (3D fix)
satellitePRNs	Array	PRNs (IDs) of satellites used for fix
PDOP	String	Dilution of precision
HDOP	String	Horizontal dilution of precision
VDOP	String	Vertical dilution of precision
error	String	Error description

Example

local sentence = "$GPGLL,4916.45,N,12311.12,W,225444,A,*1D\r\n";
local gpsData = GPSParser.getGPSDataTable(sentence);
if gpsData.sentenceId == GPS_PARSER_GLL) {
  server.log("GLL message received.");
  if (gpsData.status == "A" && "latitude" in gpsData && "longitude" in gpsData) {
    server.log(format("Latitude %s, Longitude %s", gpsData.latitude, gpsData.longitude));
  } else {
    server.log("Location data not available.");
  }
}

getFields(sentence)

This method converts a GPS sentence into an array of data fields. The first item in the array will always be the talker and sentence identifiers. The rest of the array will contain all data fields, even if they contain only an empty string. If the sentence includes a checksum this will be the last item in the array.

Parameters

Parameter	Type	Required	Description
sentence	String	Yes	A GPS sentence

Return Value

Array — the data fields contained in the sentence.

Example

local sentence = "$GPGGA,,,,,,0,00,99.99,,,,,,*48\r\n";
local fields = GPSParser.getFields(sentence);
foreach (idx, item in fields) {
  server.log(format("%i. %s", idx + 1, item));
}

parseLatitude(rawLatitude, direction)

This method takes the two latitude fields derived from a GPS GGA sentence (using getFields()) and converts them into a single latitude in decimal degrees.

Parameters

Parameter	Type	Required	Description
rawLatitude	String	Yes	The raw latitude value, eg. "3723.71721"
direction	String	Yes	The direction indicator, eg. "N"

Return Value

String — the latitude as a numeric string.

Example

See below.

parseLongitude(rawLongitude, direction)

This method takes the two longitude fields derived from a GPS GGA sentence (using getFields()) and converts them into a single longitude in decimal degrees.

Parameters

Parameter	Type	Required	Description
rawLatitude	String	Yes	The raw longitude value, eg. "12206.14085"
direction	String	Yes	The direction indicator, eg. "W"

Return Value

String — the latitude as a numeric string.

Example

local sentence = "$GNGGA,181859.00,3723.71721,N,12206.14085,W,1,12,0.97,38.0,M,-30.0,M,,*4C\r\n";
local fields = GPSParser.getFields(sentence);
local type = fields[0].slice(2);
if (type == GPS_PARSER_GGA) {
  // Get Latitude
  if (fields[2] != "" && fields[3] != "") {
    local lat = parseLatitude(fields[2], fields[3]);
    server.log("Latitude: " + lat);
  }
  // Get Longitude
  if (fields[4] != "" && fields[5] != "") {
    local lng = parseLongitude(fields[4], fields[5]);
    server.log("Longitude: " + lng);
  }
}

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release

License

The GPSParser library is licensed under the MIT License.