maritime-frame 0.1.0__tar.gz

maritime_frame-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Maritime Frame Contributors
+
+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.

maritime_frame-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include README.md

maritime_frame-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: maritime-frame
+Version: 0.1.0
+Summary: Zero-dependency streaming parsers for NMEA and related marine telemetry protocols
+Author: Maritime Frame Contributors
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# maritime-frame
+
+`maritime-frame` is a zero-runtime-dependency Python library for incremental NMEA and marine telemetry decoding. It is designed for applications that receive arbitrary serial, TCP, UDP, or CAN fragments and cannot assume that one read equals one frame.
+
+## Install and test
+
+```bash
+python -m pip install .
+python -m unittest discover -s tests -v
+```
+
+## Streaming NMEA-0183 and AIS
+
+```python
+from maritime_frame import StreamParser, Status
+
+parser = StreamParser(max_sentence=1024)
+for chunk in serial_port:
+    for event in parser.feed(chunk):
+        if event.status is Status.VALID_FRAME:
+            print(event.protocol, event.message)
+        elif event.status is Status.CORRUPTED_FRAME:
+            logger.warning("discarded frame: %s", event.error)
+```
+
+`feed()` accepts `str` or ASCII `bytes`, retains incomplete lines, rejects overlong input, validates the optional two-digit XOR checksum, and recognizes `$` and `!` prefixes. `ddm_to_decimal("4807.038", "N")` returns `48.1173`. AIS `!AIVDM` and `!AIVDO` payloads are 6-bit unarmored into a bit string; message types 1, 2, 3, and 5 expose MMSI, position, speed, course, heading, identity, and ship dimensions. Multi-sentence AIS messages are reassembled by sequence ID.
+
+## NMEA-2000 CAN and Fast Packet
+
+A 29-bit CAN identifier is mapped as follows:
+
+```text
+28       26 25 24 23       16 15        8 7       0
++----------+--+--+-----------+------------+---------+
+| priority |R |DP| PDU format|PDU specific| source  |
++----------+--+--+-----------+------------+---------+
+```
+
+```python
+from maritime_frame import StreamParser
+
+parser = StreamParser(n2k_timeout=1.0)
+first = parser.feed_can(0x0CF00501, bytes([0, 10, 1, 2, 3, 4, 5, 6]), 100.0)
+second = parser.feed_can(0x0CF00501, bytes([1, 7, 8, 9, 10, 0, 0, 0]), 100.1)
+assert second.message.payload == bytes(range(1, 11))
+```
+
+The assembler enforces frame number order, a maximum payload of 223 bytes, exact eight-byte CAN data frames, and timeout purging before each frame. Dropped or late follow-up frames never remain in memory indefinitely.
+
+## OneNet, legacy, and proprietary layers
+
+```python
+from maritime_frame.onenet import parse_datagram
+from maritime_frame.proprietary import ProprietaryRegistry
+
+network = parse_datagram(b"UdPBc $GPRMC,...")
+registry = ProprietaryRegistry()
+registry.register("PGR", lambda sentence: {"vendor": "Garmin", "fields": sentence.fields})
+```
+
+`parse_datagram` validates the `UdP*`/`TcP*` transport token and preserves the payload for the normal stream parser. `legacy.parse_0180` and `legacy.parse_0182` decode steering and bearing flags. The proprietary registry is intentionally open-ended so vendor payload schemas remain application-owned.
+
+## Status contract
+
+Every chunk or CAN frame yields one deterministic status: `VALID_FRAME`, `PARTIAL_STREAM`, or `CORRUPTED_FRAME`. A partial NMEA line produces a partial event while its bytes remain buffered. Invalid checksums, invalid AIS armor, overflows, malformed transport headers, and N2K sequencing errors produce corrupted events without exposing unsafe indexes or unbounded allocations.
+
+## Scope and transport boundary
+
+The package parses frames; it does not open sockets, configure serial ports, or control a CAN adapter. That keeps it portable and lets downstream systems choose their I/O, scheduling, timestamp, and multicast policy. All runtime code uses only the Python standard library.

maritime_frame-0.1.0/README.md

