This library provides a state machine-based solution for parsing NMEA 0183 sentences from serial ports using the Web Serial API. It builds on top of nmea-simple and extends it with custom depth sentence codecs (DPT, DBS, DBK) and a navigation data adapter that computes position, time, speed, heading, and depth from multiple NMEA sentences.
The library uses XState to orchestrate and manage the serial port connection state.
The official NMEA 0183 standard can be found here and is described in clear terms here.
The Web Serial API is supported in:
- Chrome 89+
- Edge 89+
- Opera 75+
Firefox and Safari do not currently support the Web Serial API.
npm install nmea-web-serialThe simplest way to use the library is with the client API, which provides a clean abstraction over the state machine:
import { NavigationNmeaClient } from 'nmea-web-serial'
// Create a client for navigation data
const client = new NavigationNmeaClient({
baudRate: 4800,
enableLogging: false,
onData: (navigationData) => {
if (navigationData.position) {
console.log('Position:', navigationData.position.latitude, navigationData.position.longitude)
}
if (navigationData.speed) {
console.log('Speed:', navigationData.speed.knots, 'knots')
}
if (navigationData.heading) {
console.log('Heading:', navigationData.heading.degreesTrue, '°')
}
},
onStateChange: (isConnected) => {
console.log('Connection state:', isConnected ? 'connected' : 'disconnected')
},
onError: (error) => {
console.error('Error:', error)
},
})
// Connect to a serial port
client.connect()
// Access current data
const currentData = client.data
const isConnected = client.isConnected
// Disconnect when done
client.disconnect()
// Clean up resources
client.dispose()The client API provides a simple, framework-agnostic interface for managing NMEA connections without needing to work directly with XState machines.
For navigation-focused use cases, use NavigationNmeaClient:
import { NavigationNmeaClient } from 'nmea-web-serial'
const client = new NavigationNmeaClient({
// Optional: baud rate (default: 4800)
baudRate: 4800,
// Optional: enable logging of parsed packets
enableLogging: true,
// Optional: callback when navigation data updates
onData: (navigationData) => {
// navigationData contains position, time, speed, heading, depth
},
// Optional: callback when connection state changes
onStateChange: (isConnected) => {
// isConnected is true when connected, false otherwise
},
// Optional: callback when errors occur
onError: (error) => {
// error is a string message
},
})For custom data adapters, use the generic NmeaClient:
import { createNmeaMachine, NmeaClient } from 'nmea-web-serial'
// Create a custom machine with your adapter
const machine = createNmeaMachine({
adapter: myAdapter,
allowedSentenceIds: ['GGA', 'RMC'],
initialData: { customField: null },
initialPackets: {},
})
// Create a client from the machine
const client = new NmeaClient(machine, {
baudRate: 4800,
enableLogging: false,
onData: (data) => {
// Your custom data type
},
onStateChange: (isConnected) => {
// Connection state changes
},
onError: (error) => {
// Error handling
},
})client.connect()- Connects to a serial port (triggers browser port selection dialog)client.disconnect()- Disconnects from the serial portclient.data- Get the current data (read-only property)client.isConnected- Check if currently connected (read-only property)client.isConnecting- Check if connection is in progress (read-only property)client.error- Get the current error message, if any (read-only property)client.setLogging(enabled)- Enable or disable logging of parsed packetsclient.setBaudRate(baudRate)- Set the baud rate (requires reconnection to take effect)client.machine- Access the underlying XState actor (for advanced use)client.dispose()- Clean up resources and stop the machine
It is possible to work with the machine API directly. Please consult the XState documentation for more information on how to use the machine API.
import { createNavigationNmeaMachine } from 'nmea-web-serial'
import { createActor } from 'xstate'
// Create the machine
const machine = createNavigationNmeaMachine()
// Create the actor
const actor = createActor(machine)
actor.start()
// Subscribe to state changes
actor.subscribe((state) => {
if (state.value === 'connected') {
const navigationData = state.context.data
if (navigationData.position) {
console.log('Position:', navigationData.position.latitude, navigationData.position.longitude)
}
if (navigationData.speed) {
console.log('Speed:', navigationData.speed.knots, 'knots')
}
if (navigationData.heading) {
console.log('Heading:', navigationData.heading.degreesTrue, '°')
}
}
})
// Connect to a serial port
actor.send({ type: 'CONNECT' })
// Disconnect when done
actor.send({ type: 'DISCONNECT' })The library uses an adapter pattern to transform raw NMEA packets into your application's data format. Here's how it works:
-
Raw Packets Storage: As NMEA sentences are parsed, they're stored in a
packetsobject keyed by sentence ID (e.g.,{ GGA: {...}, RMC: {...} }). -
Adapter Function: An adapter is a function that takes the current
packetsobject and transforms it into your desired data structure. This function is called automatically whenever a new packet arrives. -
Computed Data: The result of the adapter function is stored as
datain the machine context, which you can access via the client API or machine state.
Example Flow:
Raw NMEA Sentence → Parsed Packet → Stored in packets → Adapter Function → Computed Data
For example, the navigation adapter takes packets like GGA, RMC, VTG, etc., and computes a unified NavigationData object with position, time, speed, heading, and depth fields. It handles priority logic (e.g., prefer GGA over RMC for position) and data merging automatically.
You can create your own adapters to transform packets into any data structure that fits your application's needs.
The navigation adapter automatically computes navigation data from multiple NMEA sentences using priority-based fallback:
- Position: GGA (with fix) → RMC (valid) → GLL (valid)
- Time: ZDA → GGA → RMC → GLL (ZDA includes timezone for local time)
- Speed: VTG → RMC
- Heading: HDT → HDG → COG (from RMC/VTG)
- Depth: DPT → DBT → DBS → DBK
You can create custom machines with your own adapter functions:
import { createNmeaMachine } from 'nmea-web-serial'
interface MyData {
customField: string | null
}
interface MyPackets extends Record<string, unknown> {
GGA?: GGAPacket
// ... other packet types
}
function myAdapter(packets: MyPackets): MyData {
return {
customField: packets.GGA ? 'has position' : null
}
}
const machine = createNmeaMachine({
adapter: myAdapter,
allowedSentenceIds: ['GGA', 'RMC'],
initialData: { customField: null },
initialPackets: {},
})The library supports all packet types from nmea-simple, plus the following custom depth sentences:
DPT- DepthDBS- Depth Below SurfaceDBK- Depth Below Keel
The navigation adapter uses the following sentence types to compute navigation data:
GGA- GPS Fix DataRMC- Recommended Minimum Specific GNSS DataGLL- Geographic Position: Latitude/LongitudeVTG- Course Over Ground and Ground SpeedHDT- Heading, TrueHDG- Heading, Deviation & VariationDPT- DepthDBT- Depth Below TransducerDBS- Depth Below SurfaceDBK- Depth Below KeelZDA- Time & Date
This project is written in TypeScript. The library can be used by plain JavaScript as shown above, and the typing information is included with the library so that anyone wishing to use TypeScript will gain the benefits of the type information.
This module is built on top of nmea-simple and uses XState for state management. The documentation was expanded based on the excellent analysis and descriptions by Eric S. Raymond.