n2k2ip 0.1.0__py3-none-any.whl

n2k2ip-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: n2k2ip
+Version: 0.1.0
+Summary: Bridge an NMEA 2000 (SocketCAN) bus to TCP clients as Yacht Devices RAW (YDRAW)
+Author: ghotihook
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ghotihook/n2k2ip
+Project-URL: Repository, https://github.com/ghotihook/n2k2ip
+Project-URL: Issues, https://github.com/ghotihook/n2k2ip/issues
+Keywords: nmea2000,nmea,socketcan,can,ydraw,yacht,marine,gateway
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# n2k2ip
+
+Bridge an NMEA 2000 (SocketCAN) bus onto the network: read raw CAN frames from a
+SocketCAN interface and stream them to TCP clients as **Yacht Devices RAW (YDRAW)**
+text — one line per CAN frame. A software equivalent of a Yacht Devices Wi-Fi gateway
+(YDWG-02) in *RAW* mode.
+
+```
+NMEA2000 bus ──(can0)──▶ n2k2ip ──(tcp/1457)──▶ many clients
+                                                 (plotters, loggers, OpenCPN, …)
+```
+
+## Why it exists / design
+
+The data is **live**, and stale data is worthless. Everything here serves that:
+
+- **Drop-old, never back up.** Each client has a bounded outbound queue. When a client
+  can't keep up (a slow or stalled Wi-Fi link), the *oldest* whole lines are dropped so
+  it always receives recent frames instead of a growing backlog. Maximum staleness is
+  bounded by the `MAX_QUEUE` constant (100 lines) in `n2k2ip.py`.
+- **One slow client can't hurt the others.** All writes are non-blocking; a stalled or
+  dead client never blocks the CAN reader or the other clients.
+- **Low latency by default.** `TCP_NODELAY` is set on every client, so each line hits
+  the wire immediately (no Nagle batching). Over Wi-Fi this matters — measured median
+  latency for this kind of small-message stream is a few ms with NODELAY vs tens of ms
+  without.
+- **Lightweight.** Single-threaded, event-driven (`selectors`) — no threads, no
+  busy-poll, no dependencies. Pure Python standard library.
+
+## Requirements
+
+- Linux with SocketCAN (a `can0`-style interface)
+- Python **3.9+** — **no third-party packages** (stdlib only)
+- A **synchronised host clock** — YDRAW timestamps are taken from the host's UTC
+  clock, so make sure NTP is running and disciplined (e.g. `systemd-timesyncd` or
+  `chrony`). On a headless/boat box without a network, fit an RTC or expect the
+  clock — and therefore the timestamps — to be wrong until time is acquired.
+
+## Install
+
+On Raspberry Pi OS (and other Debian 12+ systems) the system Python is
+"externally managed", so use **pipx** — it drops the `n2k2ip` command on your
+`PATH` in its own isolated environment and sidesteps `--break-system-packages`:
+
+```sh
+sudo apt install pipx        # once, if you don't have it
+pipx install n2k2ip
+```
+
+There are no third-party dependencies, so plain `pip install n2k2ip` also works
+if you'd rather (add `--break-system-packages`, or install into a virtualenv).
+
+Because n2k2ip is a single stdlib-only file, you can also skip installing
+entirely and run it straight from a checkout:
+
+```sh
+python3 n2k2ip.py --channel can0 --port 1457
+```
+
+## Quick start
+
+```sh
+# bring the CAN interface up at the NMEA2000 bitrate
+sudo ip link set can0 up type can bitrate 250000
+
+# serve YDRAW on tcp/1457
+n2k2ip --channel can0 --port 1457
+```
+
+Connect and watch:
+
+```sh
+nc <host> 1457
+# 09:46:57.556 R 0DF50B16 00 E6 05 00 00 FF 7F FF
+# 09:46:57.556 R 00FA8C3E 4C 08 C2 24 7E E8 61 4B
+# ...
+```
+
+## Usage
+
+```
+n2k2ip [--channel can0] [--port 1457] [--log-level INFO]
+```
+
+(or `python3 n2k2ip.py …` when running from a checkout)
+
+| option | default | meaning |
+|---|---|---|
+| `--channel` | `can0` | SocketCAN interface to read |
+| `--port` | `1457` | TCP port to serve YDRAW on |
+| `--log-level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+Per-client buffer depth is the `MAX_QUEUE` constant in `n2k2ip.py` (100 lines). When a
+client falls behind, the oldest lines are dropped so it never lags more than ~100
+frames — roughly 0.2–0.5 s of backlog on a busy bus. Raise it only if you'd rather
+tolerate longer stalls than skip frames.
+
+## Output format (YDRAW)
+
+Each line is one CAN frame:
+
+```
+HH:MM:SS.mmm R <8-hex CAN-ID> <space-separated hex data bytes>
+```
+
+Lines are terminated with `\r\n`. Direction is always `R` (received). The
+timestamp is the host clock in **UTC** (`HH:MM:SS.mmm`). The YDRAW spec calls for
+UTC sourced from the NMEA 2000 bus when available; we don't decode the bus, so we
+use the host's UTC clock instead — accurate as long as the host clock is synced
+(e.g. NTP).
+
+**Multi-frame (fast-packet) messages are passed through, not reassembled** — and that
+is correct for YDRAW, which is a per-CAN-frame format. Each fast-packet frame is sent
+as its own line with its sequence/frame-counter byte intact; reassembling them into a
+logical PGN is the *consumer's* job (e.g. canboat `analyzer`, OpenCPN, a YDRAW
+decoder). Over a lossy link this means a lost frame loses its whole fast-packet PGN —
+inherent to the format, same as a hardware gateway. For that reason **TCP is preferred
+over UDP/broadcast on Wi-Fi**, where reliability and low jitter matter most.
+
+## Run as a service (systemd)
+
+Install it globally with pipx, then drop in the shipped unit:
+
+```sh
+sudo apt install pipx                 # once, if you don't have it
+sudo pipx install --global n2k2ip     # -> /usr/local/bin/n2k2ip
+sudo cp n2k2ip.service /etc/systemd/system/
+# edit the unit if your channel/port differ, or if can0 is brought up elsewhere
+sudo systemctl daemon-reload
+sudo systemctl enable --now n2k2ip.service
+journalctl -u n2k2ip.service -f
+```
+
+Update later with `sudo pipx upgrade --global n2k2ip`. If you'd rather not
+pip-install at all, the single stdlib-only file can just be copied and run
+directly — see the comment header in `n2k2ip.service`.
+
+## Behaviour notes
+
+- **CAN reconnect.** If the interface goes down or the controller goes bus-off, the
+  reader logs it and reopens the socket with backoff — appropriate for a boat bus that
+  may power-cycle.
+- **Error/remote frames** are skipped; only data frames are forwarded.
+- **No filtering.** Every data frame on the bus is forwarded. Add a SocketCAN filter in
+  `_open_can` if you need to restrict PGNs.
+
+## License
+
+MIT

n2k2ip-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+n2k2ip.py,sha256=6vaoDu3GZNjrNA9kbZw3XRu_jD7WjelEai4C_uJlqnY,9988
+n2k2ip-0.1.0.dist-info/licenses/LICENSE,sha256=pC9rM_mLyI9TpNbmm9A-yOZ-EH53oU7FoSIefmiM6ug,1066
+n2k2ip-0.1.0.dist-info/METADATA,sha256=3xtYx09YJlWS_jXIdoibpZIpiNJlkKrmw3M0OECa12w,6844
+n2k2ip-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+n2k2ip-0.1.0.dist-info/entry_points.txt,sha256=IHCqAXHS6vPAf3AuNJsb1wjGpLdYk3oWV1XPT__ycic,39
+n2k2ip-0.1.0.dist-info/top_level.txt,sha256=QEQDTvakroc21J6J1A6Pyv52FtDrt2SHbz0tqgEwo7I,7
+n2k2ip-0.1.0.dist-info/RECORD,,

n2k2ip-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

n2k2ip-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+n2k2ip = n2k2ip:main

n2k2ip-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghotihook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

n2k2ip-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+n2k2ip

n2k2ip.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""n2k2ip — bridge an NMEA2000 (SocketCAN) bus to TCP clients as Yacht Devices RAW.
+
+Reads raw CAN frames from a SocketCAN channel and fans each one out, as a single
+YDRAW line, to every connected TCP client.
+
+Designed for *live* data, where stale data is worthless:
+  - Each client has a bounded outbound queue. If a client can't keep up (a slow or
+    stalled wifi link), the OLDEST whole lines are dropped so it always receives
+    recent frames, never a growing backlog. Freshness is bounded by MAX_QUEUE.
+  - Writes are non-blocking, so one slow/dead client never stalls the CAN reader or
+    the other clients.
+  - TCP_NODELAY on every client: each line hits the wire immediately (no Nagle).
+
+Single-threaded, event-driven (selectors) — no threads, no busy-poll.
+
+    python3 n2k2ip.py --channel can0 --port 1457
+"""
+import argparse
+import logging
+import selectors
+import socket
+import struct
+import time
+from collections import deque
+
+__version__ = "0.1.0"
+
+# struct can_frame (Linux): u32 can_id, u8 dlc, 3 pad bytes, 8 data bytes
+CAN_FRAME    = struct.Struct("=IB3x8s")
+CAN_RTR_FLAG = 0x40000000   # remote-transmission request
+CAN_ERR_FLAG = 0x20000000   # error frame
+CAN_EFF_MASK = 0x1FFFFFFF   # 29-bit extended identifier
+
+# Max whole lines buffered per client before the oldest are dropped. Bounds how
+# stale a slow client's data can get; favours freshness over completeness.
+MAX_QUEUE = 100
+
+log = logging.getLogger("n2k2ip")
+
+
+def frame_to_ydraw(can_id: int, data: bytes) -> bytes:
+    """Render a CAN frame as one YDRAW line: 'HH:MM:SS.mmm R <8-hex id> <hex bytes>'."""
+    now = time.time()
+    stamp = time.strftime("%H:%M:%S", time.gmtime(now)) + ".%03d" % int((now % 1) * 1000)
+    body = data.hex(" ").upper()
+    line = "%s R %08X" % (stamp, can_id)
+    return ((line + " " + body) if body else line).encode("ascii") + b"\r\n"
+
+
+class Client:
+    __slots__ = ("sock", "addr", "buf", "dropped")
+
+    def __init__(self, sock, addr):
+        self.sock = sock
+        self.addr = "%s:%d" % addr
+        self.buf = deque()   # pending whole YDRAW lines (bytes); each is atomic
+        self.dropped = 0
+
+
+class CanDown(Exception):
+    """The CAN socket errored (interface down / bus-off) and must be reopened."""
+
+
+class Gateway:
+    def __init__(self, channel: str, port: int):
+        self.channel = channel
+        self.max_queue = MAX_QUEUE
+        self.clients: set[Client] = set()
+        self.sel = selectors.DefaultSelector()
+        self.frames = 0
+
+        self.listen = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.listen.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.listen.bind(("", port))
+        self.listen.listen(16)
+        self.listen.setblocking(False)
+        self.sel.register(self.listen, selectors.EVENT_READ, "listen")
+
+        self.can = self._open_can()
+        self.sel.register(self.can, selectors.EVENT_READ, "can")
+        log.info("listening on tcp/%d, reading %s", port, channel)
+
+    # ── CAN ────────────────────────────────────────────────────────────────────
+    def _open_can(self):
+        while True:
+            try:
+                s = socket.socket(socket.PF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
+                s.bind((self.channel,))
+                s.setblocking(False)
+                return s
+            except OSError as e:
+                log.warning("%s not available (%s) — retrying; bring it up: "
+                            "sudo ip link set %s up type can bitrate 250000",
+                            self.channel, e, self.channel)
+                time.sleep(1.0)
+
+    def _drain_can(self) -> list:
+        """Read every frame currently available; return their YDRAW lines."""
+        lines = []
+        while True:
+            try:
+                raw = self.can.recv(16)
+            except BlockingIOError:
+                break
+            except OSError as e:
+                raise CanDown(str(e))
+            if len(raw) < 16:
+                continue
+            can_id, dlc, payload = CAN_FRAME.unpack(raw)
+            if can_id & (CAN_ERR_FLAG | CAN_RTR_FLAG):
+                continue   # skip error/remote frames
+            lines.append(frame_to_ydraw(can_id & CAN_EFF_MASK, payload[:dlc]))
+        self.frames += len(lines)
+        return lines
+
+    # ── clients ────────────────────────────────────────────────────────────────
+    def _accept(self):
+        try:
+            sock, addr = self.listen.accept()
+        except OSError:
+            return
+        sock.setblocking(False)
+        sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        c = Client(sock, addr)
+        self.clients.add(c)
+        self.sel.register(sock, selectors.EVENT_READ, c)
+        log.info("client %s connected (%d total)", c.addr, len(self.clients))
+
+    def _drop(self, c: Client, reason: str):
+        if c not in self.clients:
+            return   # idempotent: already dropped this batch
+        self.clients.discard(c)
+        try:
+            self.sel.unregister(c.sock)
+        except (KeyError, ValueError):
+            pass     # never registered / fd already closed
+        try:
+            c.sock.close()
+        except OSError:
+            pass
+        log.info("client %s gone: %s (dropped %d lines; %d total)",
+                 c.addr, reason, c.dropped, len(self.clients))
+
+    def _flush(self, c: Client) -> bool:
+        """Send as much of the client's queue as the socket accepts without blocking.
+        Returns True if fully drained. Raises OSError if the client is dead."""
+        while c.buf:
+            chunk = c.buf[0]
+            try:
+                n = c.sock.send(chunk)
+            except BlockingIOError:
+                return False
+            if n < len(chunk):
+                c.buf[0] = chunk[n:]
+                return False
+            c.buf.popleft()
+        return True
+
+    def _want_write(self, c: Client):
+        ev = selectors.EVENT_READ | (selectors.EVENT_WRITE if c.buf else 0)
+        try:
+            self.sel.modify(c.sock, ev, c)
+        except (KeyError, ValueError):
+            pass
+
+    def _fan_out(self, lines: list):
+        for c in list(self.clients):
+            c.buf.extend(lines)
+            # Bound staleness: keep only the most recent max_queue lines.
+            excess = len(c.buf) - self.max_queue
+            for _ in range(excess if excess > 0 else 0):
+                c.buf.popleft()
+                c.dropped += 1
+            try:
+                self._flush(c)
+            except OSError as e:
+                self._drop(c, str(e))
+                continue
+            self._want_write(c)
+
+    def _service(self, c: Client, mask):
+        if mask & selectors.EVENT_READ:
+            # We don't expect input; a readable client means data or a closed peer.
+            try:
+                if not c.sock.recv(4096):
+                    self._drop(c, "closed by peer")
+                    return
+            except OSError as e:
+                self._drop(c, str(e))
+                return
+        if mask & selectors.EVENT_WRITE:
+            try:
+                self._flush(c)
+            except OSError as e:
+                self._drop(c, str(e))
+                return
+            self._want_write(c)
+
+    # ── main loop ────────────────────────────────────────────────────────────────
+    def run(self):
+        last_stat = time.monotonic()
+        while True:
+            for key, mask in self.sel.select(timeout=5.0):
+                tag = key.data
+                if tag == "can":
+                    try:
+                        self._fan_out(self._drain_can())
+                    except CanDown as e:
+                        log.error("CAN error (%s) — reopening %s", e, self.channel)
+                        self.sel.unregister(self.can)
+                        self.can.close()
+                        self.can = self._open_can()
+                        self.sel.register(self.can, selectors.EVENT_READ, "can")
+                elif tag == "listen":
+                    self._accept()
+                elif tag in self.clients:
+                    self._service(tag, mask)
+                # else: a stale event for a client already dropped earlier in this
+                # same select() batch — ignore it.
+
+            now = time.monotonic()
+            if now - last_stat >= 30:
+                log.info("stats: %d clients, %d frames forwarded", len(self.clients),
+                         self.frames)
+                last_stat = now
+
+    def close(self):
+        for c in list(self.clients):
+            c.sock.close()
+        self.listen.close()
+        self.can.close()
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--channel", default="can0", help="SocketCAN interface (default: can0)")
+    ap.add_argument("--port", type=int, default=1457,
+                    help="TCP port to serve YDRAW on (default: 1457)")
+    ap.add_argument("--log-level", default="INFO",
+                    choices=("DEBUG", "INFO", "WARNING", "ERROR"))
+    ap.add_argument("--version", action="version",
+                    version=f"n2k2ip {__version__}")
+    args = ap.parse_args()
+
+    logging.basicConfig(level=getattr(logging, args.log_level),
+                        format="%(asctime)s [n2k2ip] %(levelname)s %(message)s")
+    gw = Gateway(args.channel, args.port)
+    try:
+        gw.run()
+    except KeyboardInterrupt:
+        log.info("stopping")
+    finally:
+        gw.close()
+
+
+if __name__ == "__main__":
+    main()