@@ -0,0 +1,69 @@
+# maritime-frame
+
+`maritime-frame` is a zero-runtime-dependency Python library for incremental NMEA and marine telemetry decoding. It is designed for applications that receive arbitrary serial, TCP, UDP, or CAN fragments and cannot assume that one read equals one frame.
+
+## Install and test
+
+```bash
+python -m pip install .
+python -m unittest discover -s tests -v
+```
+
+## Streaming NMEA-0183 and AIS
+
+```python
+from maritime_frame import StreamParser, Status
+
+parser = StreamParser(max_sentence=1024)
+for chunk in serial_port:
+    for event in parser.feed(chunk):
+        if event.status is Status.VALID_FRAME:
+            print(event.protocol, event.message)
+        elif event.status is Status.CORRUPTED_FRAME:
+            logger.warning("discarded frame: %s", event.error)
+```
+
+`feed()` accepts `str` or ASCII `bytes`, retains incomplete lines, rejects overlong input, validates the optional two-digit XOR checksum, and recognizes `$` and `!` prefixes. `ddm_to_decimal("4807.038", "N")` returns `48.1173`. AIS `!AIVDM` and `!AIVDO` payloads are 6-bit unarmored into a bit string; message types 1, 2, 3, and 5 expose MMSI, position, speed, course, heading, identity, and ship dimensions. Multi-sentence AIS messages are reassembled by sequence ID.
+
+## NMEA-2000 CAN and Fast Packet
+
+A 29-bit CAN identifier is mapped as follows:
+
+```text
+28       26 25 24 23       16 15        8 7       0
++----------+--+--+-----------+------------+---------+
+| priority |R |DP| PDU format|PDU specific| source  |
++----------+--+--+-----------+------------+---------+
+```
+
+```python
+from maritime_frame import StreamParser
+
+parser = StreamParser(n2k_timeout=1.0)
+first = parser.feed_can(0x0CF00501, bytes([0, 10, 1, 2, 3, 4, 5, 6]), 100.0)
+second = parser.feed_can(0x0CF00501, bytes([1, 7, 8, 9, 10, 0, 0, 0]), 100.1)
+assert second.message.payload == bytes(range(1, 11))
+```
+
+The assembler enforces frame number order, a maximum payload of 223 bytes, exact eight-byte CAN data frames, and timeout purging before each frame. Dropped or late follow-up frames never remain in memory indefinitely.
+
+## OneNet, legacy, and proprietary layers
+
+```python
+from maritime_frame.onenet import parse_datagram
+from maritime_frame.proprietary import ProprietaryRegistry
+
+network = parse_datagram(b"UdPBc $GPRMC,...")
+registry = ProprietaryRegistry()
+registry.register("PGR", lambda sentence: {"vendor": "Garmin", "fields": sentence.fields})
+```
+
+`parse_datagram` validates the `UdP*`/`TcP*` transport token and preserves the payload for the normal stream parser. `legacy.parse_0180` and `legacy.parse_0182` decode steering and bearing flags. The proprietary registry is intentionally open-ended so vendor payload schemas remain application-owned.
+
+## Status contract
+
+Every chunk or CAN frame yields one deterministic status: `VALID_FRAME`, `PARTIAL_STREAM`, or `CORRUPTED_FRAME`. A partial NMEA line produces a partial event while its bytes remain buffered. Invalid checksums, invalid AIS armor, overflows, malformed transport headers, and N2K sequencing errors produce corrupted events without exposing unsafe indexes or unbounded allocations.
+
+## Scope and transport boundary
+
+The package parses frames; it does not open sockets, configure serial ports, or control a CAN adapter. That keeps it portable and lets downstream systems choose their I/O, scheduling, timestamp, and multicast policy. All runtime code uses only the Python standard library.

maritime_frame-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maritime-frame"
+version = "0.1.0"
+description = "Zero-dependency streaming parsers for NMEA and related marine telemetry protocols"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Maritime Frame Contributors"}]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: System :: Hardware"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

maritime_frame-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

maritime_frame-0.1.0/src/maritime_frame/__init__.py

