n2k

n2k

n2k is a standalone Go library for NMEA 2000 (N2K) — the CAN-based network that connects marine instruments (GPS, depth, wind, engine, autopilot) on boats. It reads, writes, filters, and replays bus traffic from CAN hardware, USB-CAN adapters, WiFi gateways, and capture files, decoding messages into strongly typed Go structs while preserving byte-exact wire payloads for re-encoding.

It is the Go foundation for NMEA 2000 software — the bus toolkit itself, not a plugin or companion layer for another app. Use it directly in telemetry collectors, loggers, gateways, test rigs, monitoring services, automation, and any Go program that needs to understand or participate on an N2K bus.

Why n2k

• ~600 typed PGN message types. A PGN (Parameter Group Number) is NMEA 2000's message-type identifier; n2k decodes ~600 of them into Go structs (348 distinct numbers, including manufacturer-proprietary variants), generated from the community-maintained canboat schema — the reference database for open NMEA 2000 decoding. Every numeric field with a physical interpretation gets a generated SI-unit accessor (heading.HeadingValue() → radians) over raw wire ticks. Generated coverage is not completeness: the manifest separately reports decode/encode limitations and hardware evidence.
• Wire-faithful re-encode. An unchanged decoded message retains its exact original payload, including reserved and trailing bytes. Mutating a field switches encoding to the current struct values, so edits are never silently discarded.
• A real bus node, not just a decoder. NewClient claims an address per ISO 11783, heartbeats, answers product/configuration info and ISO requests, accepts Commanded Address assignments, and handles NMEA group functions (transmit / retime / pause) — the protocol behavior NMEA 2000 requires of a transmitting device, handled for you.
• Pure Go, CGO-free, cross-compiles to Linux, macOS, and Windows.

Quick Start — No Boat Required

The repo bundles a real six-second capture from a sailing vessel (testdata/sample.log), so this program runs as-is at a desk:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/open-ships/n2k"
	"github.com/open-ships/n2k/pgn"
)

func main() {
	ctx := context.Background()

	for msg, err := range n2k.Receive(ctx, n2k.File("testdata/sample.log")) {
		if err != nil {
			log.Fatal(err)
		}
		if heading, ok := msg.(*pgn.VesselHeading); ok {
			if rad, present := heading.HeadingValue(); present {
				fmt.Printf("heading: %.4f rad\n", rad)
			}
		}
	}
}

On a boat, only the source option changes:

n2k.CAN("can0")                            // SocketCAN (Linux)
n2k.USB("/dev/ttyUSB0")                    // USB-CAN serial adapter
n2k.YachtDevicesTCP("192.168.4.1:1457")    // Yacht Devices WiFi gateway
n2k.YachtDevicesUDP(":1457")               // same gateway, UDP broadcast
n2k.ActisenseTCP("10.0.0.5:2000")          // role-aware Actisense TCP
n2k.ActisenseSerial("/dev/cu.usbserial-1234") // direct NGT/NGX

The TCP/UDP sources mean you can develop on your laptop against your boat's WiFi gateway — no CAN interface, no Linux, no cross-compiling until you deploy. TCP works for the write path too: NewClient over a Yacht Devices gateway in RAW mode is a full bus node, address claiming included, over the WiFi gateway.

Add it to your project

go get github.com/open-ships/n2k

For command-line capture and diagnostics, install open-ships/n2k-cli.

VERSION declares the exact version published by the next successful main build. The project remains on the github.com/open-ships/n2k v1 module path while its public API is known to be in flux; minor releases may deliberately refine or replace contracts such as the Actisense gateway/Client boundary. Pin the minor version when stability is required. Fully green release automation publishes an annotated tag, deterministic source archive, checksums, SBOM, and separate build-provenance and SBOM attestations through the shared Open Ships release policy.

Using n2k

Everything the library does, mapped to its API:

Reading and Writing

Client provides read and write access to NMEA 2000. Use it when you need to transmit messages in addition to receiving them.

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

client, err := n2k.NewClient(ctx,
    n2k.CAN("can0"), // auto-claims an available address
)
if err != nil {
    panic(err)
}
defer client.Close()

