nmea2k 0.2.0

A Python framework for building NMEA 2000 (N2K) marine CAN-bus devices: codecs, fast-packet reassembly, ISO address claim, a device stack, and generated PGN classes.

nmea2k

A Python framework for building NMEA 2000 (N2K) marine CAN-bus devices — message codecs, fast-packet reassembly, ISO address claim, a device stack with RX dispatch, and generated PGN classes for the full canboat PGN set.

Heavily inspired by ttlappalainen/NMEA2000 (C++). PGN field codecs are generated from canboat (see pgn_gen.py); protocol PGNs with logic are class overrides with the nmea2k.protocol logic.

I did try to adapt the framework to Python's strength, this is not intended for embedded devices (maybe someone wants to check out if it runs in MicroPython).

I'm quite happy with the class generator using the canboat PGN definitions. It allows for class overrides. I first went the route of a single class that can mimic any PGN. I don't think that is as useful, or as performant.

This sat on my drive for a while, I never got around to getting it into a nice package to publish. With the help of a couple of AI friends, I got it cleaned up, a couple of bugs fixed and 2 examples added.

As far as I know it is a pretty complete implementation. But I do not have access to the specification or the test suites.

Enjoy

Not affiliated with or endorsed by the National Marine Electronics Association. "NMEA 2000" is a registered trademark of the NMEA; it is used here only descriptively, to name the protocol this library implements.

Install

pip install nmea2k[can]     # normal: pulls python-can as the CAN backend

On constrained hosts where python-can can't be installed (e.g. a Raspberry Pi under an externally-managed Python), install the base package and use the bundled raw-SocketCAN shim instead:

pip install nmea2k

import sys, nmea2k.socketcan
sys.modules["can"] = nmea2k.socketcan   # before importing the framework

Requires Python 3.10+.

What's here

Module	Purpose
nmea2k.message / nmea2k.fields / nmea2k.pgn	CAN-ID + field-table codec engine
nmea2k.fastpacket	fast-packet (multi-frame) assembly/disassembly
nmea2k.stack (N2K)	the device stack: TX path, RX dispatch, timers
nmea2k.device / nmea2k.device_list	ISO address claim + network device list
nmea2k.group / nmea2k.handler	group-function handling + PGN handlers
nmea2k.gen.*	one generated class per PGN (from canboat)
nmea2k.socketcan	optional stdlib raw-SocketCAN can shim

Examples

• examples/windlass/ — a complete anchor-windlass device (address claim, product info, heartbeat, windlass PGNs 128776/7/8): the reference "how to build a device" driver.
• examples/bridge/ — a configurable two-bus N2K bridge that forwards frames between two CAN interfaces with per-direction PGN filtering.

Regenerating the PGN classes

The nmea2k.gen package is generated from CANboat's PGN database:

python tools/pgn_gen.py     # reads data/canboat.json -> src/nmea2k/gen/ + lookups.py

Feedback & contributing

Issues, bugs, and ideas → codeberg.org/mfriedel42/nmea2k/issues. A bus capture (candump) helps for decode bugs. See the docs for how to contribute and the roadmap.

License

Apache-2.0. PGN definitions are derived from the Apache-2.0-licensed CANboat project — see NOTICE.