@@ -0,0 +1,12 @@
+"""Streaming marine telemetry frame parsing."""
+from .models import AisMessage, CanFrame, N2kMessage, NmeaSentence, ParseEvent, Status
+from .nmea0183 import checksum, ddm_to_decimal, parse_sentence
+from .ais import decode as decode_ais
+from .n2k import FastPacketAssembler, decode_can_id
+from .parser import StreamParser
+
+__all__ = [
+    "AisMessage", "CanFrame", "FastPacketAssembler", "N2kMessage", "NmeaSentence",
+    "ParseEvent", "Status", "StreamParser", "checksum", "decode_ais", "decode_can_id",
+    "ddm_to_decimal", "parse_sentence",
+]

maritime_frame-0.1.0/src/maritime_frame/ais.py

@@ -0,0 +1,66 @@
+"""AIS 6-bit armoring and common Class A message decoding."""
+from __future__ import annotations
+
+from .models import AisMessage
+
+
+def _bits(payload: str) -> str:
+    values = []
+    for char in payload:
+        code = ord(char) - 48
+        if code > 40:
+            code -= 8
+        if not 0 <= code < 64:
+            raise ValueError("invalid AIS armored character")
+        values.append(f"{code:06b}")
+    return "".join(values)
+
+
+def _u(bits: str, start: int, width: int) -> int:
+    end = start + width
+    if end > len(bits):
+        raise ValueError("truncated AIS payload")
+    return int(bits[start:end], 2)
+
+
+def _signed(bits: str, start: int, width: int) -> int:
+    value = _u(bits, start, width)
+    return value - (1 << width) if value & (1 << (width - 1)) else value
+
+
+def decode(payload: str, fill_bits: int = 0) -> AisMessage:
+    if not 0 <= fill_bits <= 5:
+        raise ValueError("fill bits out of range")
+    bits = _bits(payload)
+    if fill_bits:
+        bits = bits[:-fill_bits]
+    message_type, repeat, mmsi = _u(bits, 0, 6), _u(bits, 6, 2), _u(bits, 8, 30)
+    fields: dict[str, int | float | str] = {}
+    if message_type in {1, 2, 3}:
+        fields.update(
+            navigational_status=_u(bits, 38, 4),
+            rate_of_turn=_signed(bits, 42, 8),
+            speed_over_ground=_u(bits, 50, 10) / 10.0,
+            longitude=_signed(bits, 61, 28) / 600000.0,
+            latitude=_signed(bits, 89, 27) / 600000.0,
+            course_over_ground=_u(bits, 116, 12) / 10.0,
+            true_heading=_u(bits, 128, 9),
+            timestamp=_u(bits, 137, 6),
+        )
+    elif message_type == 5:
+        fields.update(
+            imo_number=_u(bits, 40, 30),
+            callsign=_text(bits, 70, 42),
+            vessel_name=_text(bits, 112, 120),
+            ship_type=_u(bits, 232, 8),
+            to_bow=_u(bits, 240, 9), to_stern=_u(bits, 249, 9),
+            to_port=_u(bits, 258, 6), to_starboard=_u(bits, 264, 6),
+        )
+    else:
+        fields["raw_bits"] = bits
+    return AisMessage(message_type, repeat, mmsi, fields, payload)
+
+
+def _text(bits: str, start: int, width: int) -> str:
+    alphabet = "@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_ !\"#$%&'()*+,-./0123456789:;<=>?"
+    return "".join(alphabet[_u(bits, offset, 6)] for offset in range(start, start + width, 6)).rstrip(" @")

maritime_frame-0.1.0/src/maritime_frame/legacy.py

@@ -0,0 +1,20 @@
+"""Small, explicit decoders for NMEA-0180/0182 steering sentences."""
+from __future__ import annotations
+
+
+def parse_0180(fields: list[str] | tuple[str, ...]) -> dict[str, str | float]:
+    if len(fields) < 2:
+        raise ValueError("NMEA-0180 requires steering flag and error")
+    flag = fields[0].upper()
+    if flag not in {"L", "R", "A", "V"}:
+        raise ValueError("invalid cross-track error flag")
+    return {"cross_track_flag": flag, "cross_track_error": float(fields[1])}
+
+
+def parse_0182(fields: list[str] | tuple[str, ...]) -> dict[str, str | float]:
+    if len(fields) < 2:
+        raise ValueError("NMEA-0182 requires bearing flag and bearing")
+    flag = fields[0].upper()
+    if flag not in {"A", "M", "T", "V"}:
+        raise ValueError("invalid bearing flag")
+    return {"bearing_flag": flag, "bearing": float(fields[1])}

