NMEA 0183 sentence parser and encoder

This library parses and encodes some NMEA 0183 sentences. These are typically
used by GPS receivers to send information on position, heading, speed and
accuracy. The official standard can be found
here and is
described in clear terms here.

Example

Typically, you will get NMEA sentences via the serial port from a GPS module.
You can use the serialport NPM
package to read the lines (and the @serialport/parser-readline parser to
separate the input by "\r\n"). Each line can then be passed into
parseNmeaSentence to get the decoded packet.

``js
const SerialPort = require("serialport");
const Readline = require("@serialport/parser-readline")
const nmea = require("nmea-simple");

const port = new SerialPort(
"/dev/ttyUSB0",
{
baudRate: 9600
}
);

const parser = port.pipe(new Readline({ delimiter: '\r\n' }))

parser.on("data", line => {
try {
const packet = nmea.parseNmeaSentence(line);

if (packet.sentenceId === "RMC" && packet.status === "valid") {
console.log("Got location via RMC packet:", packet.latitude, packet.longitude);
}

if (packet.sentenceId === "GGA" && packet.fixType !== "none") {
console.log("Got location via GGA packet:", packet.latitude, packet.longitude);
}

if (packet.sentenceId === "GSA") {
console.log("There are " + packet.satellites.length + " satellites in view.");
}
} catch (error) {
console.error("Got bad packet:", line, error);
}
});
`

TypeScript

This project is written in TypeScript. The
library can be used by plain JavaScript as shown above, and the typing
information is also included with the library so that anyone wishing to use
TypeScript will gain the benefits of the type information.

Packet types supported

The following sentence types can be parsed by this library:

- APB
- BWC
- DBT
- DTM
- GGA
- GLL
- GNS
- GSA
- GST
- GSV
- HDG
- HDM
- HDT
- MTK
- MWV
- RDID
- RMC
- VHW
- VTG
- ZDA

The following sentence types can be encoded by this library:

- DBT
- GGA
- GLL
- GNS
- HDM
- HDT
- MTK
- MWV
- VTG

This is a fork of the nmea package with
all dependencies removed and TypeScript typing information added.

Extending the library

$3

Custom (proprietary) sentences can be defined with type assurance and added to the parsing algorithm by supplying a custom factory which overrides the assembleCustomPacket function of DefaultPacketFactory class.


`ts
const logSentenceId: "LOG" = "LOG";

export interface LogPacket extends PacketStub {
logNum: number;
logMsg: string;
}

class CustomPacketFactory extends DefaultPacketFactory {
assembleCustomPacket(stub: PacketStub, fields: string[]): LogPacket | null {
if (stub.sentenceId === logSentenceId) {
return {
...initStubFields(logSentenceId, stub),
logNum: parseInt(fields[1], 10),
logMsg: fields[2]
};
}

return null;
}
}

export const CUSTOM_PACKET_FACTORY = new CustomPacketFactory();
`

This extends the first example the following way:

`js
try {
const packet = nmea.parseGenericPacket(line, CUSTOM_PACKET_FACTORY);

if (packet.sentenceId === "LOG") {
console.log("Got a log message:", packet.logMsg);
}

...
`

Make sure not to conflict with built in sentence types!

For more info see CustomPacketsTest.ts

$3

It might be desired to investigate packets that are not recognized or have bad checksum. (For example analyzing occurrence frequency.) For this we can use parseUnsafeNmeaSentence.

This function will parse every packet, even if the ID is unrecognized. sentenceId for these packets are always ?.

`js
try {
const packet = nmea.parseUnsafeNmeaSentence(line);

if (packet.chxOk !== true) {
console.log("Skipping packet with bad checksum:");
return;
}

if (packet.sentenceId === "?") {
console.log("Got an unknown packet with signature:", packet.fields[0]);
}

...
``

Acknowledgements

This module was based on the NPM nmea and
nmea-0183 packages (with date decoding borrowed from GPS) and the
documentation was expanded based on the excellent
analysis and descriptions by Eric S. Raymond.