@canboat/canboatjs

A TypeScript library for parsing, encoding, and interfacing with NMEA 2000 marine electronics networks. It used the PGN definition database from canboat with extensive device support, multiple data format compatibility, and PGN output.

Table of Contents

• Features
• Architecture
• Installation
• Quick Start
• Supported Devices
• Command Line Tools
• API Reference
• Usage Examples
• Device Integration
• Data Formats
• Contributing
• License

Features

• 🔌 Multi-Device Support: Direct interface with popular NMEA 2000 gateways and CAN bus devices
• 📡 Multiple Data Formats: Parse and generate various N2K data formats (Actisense, iKonvert, YDWG, etc.)
• 🔄 Bidirectional: Both decode incoming N2K messages and encode/transmit outgoing messages
• 🛠️ Command Line Tools: Ready-to-use CLI utilities for data conversion and analysis
• 🎯 Type Safety: Built with TypeScript and includes type definitions
• 📊 JSON Output: Standardized JSON format compatible with Signal K and other marine data systems

Architecture

For an overview of how canboatjs integrates with signalk-server to create a complete marine data processing pipeline, see the Architecture Diagram.

The diagram illustrates:

• Data Flow: From NMEA 2000 hardware through parsing and conversion to Signal K format
• Device Support: Various hardware interfaces and data formats
• Bidirectional Processing: Both incoming data parsing and outgoing data generation
• Integration Points: How canboatjs works with other components in the marine data ecosystem

Installation

For Command Line Usage

sudo npm install -g @canboat/canboatjs

For Node.js Projects

npm install @canboat/canboatjs

Requirements

• Node.js: Version 20 or higher
• Optional Dependencies:
  • serialport: For serial device communication
  • socketcan: For direct CAN bus access on Linux

Quick Start

Basic Message Parsing

const { FromPgn } = require('@canboat/canboatjs')

// Create parser instance
const parser = new FromPgn()

// Handle warnings
parser.on('warning', (pgn, warning) => {
  console.log(`[WARNING] PGN ${pgn.pgn}: ${warning}`)
})

// Parse an Actisense format message
const message = "2017-03-13T01:00:00.146Z,2,127245,204,255,8,fc,f8,ff,7f,ff,7f,ff,ff"
const json = parser.parseString(message)

if (json) {
  console.log('Parsed PGN:', JSON.stringify(json, null, 2))
}

Generate N2K Messages

const { pgnToActisenseSerialFormat } = require('@canboat/canboatjs')

// Create a rudder position message
const message = {
  pgn: 127245,
  prio: 2,
  src: 204,
  dst: 255,
  fields: {
    'Instance': 252,
    'Direction Order': 0,
    'Reserved1': '62'
  }
}

const actisenseString = pgnToActisenseSerialFormat(message)
console.log('Generated:', actisenseString)

Supported Devices

NMEA 2000 Gateways

• Actisense NGT-1 & W2K-1 - USB and WiFi NMEA 2000 gateways
• Digital Yacht iKonvert - Serial to NMEA 2000 converter
• Yacht Devices YDWG-02 & YDEN-02 - WiFi and Ethernet gateways
• Shipmodul MiniPlex-3-N2K - Multi-protocol marine data multiplexer

CAN Bus Interfaces

• SocketCAN devices - Direct Linux CAN bus interface
• Various CAN adapters - Hardware CAN interfaces compatible with SocketCAN

Supported Data Formats

• Actisense Serial Format - Standard Actisense ASCII format
• iKonvert Format - Digital Yacht proprietary format
• YDWG Raw Format - Yacht Devices raw binary format
• PCDIN Format - Chetco Digital Instruments format
• MXPGN Format - MiniPlex-3 format
• SocketCAN - Linux CAN bus native format

Command Line Tools

Canboatjs includes several powerful command-line utilities:

analyzerjs - Message Analysis

Convert various N2K formats to standardized JSON:

# From Actisense NGT-1
actisense-serialjs /dev/ttyUSB0 | analyzerjs

# From iKonvert
ikonvert-serial /dev/ttyUSB0 | analyzerjs

# From YDWG-02 over network
nc ydgw-ip 1475 | analyzerjs

# From W2K-1 WiFi gateway  
nc w2k-1-ip 60002 | analyzerjs

# From SocketCAN
candumpjs can0

# Filter by specific PGN numbers
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 129025  # Position updates only
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 127245  # Rudder data only

# Filter by multiple PGNs
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 129025 --pgn 127245 --pgn 129029