maritime_frame-0.1.0/src/maritime_frame/models.py

@@ -0,0 +1,57 @@
+"""Public immutable data structures and parser status values."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Status(str, Enum):
+    VALID_FRAME = "VALID_FRAME"
+    PARTIAL_STREAM = "PARTIAL_STREAM"
+    CORRUPTED_FRAME = "CORRUPTED_FRAME"
+
+
+@dataclass(frozen=True, slots=True)
+class ParseEvent:
+    status: Status
+    protocol: str | None = None
+    message: Any = None
+    error: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class NmeaSentence:
+    talker: str
+    sentence_type: str
+    fields: tuple[str, ...]
+    raw: str
+    checksum: int | None
+    proprietary: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class AisMessage:
+    message_type: int
+    repeat: int
+    mmsi: int
+    fields: dict[str, int | float | str]
+    payload: str
+
+
+@dataclass(frozen=True, slots=True)
+class CanFrame:
+    can_id: int
+    data: bytes
+    timestamp: float
+
+
+@dataclass(frozen=True, slots=True)
+class N2kMessage:
+    priority: int
+    pgn: int
+    source: int
+    destination: int | None
+    payload: bytes
+    timestamp: float
+    fields: dict[str, int | float | str] = field(default_factory=dict)

maritime_frame-0.1.0/src/maritime_frame/n2k.py

@@ -0,0 +1,73 @@
+"""NMEA-2000 CAN identifier decoding and bounded Fast-Packet reassembly."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from .models import N2kMessage
+
+
+def decode_can_id(can_id: int) -> tuple[int, int, int, int | None]:
+    if not 0 <= can_id < (1 << 29):
+        raise ValueError("CAN identifier must be an 11-bit or 29-bit value")
+    priority = (can_id >> 26) & 7
+    data_page = (can_id >> 24) & 1
+    pdu_format = (can_id >> 16) & 0xFF
+    pdu_specific = (can_id >> 8) & 0xFF
+    source = can_id & 0xFF
+    pgn = (data_page << 16) | (pdu_format << 8)
+    destination = None if pdu_format >= 240 else pdu_specific
+    if pdu_format >= 240:
+        pgn |= pdu_specific
+    return priority, pgn, source, destination
+
+
+@dataclass(slots=True)
+class _Assembly:
+    total: int
+    data: bytearray
+    next_index: int
+    last_seen: float
+
+
+class FastPacketAssembler:
+    def __init__(self, timeout: float = 1.0, max_payload: int = 223) -> None:
+        if timeout <= 0 or max_payload < 1:
+            raise ValueError("invalid reassembly limits")
+        self.timeout, self.max_payload = timeout, max_payload
+        self._assemblies: dict[tuple[int, int, int, int | None, int], _Assembly] = {}
+
+    def purge(self, now: float) -> None:
+        expired = [key for key, item in self._assemblies.items() if now - item.last_seen > self.timeout]
+        for key in expired:
+            del self._assemblies[key]
+
+    def feed(self, can_id: int, data: bytes, timestamp: float) -> N2kMessage | None:
+        if len(data) != 8:
+            raise ValueError("N2K CAN data frames must contain exactly 8 bytes")
+        self.purge(timestamp)
+        priority, pgn, source, destination = decode_can_id(can_id)
+        sequence = data[0] >> 5
+        frame_number = data[0] & 0x1F
+        key = (pgn, source, destination or 0, sequence, priority)
+        if frame_number == 0:
+            total = data[1]
+            if not 1 <= total <= self.max_payload:
+                raise ValueError("invalid Fast-Packet payload length")
+            item = _Assembly(total, bytearray(data[2:]), 1, timestamp)
+            self._assemblies[key] = item
+            if total <= 6:
+                del self._assemblies[key]
+                return N2kMessage(priority, pgn, source, destination, bytes(item.data[:total]), timestamp)
+            return None
+        item = self._assemblies.get(key)
+        if item is None or frame_number != item.next_index:
+            self._assemblies.pop(key, None)
+            raise ValueError("missing or out-of-order Fast-Packet frame")
+        item.data.extend(data[1:])
+        item.next_index += 1
+        item.last_seen = timestamp
+        if len(item.data) >= item.total:
+            del self._assemblies[key]
+            return N2kMessage(priority, pgn, source, destination, bytes(item.data[:item.total]), timestamp)
+        return None

