N2K (NMEA 2000)

NMEA 2000 (N2K) protocol implementation in MAPS Messaging.

N2K is a CAN-based marine network standard. MAPS ingests raw CAN frames from a CAN transport (SocketCAN) and decodes them using N2K PGN/message definitions, optionally publishing decoded JSON to topics.

---

Features

• PGN-based decoding using N2K database definitions
• Optional external database override (falls back to bundled database)
• Topic templating for decoded message publication
• Optional JSON conversion of frames
• Forwarding of unknown PGNs/messages to a dedicated topic

---

Quick Start

Minimal configuration binding N2K decoding to a CAN transport endpoint:

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

---

Configuration (N2K)

Fields below map to N2KConfigDTO.

Field	Type	Default	Description
databasePath	string	(bundled)	Optional path to an external N2K database file. If omitted, the built-in database bundled in the server JAR is used.
topicNameTemplate	string	"/{candevice}/{pgn}/{messageName}"	Topic template used when publishing decoded N2K messages. Placeholders: {candevice}, {pgn}, {messageName}.
parseToJson	boolean	true	If true, frames are decoded and published as JSON. If false, raw binary frames are published.
unknownPacketTopic	string	"/{candevice}/unknown"	Topic used for raw frames when PGN/message type is unknown. Placeholders: {candevice}.

---

Example Configuration

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

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

---

Topic Templating

Decoded messages are published to topicNameTemplate.

Placeholders:

• {candevice}: CAN interface / logical device name (e.g. can0, can1)
• {pgn}: Parameter Group Number
• {messageName}: Resolved message name from the N2K database

Default:

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

---

Unknown Packets

If a frame cannot be decoded (unknown PGN or message definition), it is forwarded to unknownPacketTopic as a raw frame payload. This allows capture/analysis without dropping traffic.

Default:

/{candevice}/unknown

---

Operational Notes

• N2K decode rate is limited by CAN bus speed and traffic.
• 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.