@canboat/canboatjs 3.0.2 → 3.2.2

package/lib/n2kDevice.ts

@@ -0,0 +1,516 @@
+/**
+ * Copyright 2025 Scott Bender (scott@scottbender.net)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  PGN,
+  PGN_60928,
+  PGN_59904,
+  PGN_126208,
+  PGN_126208_Acknowledge,
+  PGN_126208_Command,
+  PGN_126996,
+  PGN_126993,
+  PGN_59392,
+  PGN_126464,
+  PgnListFunction,
+  GroupFunction,
+  PgnErrorCode,
+  TransmissionInterval,
+  ControllerState,
+  IsoControl
+} from '@canboat/ts-pgns'
+import { EventEmitter } from 'node:events'
+import _ from 'lodash'
+import { Uint64LE } from 'int64-buffer'
+import { defaultTransmitPGNs } from './codes'
+import { toPgn } from './toPgn'
+import packageJson from '../package.json'
+import { getPersistedData, savePersistedData } from './utilities'
+import { createDebug } from './utilities'
+
+const deviceTransmitPGNs = [60928, 59904, 126996, 126464]
+
+export class N2kDevice extends EventEmitter {
+  addressClaim: any
+  productInfo: any
+  configurationInfo: any
+  options: any
+  address: number
+  cansend: boolean
+  foundConflict: boolean
+  heartbeatCounter: number
+  devices: any
+  sentAvailable: boolean
+  addressClaimDetectionTime: number
+  transmitPGNs: number[]
+  addressClaimSentAt?: number
+  addressClaimChecker?: any
+  heartbeatInterval?: any
+  debug: any
+
+  constructor(options: any, debugName: string) {
+    super()
+
+    this.options = options === undefined ? {} : options
+    this.debug = createDebug(debugName, options)
+
+    let uniqueNumber: number
+    if (options.uniqueNumber !== undefined) {
+      uniqueNumber = options.uniqueNumber
+    } else {
+      uniqueNumber = this.getPersistedData('uniqueNumber')
+      if (uniqueNumber === undefined) {
+        uniqueNumber = Math.floor(Math.random() * Math.floor(2097151))
+        this.savePersistedData('uniqueNumber', uniqueNumber)
+      }
+    }
+
+    if (options.addressClaim) {
+      this.addressClaim = options.addressClaim
+      this.addressClaim.pgn = 60928
+      this.addressClaim.dst = 255
+      this.addressClaim.prio = 6
+    } else {
+      this.addressClaim = {
+        pgn: 60928,
+        dst: 255,
+        prio: 6,
+        'Manufacturer Code': 999,
+        'Device Function': 130, // PC gateway
+        'Device Class': 25, // Inter/Intranetwork Device
+        'Device Instance Lower': 0,
+        'Device Instance Upper': 0,
+        'System Instance': 0,
+        'Industry Group': 4, // Marine
+        Reserved1: 1,
+        Reserved2: 2
+      }
+
+      this.addressClaim['Unique Number'] = uniqueNumber
+    }
+
+    const version = packageJson ? packageJson.version : '1.0'
+
+    if (options.productInfo) {
+      this.productInfo = options.productInfo
+      this.productInfo.pgn = 126996
+      this.productInfo.dst = 255
+    } else {
+      this.productInfo = {
+        pgn: 126996,
+        dst: 255,
+        'NMEA 2000 Version': 1300,
+        'Product Code': 667, // Just made up..
+        'Model ID': 'Signal K',
+        'Model Version': getModelVersion(options),
+        'Model Serial Code': uniqueNumber.toString(),
+        'Certification Level': 0,
+        'Load Equivalency': 1
+      }
+    }
+
+    this.productInfo['Software Version Code'] = version
+
+    if (options.serverVersion && options.serverUrl) {
+      this.configurationInfo = {
+        pgn: 126998,
+        dst: 255,
+        'Installation Description #1': options.serverUrl,
+        'Installation Description #2': options.serverDescription,
+        'Manufacturer Information': options.serverVersion
+      }
+    }
+
+    let address: number | undefined = undefined
+
+    address = this.getPersistedData('lastAddress')
+
+    if (address === undefined) {
+      address = _.isUndefined(options.preferredAddress)
+        ? 100
+        : options.preferredAddress
+    }
+    this.address = address!
+    this.cansend = false
+    this.foundConflict = false
+    this.heartbeatCounter = 0
+    this.devices = {}
+    this.sentAvailable = false
+    this.addressClaimDetectionTime =
+      options.addressClaimDetectionTime !== undefined
+        ? options.addressClaimDetectionTime
+        : 5000
+
+    if (!options.disableDefaultTransmitPGNs) {
+      this.transmitPGNs = _.union(deviceTransmitPGNs, defaultTransmitPGNs)
+    } else {
+      this.transmitPGNs = [...deviceTransmitPGNs]
+    }
+
+    if (this.options.transmitPGNs) {
+      this.transmitPGNs = _.union(this.transmitPGNs, this.options.transmitPGNs)
+    }
+  }
+
+  start() {
+    sendISORequest(this, 60928, 254)
+    setTimeout(() => {
+      sendAddressClaim(this)
+    }, 1000)
+  }
+
+  getPersistedData(key: string) {
+    try {
+      return getPersistedData(this.options, this.options.providerId, key)
+    } catch (err: any) {
+      this.debug('reading persisted data %o', err)
+      if (err.code !== 'ENOENT') {
+        console.error(err)
+        this.setError(err.message)
+      }
+    }
+  }
+
+  savePersistedData(key: string, value: any) {
+    try {
+      savePersistedData(this.options, this.options.providerId, key, value)
+    } catch (err: any) {
+      console.error(err)
+      this.setError(err.message)
+    }
+  }
+
+  setStatus(msg: string) {
+    if (this.options.app && this.options.app.setPluginStatus) {
+      this.options.app.setProviderStatus(this.options.providerId, msg)
+    }
+  }
+
+  setError(msg: string) {
+    if (this.options.app && this.options.app.setPluginStatus) {
+      this.options.app.setProviderError(this.options.providerId, msg)
+    }
+  }
+
+  n2kMessage(pgn: PGN) {
+    if (pgn.dst == 255 || pgn.dst == this.address) {
+      try {
+        if (pgn.pgn == 59904) {
+          handleISORequest(this, pgn)
+        } else if (pgn.pgn == 126208) {
+          handleGroupFunction(this, pgn as PGN_126208)
+        } else if (pgn.pgn == 60928) {
+          handleISOAddressClaim(this, pgn as PGN_60928)
+        } else if (pgn.pgn == 126996) {
+          handleProductInformation(this, pgn)
+        }
+      } catch (err) {
+        console.error(err)
+      }
+
+      /*
+      var handler = this.handlers[pgn.pgn.toString()]
+      if ( pgn.dst == this.address )
+        debug(`handler ${handler}`)
+      if ( _.isFunction(handler) ) {
+        debug(`got handled PGN %j  ${handled}`, pgn)
+        handler(pgn)
+      }
+      */
+    }
+  }
+
+  sendPGN(_pgn: PGN, _src: number | undefined = undefined) {}
+}
+
+function getModelVersion(options: any) {
+  if (options.app?.config?.getExternalHostname !== undefined) {
+    return `${options.app.config.ssl ? 'https' : 'http'}://${options.app.config.getExternalHostname()}:${options.app.config.getExternalPort()}`
+  } else {
+    return 'canboatjs'
+  }
+}
+
+function handleISORequest(device: N2kDevice, n2kMsg: PGN_59904) {
+  device.debug('handleISORequest %j', n2kMsg)
+
+  const PGN = Number(n2kMsg.fields.pgn)
+
+  switch (PGN) {
+    case 126996: // Product Information request
+      sendProductInformation(device)
+      break
+    case 126998: // Config Information request
+      sendConfigInformation(device)
+      break
+    case 60928: // ISO address claim request
+      device.debug('sending address claim %j', device.addressClaim)
+      device.sendPGN(device.addressClaim as PGN)
+      break
+    case 126464:
+      sendPGNList(device, n2kMsg.src!)
+      break
+    default:
+      if (!device.options.disableNAKs) {
+        device.debug(`Got unsupported ISO request for PGN ${PGN}. Sending NAK.`)
+        sendNAKAcknowledgement(device, n2kMsg.src!, PGN)
+      }
+  }
+}
+
+function handleGroupFunction(device: N2kDevice, n2kMsg: PGN_126208) {
+  device.debug('handleGroupFunction %j', n2kMsg)
+  const functionCode = n2kMsg.fields.functionCode
+  if (functionCode === 'Request') {
+    handleRequestGroupFunction(device, n2kMsg)
+  } else if (functionCode === 'Command') {
+    handleCommandGroupFunction(device, n2kMsg)
+  } else {
+    device.debug('Got unsupported Group Function PGN: %j', n2kMsg)
+  }
+
+  function handleRequestGroupFunction(device: N2kDevice, n2kMsg: PGN_126208) {
+    if (!device.options.disableNAKs) {
+      // We really don't support group function requests for any PGNs yet -> always respond with pgnErrorCode 1 = "PGN not supported"
+
+      const PGN = n2kMsg.fields.pgn
+
+      device.debug(
+        "Sending 'PGN Not Supported' Group Function response for requested PGN",
+        PGN
+      )
+
+      const acknowledgement: PGN_126208_Acknowledge = {
+        pgn: 126208,
+        dst: n2kMsg.src!,
+        fields: {
+          functionCode: GroupFunction.Acknowledge,
+          pgn: PGN,
+          pgnErrorCode: PgnErrorCode.NotSupported,
+          transmissionIntervalPriorityErrorCode:
+            TransmissionInterval.Acknowledge,
+          numberOfParameters: 0,
+          list: []
+        }
+      }
+      device.sendPGN(acknowledgement)
+    }
+  }
+
+  function handleCommandGroupFunction(
+    device: N2kDevice,
+    n2kMsg: PGN_126208_Command
+  ) {
+    if (!device.options.disableNAKs) {
+      // We really don't support group function commands for any PGNs yet -> always respond with pgnErrorCode 1 = "PGN not supported"
+
+      const PGN = n2kMsg.fields.pgn
+
+      device.debug(
+        "Sending 'PGN Not Supported' Group Function response for commanded PGN",
+        PGN
+      )
+
+      const acknowledgement: PGN_126208_Acknowledge = {
+        pgn: 126208,
+        dst: n2kMsg.src!,
+        fields: {
+          functionCode: GroupFunction.Acknowledge,
+          pgn: PGN,
+          pgnErrorCode: PgnErrorCode.NotSupported,
+          transmissionIntervalPriorityErrorCode:
+            TransmissionInterval.Acknowledge,
+          numberOfParameters: 0,
+          list: []
+        }
+      }
+      device.sendPGN(acknowledgement)
+    }
+  }
+}
+
+function handleISOAddressClaim(device: N2kDevice, n2kMsg: PGN_60928) {
+  if (n2kMsg.src != device.address) {
+    if (!device.devices[n2kMsg.src!]) {
+      device.debug(`registering device ${n2kMsg.src}`)
+      device.devices[n2kMsg.src!] = { addressClaim: n2kMsg }
+      if (device.cansend) {
+        //sendISORequest(device, 126996, undefined, n2kMsg.src)
+      }
+    }
+    return
+  }
+
+  device.debug('Checking ISO address claim. %j', n2kMsg)
+
+  const uint64ValueFromReceivedClaim = getISOAddressClaimAsUint64(n2kMsg)
+  const uint64ValueFromOurOwnClaim = getISOAddressClaimAsUint64(
+    device.addressClaim
+  )
+
+  if (uint64ValueFromOurOwnClaim < uint64ValueFromReceivedClaim) {
+    device.debug(
+      `Address conflict detected! Kept our address as ${device.address}.`
+    )
+    sendAddressClaim(device) // We have smaller address claim data -> we can keep our address -> re-claim it
+  } else if (uint64ValueFromOurOwnClaim > uint64ValueFromReceivedClaim) {
+    device.foundConflict = true
+    increaseOwnAddress(device) // We have bigger address claim data -> we have to change our address
+    device.debug(
+      `Address conflict detected!  trying address ${device.address}.`
+    )
+    sendAddressClaim(device)
+  }
+}
+
+function increaseOwnAddress(device: N2kDevice) {
+  const start = device.address
+  do {
+    device.address = (device.address + 1) % 253
+  } while (device.address != start && device.devices[device.address])
+}
+
+function handleProductInformation(device: N2kDevice, n2kMsg: PGN_126996) {
+  if (!device.devices[n2kMsg.src!]) {
+    device.devices[n2kMsg.src!] = {}
+  }
+  device.debug('got product information %j', n2kMsg)
+  device.devices[n2kMsg.src!].productInformation = n2kMsg
+}
+
+function sendHeartbeat(device: N2kDevice) {
+  device.heartbeatCounter = device.heartbeatCounter + 1
+  if (device.heartbeatCounter > 252) {
+    device.heartbeatCounter = 0
+  }
+
+  const hb: PGN_126993 = {
+    pgn: 126993,
+    dst: 255,
+    prio: 7,
+    fields: {
+      dataTransmitOffset: 60,
+      sequenceCounter: device.heartbeatCounter,
+      controller1State: ControllerState.ErrorActive
+    }
+  }
+
+  device.sendPGN(hb)
+}
+
+function sendAddressClaim(device: N2kDevice) {
+  if (device.devices[device.address]) {
+    //someone already has this address, so find a free one
+    increaseOwnAddress(device)
+  }
+  device.debug(`Sending address claim ${device.address}`)
+  device.sendPGN(device.addressClaim)
+  device.setStatus(`Claimed address ${device.address}`)
+  device.addressClaimSentAt = Date.now()
+  if (device.addressClaimChecker) {
+    clearTimeout(device.addressClaimChecker)
+  }
+
+  device.addressClaimChecker = setTimeout(() => {
+    //if ( Date.now() - device.addressClaimSentAt > 1000 ) {
+    //device.addressClaimChecker = null
+    device.debug('claimed address %d', device.address)
+
+    device.savePersistedData('lastAddress', device.address)
+
+    device.cansend = true
+    if (!device.sentAvailable) {
+      if (device.options.app) {
+        device.options.app.emit('nmea2000OutAvailable')
+      }
+      device.emit('nmea2000OutAvailable')
+      device.sentAvailable = true
+    }
+    sendISORequest(device, 126996)
+    if (!device.heartbeatInterval) {
+      device.heartbeatInterval = setInterval(() => {
+        sendHeartbeat(device)
+      }, 60 * 1000)
+    }
+    //}
+  }, device.addressClaimDetectionTime)
+}
+
+function sendISORequest(
+  device: N2kDevice,
+  pgn: number,
+  src: number | undefined = undefined,
+  dst = 255
+) {
+  device.debug(`Sending iso request for ${pgn} to ${dst}`)
+
+  const isoRequest: PGN_59904 = {
+    pgn: 59904,
+    dst: dst,
+    fields: {
+      pgn
+    }
+  }
+  device.sendPGN(isoRequest, src)
+}
+
+function sendProductInformation(device: N2kDevice) {
+  device.debug('Sending product info %j', device.productInfo)
+
+  device.sendPGN(device.productInfo)
+}
+
+function sendConfigInformation(device: N2kDevice) {
+  if (device.configurationInfo) {
+    device.debug('Sending config info..')
+    device.sendPGN(device.configurationInfo)
+  }
+}
+
+function sendNAKAcknowledgement(
+  device: N2kDevice,
+  src: number,
+  requestedPGN: number
+) {
+  const acknowledgement: PGN_59392 = {
+    pgn: 59392,
+    dst: src,
+    fields: {
+      control: IsoControl.Ack,
+      groupFunction: 255,
+      pgn: requestedPGN
+    }
+  }
+  device.sendPGN(acknowledgement)
+}
+
+function sendPGNList(device: N2kDevice, dst: number) {
+  //FIXME: for now, adding everything that signalk-to-nmea2000 supports
+  //need a way for plugins, etc. to register the pgns they provide
+  const pgnList: PGN_126464 = {
+    pgn: 126464,
+    dst,
+    fields: {
+      functionCode: PgnListFunction.TransmitPgnList,
+      list: device.transmitPGNs
+    }
+  }
+  device.sendPGN(pgnList)
+}
+
+function getISOAddressClaimAsUint64(pgn: any) {
+  return new Uint64LE(toPgn(pgn)!)
+}