maritime_frame-0.1.0/src/maritime_frame/nmea0183.py

@@ -0,0 +1,55 @@
+"""NMEA-0183 sentence parsing, checksum validation, and coordinate helpers."""
+from __future__ import annotations
+
+import re
+from .models import NmeaSentence
+
+_SENTENCE = re.compile(r"^([$!])([^,*\r\n]{1,80})(?:,([^*\r\n]{0,512}))?(?:\*([0-9A-Fa-f]{2}))?$", re.ASCII)
+
+
+def checksum(body: str | bytes) -> int:
+    raw = body.encode("ascii") if isinstance(body, str) else body
+    value = 0
+    for byte in raw:
+        value ^= byte
+    return value
+
+
+def parse_sentence(line: str | bytes, *, require_checksum: bool = False) -> NmeaSentence:
+    text = line.decode("ascii", "strict") if isinstance(line, bytes) else line
+    text = text.strip("\r\n")
+    if not text or text[0] not in "$!":
+        raise ValueError("sentence must begin with '$' or '!'")
+    match = _SENTENCE.fullmatch(text)
+    if not match:
+        raise ValueError("malformed NMEA sentence")
+    prefix, head, fields_text, supplied_hex = match.groups()
+    supplied = int(supplied_hex, 16) if supplied_hex else None
+    body = head + (("," + fields_text) if fields_text is not None else "")
+    if supplied is None and require_checksum:
+        raise ValueError("checksum is required")
+    if supplied is not None and checksum(body) != supplied:
+        raise ValueError("checksum mismatch")
+    if head.startswith("P"):
+        talker, sentence_type = head[:3], head[3:]
+        proprietary = True
+    else:
+        talker, sentence_type = head[:2], head[2:]
+        proprietary = False
+    fields = tuple(fields_text.split(",")) if fields_text is not None else ()
+    return NmeaSentence(talker, sentence_type, fields, text, supplied, proprietary)
+
+
+def ddm_to_decimal(value: str, hemisphere: str) -> float:
+    """Convert NMEA ddmm.mmmm or dddmm.mmmm coordinates to signed degrees."""
+    if not value or hemisphere.upper() not in {"N", "S", "E", "W"}:
+        raise ValueError("invalid DDM coordinate")
+    try:
+        degrees = int(value[: value.index(".") - 2])
+        minutes = float(value[value.index(".") - 2 :])
+    except (ValueError, IndexError):
+        raise ValueError("invalid DDM coordinate") from None
+    if not 0 <= minutes < 60:
+        raise ValueError("coordinate minutes out of range")
+    decimal = degrees + minutes / 60.0
+    return -decimal if hemisphere.upper() in {"S", "W"} else decimal

maritime_frame-0.1.0/src/maritime_frame/onenet.py

