@canboat/ts-pgns

@canboat/ts-pgns

A comprehensive TypeScript library providing strongly-typed NMEA 2000 Parameter Group Number (PGN) definitions and utilities for marine electronics communication.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• API Documentation
• Usage Examples
• PGN Classes
• Utilities
• Type Safety
• Building from Source
• Contributing
• Version Policy
• License
• Related Projects

Overview

This library provides TypeScript definitions and utilities for working with NMEA 2000 Parameter Group Numbers (PGNs), which are standardized data messages used in marine electronics networks. Built on top of the Canboat project's PGN definitions, it offers type-safe access to hundreds of marine data message formats.

What are PGNs? Parameter Group Numbers are standardized message formats in the NMEA 2000 protocol that define how different types of marine data (GPS position, engine data, weather information, etc.) are structured and transmitted over the network.

Features

• 🔒 Type Safety: Fully typed PGN classes with TypeScript interfaces
• 📊 Comprehensive Coverage: Supports hundreds of standard NMEA 2000 PGNs
• 🛠️ Utility Functions: Helper functions for PGN manipulation and conversion
• 🔍 Enumeration Support: Built-in support for NMEA 2000 enumerations and bit fields
• 🎯 Field Validation: Type-safe field access with proper validation
• 📖 Well Documented: Comprehensive JSDoc documentation and examples
• 🔄 Conversion Utilities: Convert between different PGN representations
• ⚡ Performance Optimized: Efficient lookup and creation of PGN objects

Installation

npm install @canboat/ts-pgns

Quick Start

import { PGN_129029, PGN_127488 } from '@canboat/ts-pgns'
import { pgnToActisenseSerialFormat } from '@canboat/canboatjs'

// Create a GPS Position PGN (129029)
const gpsPosition = new PGN_129029({
  latitude: 47.6062, // Seattle latitude
  longitude: -122.3321, // Seattle longitude
  altitude: 56.0,
  gnssType: 3, // GPS
  method: 1, // GNSS fix
  integrity: 0, // No integrity checking
  numberOfSvs: 8, // 8 satellites
  hdop: 1.2, // Horizontal dilution of precision
  geoidalSeparation: -34.0
})

// Create an Engine Parameters PGN (127488)
const engineData = new PGN_127488({
  engineInstance: 0,
  oilPressure: 275000, // 275 kPa
  oilTemperature: 363.15, // 90°C in Kelvin
  temperature: 353.15, // 80°C coolant temp
  alternatorPotential: 14.2,
  fuelRate: 15.5, // L/h
  totalEngineHours: 1250.5,
  coolantPressure: 95000,
  fuelPressure: 280000
})

console.log(
  `GPS Position: ${gpsPosition.fields.latitude}, ${gpsPosition.fields.longitude}`
)
console.log(`Engine Oil Pressure: ${engineData.fields.oilPressure} Pa`)

//Generate actisense serial formated position
const n2k = pgnToActisenseSerialFormat(gpsPosition)
console.log(`actisense posistion ${n2k}`)

API Documentation

Complete API Documentation

Usage Examples

Working with PGN Definitions

import {
  getPGNWithNumber,
  getPGNWithId,
  findMatchingDefinition
} from '@canboat/ts-pgns'

// Get PGN definition by number
const windDefs = getPGNWithNumber(130306) // Wind Data
if (windDefs) {
  console.log(`Found ${windDefs.length} wind data variants`)
}

// Get specific PGN definition by ID
const gpsPosition = getPGNWithId('gnssPositionData')
if (gpsPosition) {
  console.log(`PGN Description: ${gpsPosition.Description}`)
  console.log(`Field count: ${gpsPosition.Fields.length}`)
}

Working with Enumerations

import {
  getEnumerationValue,
  getEnumerationName,
  getBitEnumerationValue
} from '@canboat/ts-pgns'

// Get numeric value for enumeration
const gnssType = getEnumerationValue('GNSS_TYPE', 'GPS')
console.log(`GPS type value: ${gnssType}`) // 3

// Get name from numeric value
const methodName = getEnumerationName('GNSS_METHOD', 1)
console.log(`Method: ${methodName}`) // "GNSS fix"

// Work with bit enumerations
const alertBit = getBitEnumerationValue('ENGINE_ALERT', 'Warning')

PGN Field Manipulation

import { mapCamelCaseKeys, mapNameKeysToCamelCase } from '@canboat/ts-pgns'

// Convert PGN field IDs to camelCase names
const pgn = new PGN_129029({
  /* ... */
})
const camelCasePgn = mapCamelCaseKeys(pgn)