package/lib/pgns.test.ts

@@ -0,0 +1,12 @@
+import { getPgn } from './pgns'
+
+describe('getPgn', () => {
+  test('Return info array about a pgn number', () => {
+    const pgns = getPgn(60928)
+    expect(pgns !== undefined)
+    if (pgns !== undefined) {
+      expect(pgns.length > 0)
+      expect(pgns[0].Description).toBe('ISO Address Claim')
+    }
+  })
+})

package/lib/pgns.ts

@@ -0,0 +1,191 @@
+import {
+  getPGN,
+  EnumBase,
+  Enumeration,
+  BitEnumeration,
+  FieldTypeEnumeration,
+  getEnumerations,
+  getFieldTypeEnumerations,
+  getBitEnumerations
+} from '@canboat/ts-pgns'
+import _ from 'lodash'
+import { createDebug } from './utilities'
+
+const debug = createDebug('canboatjs:pgns')
+
+//const enumValues : {[key:string]: {[key:number]: string}} = {}
+//const enumNames : {[key:string]: {[key:string]: number}} = {}
+
+const enumValues: any = {}
+const enumNames: any = {}
+
+function getEnumeration(name: string) {
+  const enumeration: Enumeration = lookupEnumerations[name] as Enumeration
+  if (enumeration) {
+    let vmap: any = enumValues[name]
+    if (!vmap) {
+      vmap = {}
+      enumValues[name] = vmap
+      enumeration.EnumValues.forEach((enumPair) => {
+        vmap[enumPair.Value] = enumPair.Name
+      })
+
+      const nmap: any = {}
+      enumNames[name] = nmap
+      enumeration.EnumValues.forEach((enumPair) => {
+        nmap[enumPair.Name] = enumPair.Value
+      })
+    }
+  }
+  return enumeration
+}
+
+const ftEnumValues: any = {}
+const ftEnumNames: any = {}
+const ftEnumBits: any = {}
+
+function getFieldTypeEnumeration(name: string) {
+  const enumeration = lookupFieldTypeEnumerations[name] as FieldTypeEnumeration
+  if (enumeration) {
+    let vmap = ftEnumValues[name]
+    if (!vmap) {
+      vmap = {}
+      ftEnumValues[name] = vmap
+      enumeration.EnumFieldTypeValues.forEach((enumPair) => {
+        vmap[enumPair.value] = enumPair.name
+      })
+
+      const nmap: any = {}
+      ftEnumNames[name] = nmap
+      enumeration.EnumFieldTypeValues.forEach((enumPair) => {
+        nmap[enumPair.name] = enumPair.value
+      })
+
+      const bmap: any = {}
+      ftEnumBits[name] = bmap
+      enumeration.EnumFieldTypeValues.forEach((enumPair) => {
+        bmap[enumPair.value] = Number(enumPair.Bits)
+      })
+    }
+  }
+  return enumeration
+}
+
+const bEnumValues: any = {}
+const bEnumNames: any = {}
+
+function getBitEnumeration(name: string) {
+  const enumeration = lookupBitEnumerations[name] as BitEnumeration
+  if (enumeration) {
+    let nmap = bEnumNames[name]
+    if (!nmap) {
+      nmap = {}
+      bEnumNames[name] = nmap
+      enumeration.EnumBitValues.forEach((enumPair) => {
+        nmap[enumPair.Bit] = enumPair.Name
+      })
+
+      const vmap: any = {}
+      bEnumValues[name] = vmap
+      enumeration.EnumBitValues.forEach((enumPair) => {
+        vmap[enumPair.Name] = Number(enumPair.Bit)
+      })
+    }
+  }
+  return enumeration
+}
+
+export function lookupEnumerationName(enumName: string, value: number) {
+  const enumeration = getEnumeration(enumName)
+  return enumeration && enumValues[enumName][value]
+}
+
+export function lookupEnumerationValue(enumName: string, name: string) {
+  const enumeration = getEnumeration(enumName)
+  return enumeration && enumNames[enumName][name]
+}
+
+export function lookupFieldTypeEnumerationName(
+  enumName: string,
+  value: number
+) {
+  const enumeration = getFieldTypeEnumeration(enumName)
+  return enumeration && ftEnumValues[enumName][value]
+}
+
+export function lookupFieldTypeEnumerationBits(
+  enumName: string,
+  value: number
+) {
+  const enumeration = getFieldTypeEnumeration(enumName)
+  return enumeration && ftEnumBits[enumName][value]
+}
+
+export function lookupFieldTypeEnumerationValue(
+  enumName: string,
+  name: string
+) {
+  const enumeration = getFieldTypeEnumeration(enumName)
+  return enumeration && ftEnumNames[enumName][name]
+}
+
+export function lookupBitEnumerationName(enumName: string, value: number) {
+  const enumeration = getBitEnumeration(enumName)
+  return enumeration && bEnumNames[enumName][value]
+}
+
+export function lookupBitEnumerationValue(enumName: string, name: number) {
+  const enumeration = getBitEnumeration(enumName)
+  return enumeration && bEnumValues[enumName][name]
+}
+
+function organizeEnumerations(enums: EnumBase[]): { [key: string]: EnumBase } {
+  const map: any = {}
+  enums.forEach((e) => {
+    map[e.Name] = e
+  })
+  return map
+}
+
+export const lookupEnumerations = organizeEnumerations(getEnumerations())
+export const lookupFieldTypeEnumerations = organizeEnumerations(
+  getFieldTypeEnumerations()
+)
+export const lookupBitEnumerations = organizeEnumerations(getBitEnumerations())
+export const getPgn = getPGN
+export const customPgns: any = {}
+
+export const addCustomPgns = (pgns: any, setter: any) => {
+  pgns.PGNs.forEach((pgn: any) => {
+    if (!customPgns[pgn.PGN]) {
+      customPgns[pgn.PGN] = {
+        definitions: [],
+        callbacks: []
+      }
+    }
+
+    customPgns[pgn.PGN].definitions.push(pgn)
+
+    /*
+      if ( pgn.calllback ) {
+      customPgns[pgn.PGN].callbacks.push()
+      }
+    */
+
+    debug('registered custom pgn %d by %s', pgn.PGN, setter)
+  })
+
+  if (pgns.LookupEnumerations) {
+    pgns.LookupEnumerations.forEach((e: any) => {
+      if (!lookupEnumerations[e.Name]) {
+        lookupEnumerations[e.Name] = e
+      } else {
+        debug(`enumeration ${e.Name} already exists`)
+      }
+    })
+  }
+}
+
+export const getCustomPgn = (pgnNum: number) => {
+  return customPgns[pgnNum]
+}