// Write a message. The struct knows its own PGN number.
// Priority defaults to 6, destination defaults to broadcast (255).
heading := &pgn.VesselHeading{}
if err := heading.SetHeadingValue(1.5708); err != nil { // radians
    panic(err)
}
result := client.Write(heading)
if err := result.WaitContext(ctx); err != nil {
    log.Printf("write failed: %v", err)
}

// Explicitly set priority. VesselHeading is a broadcast (PDU2) PGN, so it
// cannot carry a destination address.
heading2 := &pgn.VesselHeading{
    Info: pgn.MessageInfo{Priority: pgn.Priority(2)},
}
if err := heading2.SetHeadingValue(1.5708); err != nil { ... }
if err := client.Write(heading2).WaitContext(ctx); err != nil { ... }

// Addressed PGNs use TargetId. ISO Request is a PDU1 PGN.
requested := uint64(126996)
request := &pgn.IsoRequest{
    Info: pgn.MessageInfo{TargetId: pgn.Target(42)},
    Pgn:  &requested,
}
if err := client.Write(request).WaitContext(ctx); err != nil { ... }

// Read messages (same as top-level API)
for msg, err := range client.Receive() {
    if err != nil {
        panic(err)
    }
    fmt.Printf("Msg: %v\n", msg)
}

Write, WriteContext, SendPGN, and pgn.EncodeMessage accept pgn.Message values but require the concrete value to implement pgn.PGN. Generated message pointers implement both. Nil values and read-only pgn.UnknownPGN values return errors. Outgoing messages are copied at write admission; do not mutate a message during the call.

Address Claiming

Every device that transmits on NMEA 2000 must claim a unique bus address (0–251) using the ISO 11783 address claim protocol (PGN 60928). NewClient handles this automatically — it broadcasts an address claim, waits for contention, and only returns once a valid address is secured.

How contention works: Each device has a 64-bit NAME. When two devices claim the same address, the lower NAME wins and keeps the address; the loser must yield. The client supports two modes:

// Auto mode (default) — starts at address 251 and negotiates downward on
// contention. If all addresses are exhausted, NewClient returns an error.
client, err := n2k.NewClient(ctx, n2k.CAN("can0"))

// Explicit mode — uses a fixed address. If another device with a lower NAME
// contests it, NewClient returns an error instead of retrying.
client, err := n2k.NewClient(ctx,
    n2k.CAN("can0"),
    n2k.WithSourceAddress(42),
)

Device NAME: The NAME determines who wins contention. Lower NAME = higher priority. Customize it to control your device's identity and arbitration priority on the bus:

client, err := n2k.NewClient(ctx,
    n2k.CAN("can0"),
    n2k.WithName(n2k.DeviceName{
        IndustryGroup:    4,     // 3 bits: 4 = Marine
        ManufacturerCode: 123,   // 11 bits: replace with your assigned code
        DeviceClass:      25,    // 7 bits: 25 = Internetwork Device
        DeviceFunction:   130,   // 8 bits: 130 = PC Gateway
        DeviceInstance:   0,     // 8 bits
        SystemInstance:   0,     // 4 bits
        IdentityNumber:   12345, // 21 bits: unique per physical device
    }),
)

When WithName is not set, DefaultDeviceName() is used. That development default randomizes the identity number so multiple local processes can coexist on one bus. Production devices must provide their assigned manufacturer code and a stable, persisted identity with WithName; a random identity is not a provisioned product identity.

Persist the last claimed address and offer it on the next start; the client will try it first and move if it is occupied:

client, err := n2k.NewClient(ctx,
    n2k.CAN("can0"),
    n2k.WithPreferredAddress(loadLastAddress()),
)
// Save client.Status().Address after claiming or during orderly shutdown.

The client also handles Commanded Address (PGN 65240) without application code. It accepts only an exact nine-byte broadcast ISO transport (BAM) transfer whose full 64-bit NAME matches the client and whose requested address is 0–251. A valid change immediately emits a new Address Claim and places application writes behind a fresh contention window. Mismatched NAMEs, fast-packet or addressed lookalikes, malformed lengths, special addresses, and commands for the current address have no effect. Observe moves through client.Status().Address; user filters and unread subscriptions cannot disable this protocol behavior.

Claim timeout: NewClient blocks for up to 1500ms (the default) to allow the network to respond to the initial claim. On heavily contested buses, increase it:

client, err := n2k.NewClient(ctx,
    n2k.CAN("can0"),
    n2k.WithClaimTimeout(3 * time.Second),
)

Read-only

Receive and NewScanner decode single frames, fast packets, and complete ISO transport captures from every frame source. Passive ISO assembly accepts BAM and addressed transfers with an announcement and all DT frames in order; it does not send CTS or acknowledgments and does not require peer CTS records in the capture. Missing or expired transfers are discarded. Assembly precedes PGN filtering, so Filter("pgn == 65240") can select a transported message. Without a filter, the individual TP control/data messages remain visible too.

WithBus is for NewClient. To read a custom bus, use client.Receive(), client.Scanner(), or client.Observations(); standalone readers reject it. Standalone scanners and iterators own their sources. Scanner.Close and an early loop exit wait for source cleanup. Call Next, Message, and Err from one goroutine; Close may run concurrently to stop a blocked Next.

Iterator API

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

for msg, err := range n2k.Receive(ctx, n2k.CAN("can0")) {
    if err != nil {
        panic(err)
    }
    fmt.Printf("Msg: %v\n", msg)
}

Scanner API

s := n2k.NewScanner(ctx, n2k.CAN("can0"))
defer s.Close()
for s.Next() {
    fmt.Printf("Msg: %v\n", s.Message())
}
if err := s.Err(); err != nil {
    ...
}

Raw observations

Use Observe when typed decoding would discard context needed by a recorder, bridge, latency monitor, or multi-network diagnostic:

for observation, err := range n2k.Observe(ctx, n2k.File("capture.log")) {
    if err != nil {
        return err
    }
    fmt.Println(observation.AdapterID, observation.NetworkID,
        observation.Timestamp, observation.Direction, observation.Frame)
}

client.Observations() additionally publishes assembled-message, decode-error, gateway, and transport-error events. Every record owns its frame and payload bytes. A slow subscriber ends with ErrObservationOverflow without delaying address claims, ISO responses, decoding, or other subscribers. pgn.MessageInfo carries the same timing, Adapter, network, and direction context into typed messages.

Multiple Networks

Read from multiple CAN interfaces simultaneously:

for msg, err := range n2k.Receive(ctx,
    n2k.CAN("can0"),
    n2k.CAN("can1"),
    n2k.USB("/dev/ttyUSB0"),
) {
    // messages from all sources, interleaved by arrival
}

Log Files and Network Gateways

Frames don't have to come from local CAN hardware:

// Replay a candump -L / -l capture, as fast as possible...
for msg, err := range n2k.Receive(ctx, n2k.File("testdata/sample.log")) { ... }

// ...or paced by the log's own timestamps.
for msg, err := range n2k.Receive(ctx, n2k.File("capture.log", n2k.OriginalTiming())) { ... }

// Replay an Actisense EBL capture (raw BDTP or BSTRawFrame records).
for msg, err := range n2k.Receive(ctx, n2k.EBL("capture.ebl", n2k.OriginalTiming())) { ... }

// Yacht Devices YDWG-02 (RAW server mode) over TCP or UDP.
for msg, err := range n2k.Receive(ctx, n2k.YachtDevicesTCP("192.168.4.1:1457")) { ... }
for msg, err := range n2k.Receive(ctx, n2k.YachtDevicesUDP(":1457")) { ... }

// Actisense-format streams (W2K-1 gateways, or an NGT-1 behind a TCP
// bridge). Read-only use passively accepts all supported BST records.
for msg, err := range n2k.Receive(ctx, n2k.ActisenseTCP("10.0.0.5:2000")) { ... }

// Direct NGT/NGX serial connection; defaults to 115200 8N1.
for msg, err := range n2k.Receive(ctx, n2k.ActisenseSerial("/dev/cu.usbserial-1234")) { ... }

File, EBL, and UDP are read-only (use them with Receive/NewScanner). TCP and Serial also work with NewClient:

// A complete bus device over the boat's WiFi gateway. RAW mode is
// frame-level in both directions, so address claiming, heartbeats, and
// group functions behave exactly as on CAN hardware. The gateway echoes
// transmitted frames back, so the client also observes its own traffic.
client, err := n2k.NewClient(ctx, n2k.YachtDevicesTCP("192.168.4.1:1457"))

