Metadata-Version: 2.4
Name: nmea2k
Version: 0.1.0
Summary: 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.
Author-email: mfriedel42 <mfriedel42@noreply.codeberg.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://codeberg.org/mfriedel42/nmea2k
Project-URL: Repository, https://codeberg.org/mfriedel42/nmea2k
Project-URL: Issues, https://codeberg.org/mfriedel42/nmea2k/issues
Keywords: nmea2000,n2k,canbus,socketcan,marine,boat,canboat,pgn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: can
Requires-Dist: python-can>=4.0; extra == "can"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: python-can>=4.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

```bash
pip install nmea2k
```
```python
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:

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

## License

Apache-2.0. PGN definitions are derived from the Apache-2.0-licensed
[CANboat](https://github.com/canboat/canboat) project — see `NOTICE`.
