NMEA Client JS

A TypeScript/JavaScript client library for connecting to NMEA data streams via WebSocket. Perfect for real-time maritime navigation applications.

Features

• 🌊 Real-time NMEA data streaming via WebSocket
• 📡 Type-safe TypeScript definitions for all NMEA sentences
• 🔄 Automatic reconnection with exponential backoff
• 💓 Built-in heartbeat mechanism for connection health monitoring
• 🎯 Sentence-specific callbacks for targeted data processing
• 🚢 Maritime-focused with support for all common NMEA 0183 sentences

Installation

npm install nmea-client-js

Quick Start

import { NMEAClient } from 'nmea-client-js';

// Connect to your NMEA WebSocket server
const client = new NMEAClient('ws://localhost:8080/ws');

// Listen to all NMEA messages
client.onMessage((message) => {
  console.log('Received NMEA data from source:', message.source_key);
  console.log('Data:', message.data);
});

// Listen to specific sentence types
client.onSentence('GGA', (message) => {
  console.log('GPS Fix Data from', message.source_key, ':', message.data);
});

client.onSentence('RMC', (message) => {
  console.log('Recommended Minimum from', message.source_key, ':', message.data);
});

// Listen to data from a specific source
client.onSourceKey('gps-source-1', (message) => {
  console.log('Data from GPS source 1:', message.data);
});

// Listen to specific sentence from a specific source
client.onSentenceFromSource('GGA', 'gps-source-1', (message) => {
  console.log('GGA data specifically from GPS source 1:', message.data);
});

// Start the connection
client.connect();

API Reference

Constructor

const client = new NMEAClient(url: string);

• url: WebSocket endpoint URL (e.g., ws://localhost:8080/ws)

Methods

connect(): void

Establishes WebSocket connection with automatic reconnection support.

onMessage(callback: (message: WebSocketMessage) => void): void

Listen to all incoming NMEA messages.

onSourceKey(sourceKey: string, callback: (message: WebSocketMessage) => void): void

Listen to all messages from a specific source.

onSentenceFromSource<T>(sentenceID: T, sourceKey: string, callback: (message: WebSocketMessage) => void): void

Listen to specific NMEA sentence types from a specific source.

getSourceKey(message: WebSocketMessage): string

Extract the source key from a WebSocket message.

Message Format

interface WebSocketMessage {
  source_key: string;
  data: NMEASentenceUnion;
}

Supported NMEA Sentences

The client supports all standard NMEA 0183 sentences including:

• GGA - Global Positioning System Fix Data
• RMC - Recommended Minimum Navigation Information
• VTG - Track Made Good and Ground Speed
• GSA - GPS DOP and Active Satellites
• GSV - GPS Satellites in View
• And many more...

Advanced Usage

Error Handling

client.onMessage((message) => {
  try {
    // Process your NMEA data
    console.log(`Processing data from source: ${message.source_key}`);
    processNMEAData(message.data);
  } catch (error) {
    console.error('Error processing NMEA data:', error);
  }
});

Connection Management

The client automatically handles:

• Connection failures with exponential backoff
• Heartbeat/ping messages to maintain connection
• Graceful reconnection when connection is lost

Configuration

// The client uses reasonable defaults
const client = new NMEAClient('ws://localhost:8080/ws');

// Reconnection and heartbeat settings are built-in:
// - Reconnect interval: 5 seconds
// - Ping interval: 10 seconds  
// - Max reconnect attempts: 10

Examples

Real-time GPS Tracking

import { NMEAClient } from 'nmea-client-js';

const client = new NMEAClient('ws://localhost:8080/ws');

client.onSentence('GGA', (message) => {
  const gga = message.data;
  if (gga.latitude && gga.longitude) {
    updateMapPosition({
      lat: gga.latitude,
      lng: gga.longitude,
      quality: gga.quality,
      satellites: gga.numSatellites,
      source: message.source_key  // Track which GPS unit this came from
    });
  }
});

client.connect();

Maritime Dashboard

import { NMEAClient } from 'nmea-client-js';

const client = new NMEAClient('ws://localhost:8080/ws');

// Speed and heading
client.onSentence('VTG', (message) => {
  updateSpeedDisplay(message.data.speedKnots, message.source_key);
  updateHeadingDisplay(message.data.trackTrue, message.source_key);
});

// Depth information  
client.onSentence('DBT', (message) => {
  updateDepthDisplay(message.data.depthFeet, message.source_key);
});

// Wind data
client.onSentence('MWV', (message) => {
  updateWindDisplay({
    angle: message.data.windAngle,
    speed: message.data.windSpeed,
    unit: message.data.speedUnit,
    source: message.source_key
  });
});

client.connect();

Multi-Source Data Handling

When working with multiple NMEA sources (multiple GPS units, AIS transponders, etc.):

import { NMEAClient } from 'nmea-client-js';

const client = new NMEAClient('ws://localhost:8080/ws');

// Handle GPS data from primary and backup units
client.onSentenceFromSource('GGA', 'primary-gps', (message) => {
  console.log('Primary GPS position:', message.data);
  updatePrimaryGPSDisplay(message.data);
});

client.onSentenceFromSource('GGA', 'backup-gps', (message) => {
  console.log('Backup GPS position:', message.data);
  updateBackupGPSDisplay(message.data);
});

// Handle all AIS data from any source
client.onSentence('VDM', (message) => {
  console.log(`AIS data from ${message.source_key}:`, message.data);
  processAISMessage(message.data, message.source_key);
});

// Monitor specific source connectivity
client.onSourceKey('engine-data', (message) => {
  updateEngineSourceStatus('connected');
  processEngineData(message.data);
});

client.connect();

Migration from v1.x

If you're upgrading from version 1.x, the main change is in the message format:

v1.x (old format):

interface WebSocketMessage {
  source: {
    type: string;
    id: string;
  };
  data: NMEASentenceUnion;
}

// Old usage
client.onMessage((message) => {
  console.log(`Data from ${message.source.type}:${message.source.id}`);
});

v2.x (new format):

interface WebSocketMessage {
  source_key: string;
  data: NMEASentenceUnion;
}

// New usage
client.onMessage((message) => {
  console.log(`Data from ${message.source_key}`);
});

Migration Steps:

1. Update your message handlers to use message.source_key instead of message.source.id or message.source.type
2. Consider using the new helper methods like onSourceKey() and onSentenceFromSource() for better source filtering
3. Update your source identification logic to work with string keys instead of type/id objects

TypeScript Support

Full TypeScript support with auto-completion for all NMEA sentence fields:

client.onSentence('GGA', (message) => {
  // TypeScript knows the exact structure of GGA messages
  const {
    latitude,
    longitude,
    quality,
    numSatellites,
    hdop,
    altitude
  } = message.data; // All properly typed!
});

Server Integration

This client is designed to work with the MOC NMEA Go server, but can connect to any WebSocket server that broadcasts NMEA data in the expected format.

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.