// Preferred Actisense Client path. The dedicated constructors query the prior
// mode, set and acknowledge mode 5, then exchange source-authoritative BST-95
// frames. A gateway that rejects or strips BEM setup fails explicitly; there
// is no automatic fallback to gateway-owned writes.
client, err := n2k.NewClient(ctx, n2k.ActisenseTCP("10.0.0.5:2000"))
client, err := n2k.NewClient(ctx, n2k.ActisenseSerial("/dev/cu.usbserial-1234"))

// Gateway-owned BST-94 transmission is a separate session because the wire
// format has no source-address field. It never runs a virtual address claim.
session, err := n2k.NewActisenseTCPSession(ctx, "10.0.0.5:2000")
err = session.SendRawPGN(ctx, 126992, 3, 255, payload)

// Explicit raw selection also remains available.
client, err := n2k.NewClient(ctx,
    n2k.TCP("10.0.0.5:2000", n2k.FormatActisenseRaw))

TCP, UDP, and Serial remain the explicit-format layer for compatible hardware, unusual gateway modes, and callers that need to select a particular Actisense representation. The device-aware constructors above are the recommended defaults.

Source support by platform

Actisense sessions and device control

BST-94 does not carry a source address, so the library never exposes it as a Client Bus. Use a gateway session for assembled sends and local control:

session, err := n2k.NewActisenseTCPSession(ctx, "10.0.0.5:2000")
if err != nil { ... }
defer session.Close()

product, err := session.GetProductInfo(ctx)
diagnostics := session.Diagnostics()
status := session.Status()

The session exposes the complete compiled NMEA 2000 BEM command set, including product/CAN/port information, Rx/Tx PGN controls, multi-reply lists, explicit commit/reinitialize methods, EBL wire trace, and cumulative metrics. Sends do not mutate Tx lists. ConfigureTransmitPGNs provides an explicit batched, rollback-capable volatile transaction. Transactions serialize and retain the original settings before sending changes. Cancellation still permits one command-timeout window for same-connection rollback; errors include any restoration failure. Check session.Close() as well: it cancels active configuration and retries restoration on the same connection epoch. A lost connection prevents restoration through a later epoch. Direct Tx-list BEM commands must not run concurrently with a transaction.

Both a gateway session and a source-authoritative Client expose the same typed commands for remote Actisense devices through addressed PGN 126720:

remote, err := session.ActisenseRemoteDevice(35) // also available on Client
product, err := remote.GetProductInfo(ctx)

WithActisensePreserveOperatingMode() opens a control session without changing the current mode. SendBST and SendRaw provide the SDK's generic send paths. The supported scope is the published NMEA 2000/binary SDK interface, excluding NMEA 0183 and !PARLB. This is not an Actisense endorsement or a claim that every hardware model and firmware has been verified.

See Actisense NMEA 2000 support for the command ledger, serial settings, persistence rules, formats, model caveats, and parity evidence.

Filter Messages using Common Expression Language

Filter messages using CEL expressions.

n2k automatically optimizes filters — metadata-only expressions skip decoding entirely.

// Only vessel heading messages
for msg, err := range n2k.Receive(ctx,
    n2k.CAN("can0"),
    n2k.Filter("pgn == 127250"),
) { ... }

// Filter on decoded fields -- decoded numeric fields hold raw wire ticks,
// not physical units (see "Physical Values" below); Heading is in
// 0.0001-radian ticks, so 31416 here is > pi rad.
for msg, err := range n2k.Receive(ctx,
    n2k.CAN("can0"),
    n2k.Filter("pgn == 127250 && msg.Heading > 31416"),
) { ... }

// Filter by source address
for msg, err := range n2k.Receive(ctx,
    n2k.CAN("can0"),
    n2k.Filter("source == 3"),
) { ... }

Filter variables:

Repeating-group slice fields (Repeating1/Repeating2) are not addressable in filter expressions.

Options

Errors, backpressure, and health

Runtime failure is surfaced through the API. An unrecoverable bus failure ends live iterators/scanners with that error, causes later writes to fail, and appears in Client.Err() and Client.Status(). With automatic reconnect, a temporary disconnect invalidates old requests and writes with ErrEpochChanged. New writes fail with ErrNotReady until address claiming completes; they are never carried into the next connection silently.

