N2K (NMEA 2000)

NMEA 2000 (N2K) is a CAN-based marine networking standard used to exchange structured messages between onboard systems such as navigation devices, engines, sensors, displays, and control units.

In MAPS Messaging, N2K support focuses on ingesting CAN bus traffic, decoding known PGNs/messages, and publishing them into MAPS topics so they can be routed, transformed, stored, and analysed alongside other protocols.

Features

PGN-based decoding using N2K database definitions
Built-in database support with optional external override
Optional base64-encoded embedded database definition
Topic templating for decoded message publication
Optional JSON conversion of inbound CAN frames
Forwarding of unknown PGNs/messages to a dedicated topic
Optional subscription to inbound MAPS topics carrying raw CAN/N2K traffic
Optional publication of MAVLink-tracked drones as AIS/N2K events
Configurable AIS PGN transmission enablement and intervals

Quick Start

Minimal configuration binding N2K decoding to a CAN transport endpoint:

- name: "Canbus Interface"
  url: canbus://::/
  deviceName: can1
  protocol: n2k

Configuration

Fields below map to N2KConfigDTO.

Field	Type	Default	Description
`databasePath`	string	built-in database	Optional path to an external NMEA 2000 database file. If omitted, the bundled database in the server JAR is used.
`base64EncodedDatabase`	string	none	Optional N2K XML database definition encoded as base64. Useful when embedding the definition directly in YAML or another config source.
`canBusAddress`	int	`123`	CAN bus source address used by the N2K node when transmitting frames and responding to requests. Valid range is `0` to `255`.
`topicNameTemplate`	string	`"/{candevice}/{pgn}/{messageName}"`	Topic template used when publishing decoded N2K messages.
`unknownPacketTopic`	string	`"/{candevice}/unknown"`	Topic used for raw CAN/N2K frames when the PGN or message type cannot be decoded.
`inboundTopicName`	string	none	Optional MAPS topic subscription used to receive inbound raw CAN/N2K traffic from the messaging layer instead of, or in addition to, direct CAN device input.
`parseToJson`	boolean	`true`	If `true`, frames are decoded and published as JSON. If `false`, raw binary frames are published.
`publishMavlinkDrones`	boolean	`true`	If enabled, MAVLink-tracked drone position and details may be published as AIS/N2K events.
`ais.enabled`	boolean	`true`	Enables AIS/N2K publication from tracked drone/twin state.
`ais.pgn129039.enabled`	boolean	`true`	Enables PGN `129039`, AIS Class B Position Report.
`ais.pgn129039.intervalMilliseconds`	long	`1000`	Normal transmission interval for PGN `129039`. Dynamic handlers may publish earlier when material motion changes, but not more frequently than the handler's early-publish throttle.
`ais.pgn129040.enabled`	boolean	`true`	Enables PGN `129040`, AIS Class B Extended Position Report.
`ais.pgn129040.intervalMilliseconds`	long	`2000`	Normal transmission interval for PGN `129040`.
`ais.pgn129809.enabled`	boolean	`true`	Enables PGN `129809`, AIS Class B static data part A.
`ais.pgn129809.intervalMilliseconds`	long	`60000`	Normal transmission interval for PGN `129809`.
`ais.pgn129810.enabled`	boolean	`true`	Enables PGN `129810`, AIS Class B static data part B.
`ais.pgn129810.intervalMilliseconds`	long	`60000`	Normal transmission interval for PGN `129810`.

Example Configuration

- name: "Canbus N2K Interface"
  url: canbus://0.0.0.0/
  deviceName: can1
  protocol: n2k
  auth: default

  # N2K protocol settings
  databasePath: /etc/maps/n2k/n2k-database.xml
  canBusAddress: 123
  topicNameTemplate: "/{candevice}/{pgn}/{messageName}"
  unknownPacketTopic: "/{candevice}/unknown"
  parseToJson: true
  publishMavlinkDrones: true

  ais:
    enabled: true
    pgn129039:
      enabled: true
      intervalMilliseconds: 1000
    pgn129040:
      enabled: true
      intervalMilliseconds: 2000
    pgn129809:
      enabled: true
      intervalMilliseconds: 60000
    pgn129810:
      enabled: true
      intervalMilliseconds: 60000

Example Using Embedded Database

This form is useful when you want the N2K database shipped entirely in configuration instead of as a separate file.

- name: "Canbus N2K Interface"
  url: canbus://0.0.0.0/
  deviceName: can1
  protocol: n2k

  base64EncodedDatabase: "PHhtbD4uLi48L3htbD4="
  topicNameTemplate: "/{candevice}/{pgn}/{messageName}"
  unknownPacketTopic: "/{candevice}/unknown"
  parseToJson: true

Topic Templating

Decoded messages are published to topicNameTemplate.

Supported placeholders:

{candevice}: CAN interface or logical CAN device name, for example can0 or can1
{pgn}: Parameter Group Number
{messageName}: resolved N2K message name from the active database

Default:

/{candevice}/{pgn}/{messageName}

Example:

/can1/129025/PositionRapidUpdate

Unknown Packets

If a frame cannot be decoded because the PGN or message definition is unknown, it is forwarded to unknownPacketTopic as a raw frame payload. This allows you to capture and analyse unknown traffic instead of dropping it.

Default:

/{candevice}/unknown

This is especially useful when:

integrating new marine devices
validating custom PGNs
extending the bundled N2K database
troubleshooting partial or vendor-specific implementations

Database Selection

MAPS supports multiple ways to provide N2K message definitions:

Built-in database

If neither databasePath nor base64EncodedDatabase is set, MAPS uses the bundled N2K database included with the server.

External file

Use databasePath to point to an XML database file on disk.

Example:

databasePath: /etc/maps/n2k/n2k-database.xml

Embedded base64 database

Use base64EncodedDatabase when the XML definition is embedded directly in configuration as base64 text.

This is useful for:

self-contained deployments
container images
environments where mounting separate files is inconvenient

When both are present, the deployment should treat the explicitly supplied database configuration as the active source. In practice, it is best to configure one method only so humans do not create their own archaeology layer.

Inbound Topic Bridging

inboundTopicName allows N2K processing to consume raw CAN/N2K traffic arriving through the MAPS messaging layer.

Example:

inboundTopicName: "/can1/#"

This is useful when:

CAN frames are ingested by another protocol or adapter first
replaying captured traffic through MAPS topics
bridging physical and virtual CAN sources into the same N2K decoder path

MAVLink to AIS/N2K Publication

If publishMavlinkDrones is enabled, MAPS may publish MAVLink drone position and related details as AIS/N2K events.

This is intended for scenarios where:

drone state is being bridged into marine situational awareness feeds
a unified N2K/AIS view is needed alongside native marine traffic
external marine tools expect AIS-style event output

AIS PGN Transmission Configuration

When publishMavlinkDrones and ais.enabled are enabled, MAPS can project tracked drone/twin state onto selected AIS-related NMEA 2000 PGNs.

This configuration controls which PGNs are emitted and how often. It does not define the identity or physical defaults of the drone, such as callsign, vendor ID, length, beam, nationality, or STANAG/TAK metadata. Those values belong in the Twin Manager projection configuration, where common defaults and per-twin overrides can be resolved before any protocol-specific mapper uses them.

Supported AIS PGN transmit controls:

PGN	Name	Typical role	Dynamic/static
`129039`	AIS Class B Position Report	Position, motion, and navigation update	Dynamic
`129040`	AIS Class B Extended Position Report	Extended position and vessel details	Dynamic
`129809`	AIS Class B static data part A	Static identity data	Static
`129810`	AIS Class B static data part B	Static vessel and voyage-related details	Static

Example:

ais:
  enabled: true

  pgn129039:
    enabled: true
    intervalMilliseconds: 1000

  pgn129040:
    enabled: true
    intervalMilliseconds: 2000

  pgn129809:
    enabled: true
    intervalMilliseconds: 60000

  pgn129810:
    enabled: true
    intervalMilliseconds: 60000

enabled is the only disable switch for each PGN. intervalMilliseconds controls the normal transmit cadence and must be greater than zero.

For dynamic PGNs, handlers may emit early when the drone has materially changed since the last emitted snapshot. Material motion includes changes such as position, heading, course, or speed beyond the handler thresholds. Early emission is still bounded by the handler's early-publish throttle so a moving drone does not flood the CAN/N2K queue.

Static PGNs should normally emit on their configured interval or when static identity data changes. They should not be driven by motion changes.

Configuration Boundaries

N2K configuration is deliberately limited to NMEA 2000 protocol behaviour:

N2K database selection
inbound and decoded topic mapping
JSON/raw frame publication
AIS PGN enablement and cadence

CAN bus write queueing is configured on the CAN bus transport endpoint, not here. The CAN queue controls how logical CAN/N2K messages are queued, rate-limited, dropped, or rejected before they are written to the bus.

Twin projection defaults and per-twin overrides are configured in the Twin Manager, not here. The Twin Manager is responsible for values that may be required by several external formats, including AIS/N2K, TAK, and STANAG. The N2K layer consumes the resolved projection and decides when to emit PGNs.

Operational Notes

N2K decode rate is limited by CAN bus speed and traffic volume.
If parseToJson is enabled, CPU usage scales with frame rate and decode complexity.
Use unknownPacketTopic when integrating new devices or incomplete databases to retain visibility.
canBusAddress matters when the node participates actively on the bus, not just when passively decoding traffic.
publishMavlinkDrones is MAPS-specific behaviour, not an NMEA 2000 standard capability.
AIS PGN intervals control normal transmission cadence; dynamic handlers may emit early when material motion changes.
Static AIS PGNs should not be emitted early due to drone motion.
CAN bus queueing and bus usage limits are configured on the CAN bus transport endpoint.
Drone identity and projection defaults are resolved by the Twin Manager before N2K mapping.

Features​

Quick Start​

Configuration​

Example Configuration​

Example Using Embedded Database​

Topic Templating​

Unknown Packets​

Database Selection​

Built-in database​

External file​

Embedded base64 database​

Inbound Topic Bridging​

MAVLink to AIS/N2K Publication​

AIS PGN Transmission Configuration​

Configuration Boundaries​

Operational Notes​

Features

Quick Start

Configuration

Example Configuration

Example Using Embedded Database

Topic Templating

Unknown Packets

Database Selection

Built-in database

External file

Embedded base64 database

Inbound Topic Bridging

MAVLink to AIS/N2K Publication

AIS PGN Transmission Configuration

Configuration Boundaries

Operational Notes