@@ -0,0 +1,21 @@
+"""NMEA-OneNet/IEC 61162-450 transport envelope helpers."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class OneNetDatagram:
+    transport_header: str
+    payload: bytes
+
+
+def parse_datagram(data: bytes | str) -> OneNetDatagram:
+    raw = data.encode("ascii") if isinstance(data, str) else data
+    separator = raw.find(b" ")
+    if separator <= 0 or separator > 128:
+        raise ValueError("OneNet transport header is missing")
+    header = raw[:separator].decode("ascii", "strict")
+    if not (header.startswith("UdP") or header.startswith("TcP")):
+        raise ValueError("unsupported OneNet transport header")
+    return OneNetDatagram(header, raw[separator + 1 :])

maritime_frame-0.1.0/src/maritime_frame/parser.py

@@ -0,0 +1,83 @@
+"""Bounded, incremental dispatcher for ASCII NMEA and binary CAN inputs."""
+from __future__ import annotations
+
+from .ais import decode as decode_ais
+from .models import N2kMessage, ParseEvent, Status
+from .n2k import FastPacketAssembler
+from .nmea0183 import parse_sentence
+
+
+class _PartialFrame(Exception):
+    pass
+
+
+class StreamParser:
+    def __init__(self, *, max_sentence: int = 1024, n2k_timeout: float = 1.0) -> None:
+        if max_sentence < 16:
+            raise ValueError("max_sentence is too small")
+        self.max_sentence = max_sentence
+        self._text = bytearray()
+        self._ais_fragments: dict[str, list[str]] = {}
+        self.n2k = FastPacketAssembler(timeout=n2k_timeout)
+
+    def feed(self, chunk: str | bytes) -> list[ParseEvent]:
+        raw = chunk.encode("ascii") if isinstance(chunk, str) else bytes(chunk)
+        events: list[ParseEvent] = []
+        for byte in raw:
+            if byte in (10, 13):
+                if self._text:
+                    events.append(self._parse_line(bytes(self._text)))
+                    self._text.clear()
+                continue
+            if not self._text and byte not in (36, 33):
+                continue
+            if len(self._text) >= self.max_sentence:
+                self._text.clear()
+                events.append(ParseEvent(Status.CORRUPTED_FRAME, error="sentence exceeds configured limit"))
+                continue
+            self._text.append(byte)
+        if self._text:
+            events.append(ParseEvent(Status.PARTIAL_STREAM))
+        elif not events:
+            events.append(ParseEvent(Status.PARTIAL_STREAM))
+        return events
+
+    def feed_can(self, can_id: int, data: bytes, timestamp: float) -> ParseEvent:
+        try:
+            message = self.n2k.feed(can_id, data, timestamp)
+        except (ValueError, IndexError) as exc:
+            return ParseEvent(Status.CORRUPTED_FRAME, protocol="NMEA-2000", error=str(exc))
+        if message is None:
+            return ParseEvent(Status.PARTIAL_STREAM, protocol="NMEA-2000")
+        return ParseEvent(Status.VALID_FRAME, protocol="NMEA-2000", message=message)
+
+    def _parse_line(self, raw: bytes) -> ParseEvent:
+        try:
+            sentence = parse_sentence(raw, require_checksum=False)
+            if sentence.talker == "AI" and sentence.sentence_type in {"VDM", "VDO"}:
+                message = self._parse_ais(sentence)
+                return ParseEvent(Status.VALID_FRAME, protocol="AIS", message=message)
+            return ParseEvent(Status.VALID_FRAME, protocol="NMEA-0183", message=sentence)
+        except _PartialFrame:
+            return ParseEvent(Status.PARTIAL_STREAM, protocol="AIS")
+        except (ValueError, UnicodeError) as exc:
+            return ParseEvent(Status.CORRUPTED_FRAME, protocol="NMEA-0183", error=str(exc))
+
+    def _parse_ais(self, sentence):
+        if len(sentence.fields) < 6:
+            raise ValueError("AIS sentence requires fragment fields")
+        total, number = int(sentence.fields[0]), int(sentence.fields[1])
+        sequence = sentence.fields[2] or "_"
+        payload, fill = sentence.fields[4], int(sentence.fields[5])
+        key = f"{sentence.sentence_type}:{sequence}"
+        parts = self._ais_fragments.setdefault(key, [])
+        if number == 1:
+            parts.clear()
+        if number != len(parts) + 1 or total < number:
+            self._ais_fragments.pop(key, None)
+            raise ValueError("AIS fragments are out of order")
+        parts.append(payload)
+        if number != total:
+            raise _PartialFrame()
+        self._ais_fragments.pop(key, None)
+        return decode_ais("".join(parts), fill)

maritime_frame-0.1.0/src/maritime_frame/proprietary.py

@@ -0,0 +1,23 @@
+"""Registry hook for vendor-specific NMEA-0183 $P sentences."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from .models import NmeaSentence
+
+Decoder = Callable[[NmeaSentence], object]
+
+
+class ProprietaryRegistry:
+    def __init__(self) -> None:
+        self._decoders: dict[str, Decoder] = {}
+
+    def register(self, manufacturer: str, decoder: Decoder) -> None:
+        if not manufacturer or not manufacturer.isalnum():
+            raise ValueError("manufacturer key must be alphanumeric")
+        self._decoders[manufacturer.upper()] = decoder
+
+    def decode(self, sentence: NmeaSentence) -> object:
+        if not sentence.proprietary:
+            raise ValueError("sentence is not proprietary")
+        decoder = self._decoders.get(sentence.talker[1:].upper())
+        return decoder(sentence) if decoder else sentence