An Actisense operating-mode failure is available to errors.As without losing the underlying timeout or device error. This lets an application deliberately offer a legacy configuration instead of receiving a silent downgrade:

var modeErr *n2k.ActisenseModeError
if errors.As(err, &modeErr) && modeErr.RequestedMode == 5 {
    // Raw Client semantics are unavailable; choose a gateway session only if
    // the application can accept the physical gateway's source identity.
}

Queues are deliberately bounded:

• Write snapshots the payload and header before returning, then admits without waiting for queue space. When full, the result reports ErrWriteQueueFull. You can reuse the message after return; do not mutate it during the call.
• Each live Receive or Scanner call has an independent subscription. A slow subscription ends with ErrReceiveOverflow; it cannot stall address claiming, transport handling, or another reader.
• Each raw observation subscription is independently bounded and ends with ErrObservationOverflow when slow.
• Required automatic protocol traffic uses a dedicated priority queue. Queue, encoding, and transport failures become terminal state instead of logs.
• ISO request correlation is capped at 64 (ErrRequestQueueFull). Close, terminal failure, disconnect, and address change promptly invalidate waiters.
• Replay WrittenFrames() retains the newest 4096 frames; status exposes retained capacity and evictions. Each typed subscriber and registry snapshot owns independent message fields and metadata.

Use WriteContext(ctx, msg) to cancel queued or in-progress transmission. WaitContext cancels only the wait, not the write. Errors after a physical attempt may describe a partial transfer: inspect *WriteError's CompletedRecords and TransmissionUncertain before choosing whether to retry. Successful transmission is not proof of remote application acceptance.

Tune bounds with WithWriteQueue / WithReceiveBuffer, and expose Status() from health or metrics endpoints:

status := client.Status()
fmt.Println(status.Address, status.AddressClaimed, status.Connected,
    status.Ready, status.ConnectionEpoch, status.ClaimEpoch, status.WriteQueueDepth,
    status.ProtocolRequiredQueueDepth, status.ReceiveSubscribers,
    status.ObservationSubscribers, status.TerminalError)

Custom transports

WithBus is the NewClient extension seam for hardware and gateways not included here. Implement Bus for frame-level read/write access. Optionally implement ObservationBus to retain transport context, ReadyBus when opening is asynchronous, ConnectionLifecycleBus for reconnect epochs, and MessageWriter when a transport accepts assembled PGN payloads while honoring the exact source identity. Gateway-owned source substitution is not a Bus. Expose ContextBus/ContextMessageWriter for cancellable writes; otherwise Client closes the bus to interrupt canceled I/O. Bus.Close must interrupt blocked reads/writes and return promptly. The client waits for its workers.

A Complete Bus Node

Beyond claiming an address, a bus client implements the protocol behavior NMEA 2000 requires of a transmitting device:

• Heartbeat (PGN 126993) — sent every 60 seconds automatically (tune or disable with WithHeartbeatInterval).
• Product & configuration info (PGNs 126996/126998) — requests from other devices (chartplotters, analyzers) are answered automatically. Set your identity with WithProductInfo / WithConfigInfo; without them a generic software-gateway identity is reported so the device never shows up blank.
• ISO requests (PGN 59904) — requests for supported PGNs are answered; requests addressed to us for anything else are refused with an ISO acknowledgement NAK, per ISO 11783-3.
• Commanded Address (PGN 65240) — a matching nine-byte BAM assignment moves the node to a claimable address, immediately reclaims it, and opens a fresh contention window. Malformed and non-target commands are ignored.
• Group functions (PGN 126208) — request group functions can transmit, retime, pause (interval 0), or restore (interval 0xFFFFFFFE) any PGN the client transmits, including scheduled broadcasts. Unsupported group functions (commands, read/write fields) are acknowledged with the proper error codes.

All of this runs on a dedicated decode path, so a Filter(...) expression never breaks protocol behavior.

Request/response — ask another device for a PGN and await its typed reply (default timeout 1250ms, the ISO 11783 response time):

pi, err := n2k.Request[*pgn.ProductInformation](ctx, client, 0x23)
if err == nil {
    fmt.Println(pi.ModelId, pi.SoftwareVersionCode)
}