# Filter by source address (device that sent the message)
actisense-serialjs /dev/ttyUSB0 | analyzerjs --src 15      # From device address 15
actisense-serialjs /dev/ttyUSB0 | analyzerjs --src 127     # From device address 127

# Filter by destination address 
actisense-serialjs /dev/ttyUSB0 | analyzerjs --dst 255     # Broadcast messages only
actisense-serialjs /dev/ttyUSB0 | analyzerjs --dst 204     # Messages to device 204

# Filter by manufacturer
actisense-serialjs /dev/ttyUSB0 | analyzerjs --manufacturer "Garmin"

# Combine multiple filters
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 129025 --src 15 --dst 255

# Filter using a JavaScript expression
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 129025 --filter "pgn.fields.proprietaryId === 'Pilot Configuration'"

# Pretty print JSON output
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 129025 --pretty

# Pretty print using JavaScript output with colors
actisense-serialjs /dev/ttyUSB0 | analyzerjs --pgn 129025 --js-colors

# Process log files with filtering
analyzerjs --file my_log.txt --pgn 129025 --pgn 127245 --src 15

to-pgn - Message Generation

Convert JSON to various N2K formats:

echo '{"pgn":127245,"fields":{"Instance":0}}' | to-pgn --format=actisense

candumpjs - Direct CAN Access

Read from SocketCAN without installing can-utils:

# Basic CAN bus monitoring
candumpjs can0

# Filter by specific PGN numbers
candumpjs can0 --pgn 129025                    # Position updates only
candumpjs can0 --pgn 127245                    # Rudder data only

# Filter by multiple PGNs  
candumpjs can0 --pgn 129025 --pgn 127245 --pgn 129029

# Filter by source address (device that sent the message)
candumpjs can0 --src 15                        # From device address 15
candumpjs can0 --src 127                       # From device address 127

# Filter by destination address
candumpjs can0 --dst 255                       # Broadcast messages only
candumpjs can0 --dst 204                       # Messages to device 204

# Filter by manufacturer
candumpjs can0 --manufacturer "Garmin"

# Combine multiple filters
candumpjs can0 --pgn 129025 --src 15 --dst 255

# Output in Actisense format instead of JSON
candumpjs can0 --format actisense

# Pretty print JSON with filtering
candumpjs can0 --pgn 129025 --pretty

# Common PGN filters for navigation data
candumpjs can0 --pgn 129025 --pgn 129026 --pgn 129029  # GPS position data
candumpjs can0 --pgn 127245 --pgn 127250               # Rudder and heading
candumpjs can0 --pgn 128267 --pgn 128259               # Depth and speed

ydvr-file - YDVR File Processing

Process Yacht Devices recorder files:

ydvr-file recording.ydvr | analyzerjs

Additional Tools

• actisense-file - Process Actisense log files
• actisense-n2k-tcp - TCP server for Actisense data
• cansendjs - Send CAN messages
• ikonvert-serial - iKonvert serial interface

Message Filtering

Both analyzerjs and candumpjs support powerful filtering options to focus on specific data:

PGN Filtering

Filter by Parameter Group Number to see only specific message types:

# Navigation data
--pgn 129025    # Position, Rapid Update
--pgn 129026    # COG & SOG, Rapid Update  
--pgn 129029    # GNSS Position Data
--pgn 127250    # Vessel Heading

# Engine data
--pgn 127488    # Engine Parameters, Rapid Update
--pgn 127489    # Engine Parameters, Dynamic

# Environmental data
--pgn 128267    # Water Depth
--pgn 128259    # Speed
--pgn 130311    # Environmental Parameters

# Multiple PGNs
--pgn 129025 --pgn 129026 --pgn 127250

Source and Destination Filtering

Filter by device addresses to monitor specific devices or message types:

# Source address filtering (device that sent the message)
--src 15        # Messages from device address 15 (often a chartplotter)
--src 127       # Messages from device address 127 (often a GPS)
--src 204       # Messages from device address 204 (often an autopilot)

# Destination address filtering
--dst 255       # Broadcast messages (most common)
--dst 204       # Directed messages to device 204
--dst 15        # Directed messages to device 15

# Multiple source/destination addresses
--src 15 --src 127 --dst 255

Manufacturer Filtering

Filter by device manufacturer:

--manufacturer "Garmin"
--manufacturer "Raymarine" 
--manufacturer "Simrad"
--manufacturer "Furuno"

Practical Examples

# Monitor only GPS position data from all devices
candumpjs can0 --pgn 12902