maritime_frame-0.1.0/src/maritime_frame.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: maritime-frame
+Version: 0.1.0
+Summary: Zero-dependency streaming parsers for NMEA and related marine telemetry protocols
+Author: Maritime Frame Contributors
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# maritime-frame
+
+`maritime-frame` is a zero-runtime-dependency Python library for incremental NMEA and marine telemetry decoding. It is designed for applications that receive arbitrary serial, TCP, UDP, or CAN fragments and cannot assume that one read equals one frame.
+
+## Install and test
+
+```bash
+python -m pip install .
+python -m unittest discover -s tests -v
+```
+
+## Streaming NMEA-0183 and AIS
+
+```python
+from maritime_frame import StreamParser, Status
+
+parser = StreamParser(max_sentence=1024)
+for chunk in serial_port:
+    for event in parser.feed(chunk):
+        if event.status is Status.VALID_FRAME:
+            print(event.protocol, event.message)
+        elif event.status is Status.CORRUPTED_FRAME:
+            logger.warning("discarded frame: %s", event.error)
+```
+
+`feed()` accepts `str` or ASCII `bytes`, retains incomplete lines, rejects overlong input, validates the optional two-digit XOR checksum, and recognizes `$` and `!` prefixes. `ddm_to_decimal("4807.038", "N")` returns `48.1173`. AIS `!AIVDM` and `!AIVDO` payloads are 6-bit unarmored into a bit string; message types 1, 2, 3, and 5 expose MMSI, position, speed, course, heading, identity, and ship dimensions. Multi-sentence AIS messages are reassembled by sequence ID.
+
+## NMEA-2000 CAN and Fast Packet
+
+A 29-bit CAN identifier is mapped as follows:
+
+```text
+28       26 25 24 23       16 15        8 7       0
++----------+--+--+-----------+------------+---------+
+| priority |R |DP| PDU format|PDU specific| source  |
++----------+--+--+-----------+------------+---------+
+```
+
+```python
+from maritime_frame import StreamParser
+
+parser = StreamParser(n2k_timeout=1.0)
+first = parser.feed_can(0x0CF00501, bytes([0, 10, 1, 2, 3, 4, 5, 6]), 100.0)
+second = parser.feed_can(0x0CF00501, bytes([1, 7, 8, 9, 10, 0, 0, 0]), 100.1)
+assert second.message.payload == bytes(range(1, 11))
+```
+
+The assembler enforces frame number order, a maximum payload of 223 bytes, exact eight-byte CAN data frames, and timeout purging before each frame. Dropped or late follow-up frames never remain in memory indefinitely.
+
+## OneNet, legacy, and proprietary layers
+
+```python
+from maritime_frame.onenet import parse_datagram
+from maritime_frame.proprietary import ProprietaryRegistry
+
+network = parse_datagram(b"UdPBc $GPRMC,...")
+registry = ProprietaryRegistry()
+registry.register("PGR", lambda sentence: {"vendor": "Garmin", "fields": sentence.fields})
+```
+
+`parse_datagram` validates the `UdP*`/`TcP*` transport token and preserves the payload for the normal stream parser. `legacy.parse_0180` and `legacy.parse_0182` decode steering and bearing flags. The proprietary registry is intentionally open-ended so vendor payload schemas remain application-owned.
+
+## Status contract
+
+Every chunk or CAN frame yields one deterministic status: `VALID_FRAME`, `PARTIAL_STREAM`, or `CORRUPTED_FRAME`. A partial NMEA line produces a partial event while its bytes remain buffered. Invalid checksums, invalid AIS armor, overflows, malformed transport headers, and N2K sequencing errors produce corrupted events without exposing unsafe indexes or unbounded allocations.
+
+## Scope and transport boundary
+
+The package parses frames; it does not open sockets, configure serial ports, or control a CAN adapter. That keeps it portable and lets downstream systems choose their I/O, scheduling, timestamp, and multicast policy. All runtime code uses only the Python standard library.