Periodic broadcasts — transmit a PGN on a schedule; the provider runs on every tick (return nil to skip a tick). Prefer BroadcastPGN, which registers the PGN immediately for deterministic replacement and group-function retiming:

stop, err := client.BroadcastPGN(127250, time.Second, func(ctx context.Context) pgn.Message {
    heading := &pgn.VesselHeading{}
    if err := heading.SetHeadingValue(currentHeadingRadians()); err != nil {
        log.Printf("invalid heading: %v", err)
        return nil // skip this tick
    }
    return heading
})
if err != nil {
    log.Fatal(err)
}
defer stop()

Other devices can retime or pause the broadcast with a request group function naming its PGN. Each provider runs on one owned schedule worker and must return promptly when its context is canceled. Pass that context through to sensor reads and other blocking work. Stop and Close cancel providers and wait for them to exit, so a provider must not call its own stop function or Close. Periodic provider panics are contained.

At most 64 schedule workers may be alive; admission returns ErrBroadcastLimit when full. Required group-function responses use a bounded queue on the same worker. Saturation is observable through Client.Err as ErrBroadcastQueueFull.

Device Registry

Bus clients passively map the network: every address claim, product info, and configuration info message updates a registry keyed by 64-bit NAME (addresses are dynamic — the NAME is the stable identity). On first sight of a device the client requests its product and configuration info, and at startup it broadcasts an address-claim request so the whole bus announces itself.

for _, d := range client.Devices() {
    model := "(no product info yet)"
    if d.ProductInfo != nil {
        model = d.ProductInfo.ModelId
    }
    fmt.Printf("addr %d: %s (manufacturer %d, last seen %s)\n",
        d.Address, model, d.Name.ManufacturerCode, d.LastSeen)
}

// Correlate a decoded message with the device that sent it.
if vh, ok := msg.(*pgn.VesselHeading); ok {
    if dev, found := client.DeviceAt(vh.Info.SourceId); found {
        fmt.Printf("heading from %016X\n", dev.RawName)
    }
}

Testing with Replay

frames := []can.Frame{
    {ID: 0x09F10D01, Length: 8, Data: [8]uint8{1, 2, 3, 4, 5, 6, 7, 8}},
}

for msg, err := range n2k.Receive(ctx, n2k.Replay(frames)) {
    // test your message handling
}

PGN Types

All decoded messages implement the pgn.Message interface and are pointers to typed structs in the pgn package. Use a type switch to handle specific message types. PGN structs are organized across category files — system.go, navigation.go, engine.go, etc.

type Message interface {
    PGNNumber() uint32
}

Every struct carries a pgn.MessageInfo field with wire metadata:

type MessageInfo struct {
    Timestamp time.Time
    Priority  *uint8
    PGN       uint32
    SourceId  uint8
    TargetId  *uint8
}

When writing, Priority and TargetId default to 6 and 255 respectively when nil. When reading, they are populated from the wire. Use the helpers pgn.Priority(v) and pgn.Target(v) for concise literal construction:

info := pgn.MessageInfo{
    PGN:      126996,
    SourceId:  3,
    Priority: pgn.Priority(2),
    TargetId: pgn.Target(42),
}

Physical Values

