rotu / nmea-simple

JavaScript parser for NMEA 0183 sentences

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.

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

Custom packets

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.

const logSentenceId: "LOG" = "LOG";

export interface LogPacket extends PacketStub<typeof logSentenceId> {
    logNum: number;
    logMsg: string;
}

class CustomPacketFactory extends DefaultPacketFactory<LogPacket> {
    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:

    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

Unsafe packets

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 ?.

    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.