// Now you can access fields by name instead of ID
console.log(camelCasePgn.fields.latitude) // instead of fields.latitude
console.log(camelCasePgn.fields.longitude) // instead of fields.longitude

Creating Group Function Messages

import {
  createNmeaGroupFunction,
  GroupFunction,
  SeatalkPilotMode16,
  PGN_65379_SeatalkPilotMode
} from '@canboat/ts-pgns'

const pgn = new PGN_65379_SeatalkPilotMode({
  pilotMode: SeatalkPilotMode16.TrackMode,
  subMode: 0xffff
})

// Create a command group function to change this data
const requestMsg = createNmeaGroupFunction(
  GroupFunction.Command,
  pgn,
  42 // destination address
)

PGN Classes

The library includes type-safe classes for hundreds of NMEA 2000 PGNs. Some commonly used ones include:

Navigation & Positioning

• PGN_129029 - GNSS Position Data
• PGN_129025 - Position, Rapid Update
• PGN_129026 - COG & SOG, Rapid Update
• PGN_127250 - Vessel Heading
• PGN_130306 - Wind Data

Engine & Propulsion

• PGN_127488 - Engine Parameters, Rapid Update
• PGN_127489 - Engine Parameters, Dynamic
• PGN_127505 - Fluid Level
• PGN_130312 - Temperature

Electrical Systems

• PGN_127508 - Battery Status
• PGN_127506 - DC Detailed Status
• PGN_127513 - Battery Configuration Status

Environmental

• PGN_130310 - Environmental Parameters
• PGN_130311 - Environmental Parameters
• PGN_130316 - Temperature, Extended Range

Each PGN class provides:

• Type-safe field access
• Proper TypeScript interfaces
• Built-in validation
• Access to the underlying PGN definition

Utilities

Core Utilities

• createPGN(id, fields, dst?) - Create PGN instances by ID
• findMatchingDefinition(pgn) - Find the matching definition for a PGN
• getPGNWithNumber(num) - Get PGN definitions by number
• getPGNWithId(id) - Get PGN definition by ID

Field Conversion

• mapCamelCaseKeys(pgn) - Convert field IDs to camelCase names
• mapNameKeysToCamelCase(pgn) - Convert field names to camelCase IDs
• isMatch(pgn, matchFields) - Check if PGN matches specific field values

Enumeration Helpers

• getEnumeration(name) / getEnumerations() - Access enumerations
• getEnumerationValue(enumName, value) - Get numeric value from name
• getEnumerationName(enumName, value) - Get name from numeric value
• getBitEnumeration(name) - Access bit enumerations
• getBitEnumerationValue(enumName, value) - Get bit value from name

SignalK Server Integration

• convertCamelCase(pluginApp, pgn) - Convert keys based on server capability
• convertNamesToCamel(pluginApp, pgn) - Convert names based on server capability

Type Safety

This library provides comprehensive TypeScript support:

// Strongly typed fields
const gps = new PGN_129029({
  latitude: 47.6062, // number
  longitude: -122.3321, // number
  gnssType: 3, // number (enumeration)
  method: 1 // number (enumeration)
})

// TypeScript will catch field type errors
const badGps = new PGN_129029({
  latitude: 'invalid', // ❌ TypeScript error: string not assignable to number
  gnssType: 'GPS' // ❌ TypeScript error: string not assignable to number
})

// Proper enumeration usage
import { GnssType } from '@canboat/ts-pgns'
const correctGps = new PGN_129029({
  latitude: 47.6062,
  longitude: -122.3321,
  gnssType: GnssType.Gps, // ✅ Type-safe enumeration
  method: 1
})

Building from Source

# Clone the repository
git clone https://github.com/canboat/ts-pgns.git
cd ts-pgns

# Install dependencies
npm install

# Build the project
npm run build

# Generate the typescript files if you have changed canboat.json
npm run generate
npm run build

# Run tests
npm test

# Format code
npm run format

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

• Fork the repository
• Create a feature branch: git checkout -b feature/amazing-feature
• Make your changes
• Run tests: npm test
• Run prettier and lint: npm run format
• Commit your changes: git commit -m 'Add amazing feature'
• Push to the branch: git push origin feature/amazing-feature
• Open a Pull Request

Version Policy

Important Note: This library is currently in active development. Minor releases may include breaking changes. Please pin to specific minor versions (e.g., 1.10.x) in your dependencies.

Once the API stabilizes, breaking changes will only be introduced in major releases.

{
  "dependencies": {
    "@canboat/ts-pgns": "~1.10.0" // Pin to minor version
  }
}

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Related Projects

• canboat - Core Canboat
• canboatjs - Core Canboat JavaScript library
• signalk-server - Signal K server implementation

Made with ⚓ by the Canboat project contributors