Usage

GPS.js is an extensible parser for NMEA sentences, given by any common GPS receiver. The output is tried to be as high-level as possible to make it more useful than simply splitting the information. The aim is, that you don't have to understand NMEA, just plug in your receiver and you're ready to go.

Usage

The interface of GPS.js is as simple as the following few lines. You need to add an event-listener for the completion of the task and invoke the update method with a sentence you want to process. There are much more examples in the examples folder.

var gps = new GPS;

// Add an event listener on all protocols
gps.on('data', function(parsed) {
    console.log(parsed);
});

// Call the update routine directly with a NMEA sentence, which would
// come from the serial port or stream-reader normally
gps.update("$GPGGA,224900.000,4832.3762,N,00903.5393,E,1,04,7.8,498.6,M,48.0,M,,0000*5E");

It's also possible to add event-listeners only on one of the following protocols, by stating gps.on('GGA', ...) for example.

State

The real advantage over other NMEA implementations is, that the GPS information is interpreted and normalized. The most high-level API is the state object, which changes with every new event. You can use this information with:

gps.on('data', function() {
  console.log(gps.state);
});

Installation

Installing GPS.js is as easy as cloning this repo or use the following command:

npm install gps

Find the serial device

On Linux serial devices typically have names like /dev/ttyS1, on OSX /dev/tty.usbmodem1411 after installing a USB to serial driver and on Windows, you're probably fine by using the highest COM device you can find in the device manager. Please note that if you have multople USB ports on your computer and use them randomly, you have to lookup the path/device again.

Register device on a BeagleBone

If you find yourself on a BeagleBone, the serial device must be registered manually. Luckily, this can be done within node quite easily using octalbonescript:

var obs = require('octalbonescript');
obs.serial.enable('/dev/ttyS1', function() {  
    console.log('serial device activated');
});

Examples

GPS.js comes with some examples, like drawing the current latutude and longitude to Google Maps, displaying a persistent state and displaying the parsed raw data. In some cases you have to adjust the serial path to your own GPS receiver to make it work.

Simple serial example

var SerialPort = require('serialport');
var port = new SerialPort.SerialPort('/dev/tty.usbserial', { // change path
  baudrate: 4800,
  parser: SerialPort.parsers.readline('\r\n')
});

var GPS = require('gps');
var gps = new GPS;

gps.on('data', function(data) {
  console.log(data, gps.state);
});

port.on('data', function(data) {
  gps.update(data);
});

Dashboard

Go into the folder examples/dashboard and start the server with

node server

After that you can open the browser and go to http://localhost:3000. The result should look like the following, which in principle is just a visualiziation of the state object gps.state

Google Maps

Go into the folder examples/maps and start the server with

node server

After that you can open the browser and go to http://localhost:3000 The result should look like

Confluence

Confluence is a project, which tries to travel to and document all integer GPS coordinates. GPS.js can assist on that goal. Go into the examples folder and run:

node confluence

You should see something like the following, updating as you move around

You are at (48.53, 9.05951),
The closest confluence point (49, 9) is in 51.36 km.
You have to go 355.2° N

Set Time

On systems without a RTC - like Raspberry PI - you need to update the time yourself at runtime. If the device has an internet connection, it's quite easy to use an NTP server. An alternative for disconnected projects with access to a GPS receiver can be the high-precision time signal, sent by satellites. Go to the examples folder and run the following to update the time:

node set-date

Available Methods

update(line)

The update method is the most important function, it adds a new NMEA sentence and forces the callback to trigger

updatePartial(chunk)

Will call update() when a full NMEA sentence has been arrived

on(event, callback)

Adds an event listener for a protocol to occur (see implemented protocols, simply use the name - upper case) or for all sentences with data. Because GPS.js should be more general, it doesn't inherit EventEmitter, but simply invokes the callback.

off(event)

Removes an event listener

Implemented Protocols