Numeric struct fields hold raw wire ticks (*uint64/*int64). Exact round trips are preserved by an owned original-payload snapshot; raw ticks make field edits precise and predictable. Every numeric field with a physical interpretation also gets generated typed accessors that do the unit math — SI units in, SI units out, raw ticks underneath:

heading := &pgn.VesselHeading{}
if err := heading.SetHeadingValue(1.5708); err != nil { // 15708 raw ticks
    return err
}

rad, ok := heading.HeadingValue()    // 1.5708, true
_ = heading.Heading                  // *uint64 raw ticks, still there

depth := decoded.(*pgn.WaterDepth)
meters, ok := depth.DepthValue()     // e.g. 2.70 m from raw 270

The accessor's bool is false for absent, sentinel, or out-of-range measurements. A setter rounds to the nearest wire tick and returns an error wrapping pgn.ErrInvalidPhysicalValue if the input is NaN, infinite, outside the physical or integer range, or rounds to an unavailable measurement. Failed setters leave the previous field intact; check the error before transmitting. A nil receiver also returns this error. Each accessor documents its unit and conversion (value = raw * resolution + offset); the units are the schema's SI units (rad, m/s, K, V, ...).

For dynamic, metadata-driven access — when the field is only known at runtime — pgn.PhysicalValue(msg, fieldOrder) performs the same conversion by field source order and also returns the unit label:

v, unit, ok, err := pgn.PhysicalValue(heading, 2) // field order 2 = Heading
// v = 1.5708, unit = "rad"

PhysicalValue returns an error for unknown fields, non-numeric fields (strings, binary, FLOAT, match selectors), and fields inside repeating groups — for those, decode the group slice and use the element structs' accessors instead (they're generated too).

Unit Types

The units package provides type-safe quantity wrappers (Distance, Velocity, Pressure, ...) with built-in unit conversion. It is independent of the PGN decode path: decoded structs keep raw wire ticks, and the generated accessors above return plain float64 values in each field's native schema unit. Wrapping those values into units types is left to the caller; wiring units directly into decoding would require changing generated PGN struct fields from raw-tick *uint64/*int64 values to quantity types, which is deliberately deferred (see the units package doc comment).

Conformance Status

The public, reproducible protocol evidence is run with just conformance-local and in Linux CI. Its controlled baseline is ISO 11783-3:2026, edition 5 for transport, ISO 11783-5:2019, edition 3 for address management, and NMEA 2000 Version 3.000 with amendments for the marine application and certification process. The test-to-behavior matrix is in the conformance guide.

This evidence is not formal NMEA certification. The official licensed tool has not been run against this repository alone: certification requires the actual product hardware and firmware, assigned manufacturer and product codes, the licensed tool, its encrypted result, and NMEA validation. The tracked evidence template reports those external steps as not-run until real records are supplied; the project does not infer or simulate a pass.

Comparison

Reviewed 2026-07-18, these are relevant projects that document NMEA 2000 support. Go projects come first because n2k is for Go applications; non-Go projects follow to show the broader ecosystem. NMEA 0183-only parsers are excluded.

Legend: ✅ first-class documented support · 🟡 partial, lower-level, or workflow-specific · ❓ capability may exist but isn't documented · ❌ not present or not applicable.

For a Go application, open-ships/n2k is designed to cover the full path in one API: typed decoding, byte-preserving writes, bus-node behavior, group functions, and gateway/file sources. Evaluate the details that matter to your deployment rather than relying on the summary table alone.

Known Limitations

• The codec implements the schema's current PGNIsProprietary field condition; a future schema condition expression must be added explicitly and otherwise fails closed during codec-plan compilation.
• Formal NMEA certification has not been run. Products that transmit on a real vessel network must follow the hardware/tool workflow in Protocol conformance before making a certification claim.
• One physical bus per client.
• Address claiming uses a 1500ms default timeout; on heavily contested buses, increase via WithClaimTimeout.
• File, EBL, and UDP sources are read-only; writing requires CAN, USB, Serial, TCP, or Replay.
• FormatActisense and FormatActisenseN2KASCII are gateway-owned read sources and are rejected by NewClient. Use ActisenseGatewaySession for sends under the physical gateway identity, or BST-95/CAN ASCII for a true source-authoritative Client.
• Mode 5 is not available on NGT-class hardware. Raw mode does not silently fall back; an unsupported or unacknowledged BEM setup fails NewClient startup. Such hardware can still be read passively or used through an ActisenseGatewaySession, without virtual-node claims.
• Gateway TCP connections do not auto-reconnect by default; a dropped connection ends the read loop. Pass WithReconnect to re-dial dropped connections with backoff. Each new connection epoch reclaims the address, clears stale registry topology, waits through contention, re-enumerates, and resumes scheduled traffic.
• Live delivery is bounded by design. A reader that cannot keep up receives ErrReceiveOverflow or ErrObservationOverflow; increase WithReceiveBuffer or consume faster.

License

MIT — see LICENSE.

Development and security

See CONTEXT.md for architecture vocabulary and invariants, the architecture guide for runtime ownership, the conformance guide for standards evidence, CONTRIBUTING.md for required checks, and SECURITY.md for private vulnerability reporting.

Acknowledgments

• canboat — maintains the open PGN schema this library's decoders are generated from. The decoded-message breadth here is theirs.
• boatkit-io/n2k — the Go project that inspired this one.