maritime_frame-0.1.0/src/maritime_frame.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/maritime_frame/__init__.py
+src/maritime_frame/ais.py
+src/maritime_frame/legacy.py
+src/maritime_frame/models.py
+src/maritime_frame/n2k.py
+src/maritime_frame/nmea0183.py
+src/maritime_frame/onenet.py
+src/maritime_frame/parser.py
+src/maritime_frame/proprietary.py
+src/maritime_frame.egg-info/PKG-INFO
+src/maritime_frame.egg-info/SOURCES.txt
+src/maritime_frame.egg-info/dependency_links.txt
+src/maritime_frame.egg-info/top_level.txt
+tests/test_parser.py

maritime_frame-0.1.0/src/maritime_frame.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

maritime_frame-0.1.0/src/maritime_frame.egg-info/top_level.txt

@@ -0,0 +1 @@
+maritime_frame

maritime_frame-0.1.0/tests/test_parser.py

@@ -0,0 +1,48 @@
+import unittest
+
+from maritime_frame import FastPacketAssembler, Status, StreamParser, ddm_to_decimal, parse_sentence
+from maritime_frame.ais import decode as decode_ais
+from maritime_frame.n2k import decode_can_id
+from maritime_frame.onenet import parse_datagram
+
+
+class ParserTests(unittest.TestCase):
+    def test_sentence_checksum_and_ddm(self):
+        sentence = "$GPGGA,123519,4807.038,N,01131.000,E,1*53"
+        parsed = parse_sentence(sentence, require_checksum=True)
+        self.assertEqual(parsed.sentence_type, "GGA")
+        self.assertAlmostEqual(ddm_to_decimal("4807.038", "N"), 48.1173, places=4)
+        self.assertAlmostEqual(ddm_to_decimal("01131.000", "W"), -11.516666, places=4)
+
+    def test_stream_fragment_status_and_recovery(self):
+        parser = StreamParser()
+        self.assertEqual(parser.feed("$GPRMC,1,2")[0].status, Status.PARTIAL_STREAM)
+        event = parser.feed(",3*00\r\n")[0]
+        self.assertEqual(event.status, Status.CORRUPTED_FRAME)
+
+    def test_can_id(self):
+        priority, pgn, source, destination = decode_can_id(0x0CF00401)
+        self.assertEqual((priority, pgn, source, destination), (3, 61444, 1, None))
+
+    def test_fast_packet_reassembly(self):
+        assembler = FastPacketAssembler(timeout=1.0)
+        can_id = 0x0CF00501
+        self.assertIsNone(assembler.feed(can_id, bytes([0, 10, 1, 2, 3, 4, 5, 6]), 0.0))
+        result = assembler.feed(can_id, bytes([1, 7, 8, 9, 10, 0, 0, 0]), 0.1)
+        self.assertEqual(result.payload, bytes(range(1, 11)))
+        self.assertIsNone(assembler.feed(can_id, bytes([0, 10, 1, 2, 3, 4, 5, 6]), 1.0))
+        with self.assertRaises(ValueError):
+            assembler.feed(can_id, bytes([1, 7, 8, 9, 10, 0, 0, 0]), 2.1)
+
+    def test_onenet(self):
+        datagram = parse_datagram(b"UdPBc 239.0.0.1\r\n$GPRMC")
+        self.assertEqual(datagram.transport_header, "UdPBc")
+        self.assertTrue(datagram.payload.startswith(b"239"))
+
+    def test_unknown_ais_type_is_decoded(self):
+        message = decode_ais("0" * 20)
+        self.assertEqual(message.message_type, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()