pgntui 0.1.2__py3-none-any.whl

pgntui/__init__.py

@@ -0,0 +1,3 @@
+"""pgntui — NMEA 2000 TUI."""
+
+__version__ = "0.1.2"

pgntui/__main__.py

@@ -0,0 +1,55 @@
+"""CLI entry point for pgntui."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from pgntui.config import load_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="pgntui", description="NMEA 2000 terminal UI")
+    p.add_argument("--workspace", default=None, help="override workspace directory")
+    p.add_argument("--enable-write", action="store_true", help="enable writes")
+    sub = p.add_subparsers(dest="command")
+    replay = sub.add_parser("replay", help="replay a .pgnlog file")
+    replay.add_argument("replay_file")
+    return p
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    return build_parser().parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    workspace = (
+        Path(args.workspace).expanduser()
+        if args.workspace
+        else Path("~/.config/pgntui").expanduser()
+    )
+    cfg_path = workspace / "config.toml"
+    cfg = load_config(cfg_path)
+    if args.enable_write:
+        # Re-create with write_enabled flipped on
+        cfg = type(cfg)(
+            driver_name=cfg.driver_name,
+            driver_options=cfg.driver_options,
+            write_enabled=True,
+            theme=cfg.theme,
+            workspace=workspace,
+            csv_dir=cfg.csv_dir,
+            record_dir=cfg.record_dir,
+        )
+    if args.command == "replay":
+        # Replay mode is bootstrapped here in a later integration step.
+        print(f"replay: {args.replay_file} (workspace={workspace}, theme={cfg.theme})")
+        return 0
+    print(f"pgntui: workspace={workspace} theme={cfg.theme} write_enabled={cfg.write_enabled}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pgntui/app.py

@@ -0,0 +1,67 @@
+"""Textual app shell — tabs, hotkey strip, status bar."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Header, Static, TabbedContent, TabPane
+
+from pgntui.themes.loader import Theme, to_textual_css
+
+
+class PgntuiApp(App[None]):
+    CSS = ""
+
+    BINDINGS = [
+        ("tab", "next_container", "Next"),
+        ("shift+tab", "prev_container", "Prev"),
+        ("d", "show_debug", "Debug"),
+        ("r", "toggle_record", "Record"),
+        ("q", "quit", "Quit"),
+        ("question_mark", "help", "Help"),
+    ]
+
+    def __init__(self, theme: Theme, container_titles: list[str]) -> None:
+        super().__init__()
+        self._theme = theme
+        self._container_titles = container_titles
+
+    def on_mount(self) -> None:
+        self.stylesheet.add_source(to_textual_css(self._theme), read_from=("theme", "theme"))
+        self.stylesheet.parse()
+        self.refresh_css()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical():
+            with TabbedContent(id="tabs"):
+                for title in self._container_titles:
+                    with TabPane(title):
+                        yield Static(title, classes="signal-title")
+                with TabPane("Debug", id="debug"):
+                    yield Static("debug placeholder")
+            yield Static("[Tab] Next [D] Debug [R] Rec [Q] Quit", id="hotkey-strip")
+            yield Static("status: idle", id="status-bar")
+
+    def action_next_container(self) -> None:
+        tabs = self.query_one(TabbedContent)
+        tabs.action_next_tab()  # type: ignore[attr-defined]  # Textual provides at runtime
+
+    def action_prev_container(self) -> None:
+        tabs = self.query_one(TabbedContent)
+        tabs.action_previous_tab()  # type: ignore[attr-defined]  # Textual provides at runtime
+
+    def action_show_debug(self) -> None:
+        tabs = self.query_one(TabbedContent)
+        tabs.active = "debug"
+
+    def action_toggle_record(self) -> None:
+        status = self.query_one("#status-bar", Static)
+        status.update("status: REC")
+
+    def action_help(self) -> None:
+        status = self.query_one("#status-bar", Static)
+        status.update("help: Tab/D/R/Q")
+
+
+__all__ = ["PgntuiApp"]

pgntui/config.py

@@ -0,0 +1,42 @@
+"""TOML config loader."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    driver_name: str = "file-replay"
+    driver_options: dict[str, Any] = field(default_factory=dict)
+    write_enabled: bool = False
+    theme: str = "dark"
+    workspace: Path = Path("~/.config/pgntui")
+    csv_dir: str = "logs"
+    record_dir: str = "recordings"
+
+
+def load_config(path: Path) -> Config:
+    path = Path(path)
+    if not path.exists():
+        return Config()
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    driver = data.get("driver", {})
+    app = data.get("app", {})
+    logging_cfg = data.get("logging", {})
+    driver_opts = {k: v for k, v in driver.items() if k != "name"}
+    return Config(
+        driver_name=driver.get("name", "file-replay"),
+        driver_options=driver_opts,
+        write_enabled=bool(app.get("write_enabled", False)),
+        theme=app.get("theme", "dark"),
+        workspace=Path(app.get("workspace", "~/.config/pgntui")).expanduser(),
+        csv_dir=logging_cfg.get("csv_dir", "logs"),
+        record_dir=logging_cfg.get("record_dir", "recordings"),
+    )
+
+
+__all__ = ["Config", "load_config"]

pgntui/containers/loader.py

@@ -0,0 +1,59 @@
+"""Container JSON loader."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ContainerLoadError(ValueError):
+    """Raised when a container JSON document is invalid."""
+
+
+@dataclass(frozen=True, slots=True)
+class SignalPlacement:
+    ref: str
+    row: int
+    col: int
+    w: int
+
+
+@dataclass(frozen=True, slots=True)
+class Container:
+    id: str
+    title: str
+    cols: int
+    signals: list[SignalPlacement]
+
+
+def load_container(path: Path, known_signal_ids: set[str]) -> Container:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ContainerLoadError(f"{path}: invalid JSON: {e}") from e
+    try:
+        cid = payload["id"]
+        title = payload["title"]
+    except KeyError as e:
+        raise ContainerLoadError(f"{path}: missing key {e}") from e
+    cols = int(payload.get("cols", 12))
+    if cols <= 0:
+        raise ContainerLoadError(f"{path}: cols must be positive")
+    placements: list[SignalPlacement] = []
+    for item in payload.get("signals", []):
+        ref = item["ref"]
+        if ref not in known_signal_ids:
+            raise ContainerLoadError(f"{path}: unknown signal ref {ref!r}")
+        row = int(item["row"])
+        col = int(item["col"])
+        w = int(item["w"])
+        if row < 0 or col < 0 or w <= 0:
+            raise ContainerLoadError(f"{path}: ref {ref!r} has invalid geometry")
+        if col + w > cols:
+            raise ContainerLoadError(f"{path}: ref {ref!r} overflows grid (cols={cols})")
+        placements.append(SignalPlacement(ref=ref, row=row, col=col, w=w))
+    return Container(id=cid, title=title, cols=cols, signals=placements)
+
+
+__all__ = ["Container", "ContainerLoadError", "SignalPlacement", "load_container"]

pgntui/containers/screen.py

@@ -0,0 +1,60 @@
+"""ContainerScreen — renders a Container's grid of signal widgets."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Grid
+from textual.screen import Screen
+from textual.widget import Widget
+
+from pgntui.containers.loader import Container
+from pgntui.signals.base import AnalogIn, AnalogOut, DigitalIn, DigitalOut, Signal
+from pgntui.signals.widgets import (
+    AnalogInWidget,
+    AnalogOutWidget,
+    DigitalInWidget,
+    DigitalOutWidget,
+)
+
+
+class ContainerScreen(Screen[None]):
+    def __init__(
+        self,
+        container: Container,
+        signals: dict[str, Signal],
+        write_enabled: bool,
+    ) -> None:
+        super().__init__()
+        self.container_def = container
+        self.signals = signals
+        self.write_enabled = write_enabled
+        self.widgets: dict[str, Widget] = {}
+
+    def compose(self) -> ComposeResult:
+        grid = Grid(id="container-grid")
+        grid.styles.grid_size_columns = self.container_def.cols
+        for placement in self.container_def.signals:
+            sig = self.signals[placement.ref]
+            w = self._make_widget(sig)
+            w.styles.column_span = placement.w
+            self.widgets[placement.ref] = w
+        yield grid
+
+    def on_mount(self) -> None:
+        grid = self.query_one(Grid)
+        for w in self.widgets.values():
+            grid.mount(w)
+
+    def _make_widget(self, sig: Signal) -> Widget:
+        if isinstance(sig, AnalogIn):
+            return AnalogInWidget(sig)
+        if isinstance(sig, AnalogOut):
+            return AnalogOutWidget(sig, write_enabled=self.write_enabled)
+        if isinstance(sig, DigitalIn):
+            return DigitalInWidget(sig)
+        if isinstance(sig, DigitalOut):
+            return DigitalOutWidget(sig, write_enabled=self.write_enabled)
+        raise TypeError(f"Unknown signal type: {type(sig).__name__}")
+
+
+__all__ = ["ContainerScreen"]

pgntui/debug/tab.py

@@ -0,0 +1,46 @@
+"""Debug tab — scrolling decoded-frame buffer with filters."""
+
+from __future__ import annotations
+
+from collections import deque
+
+from pgntui.decode.canboat import DecodedFrame
+
+
+class DebugBuffer:
+    def __init__(
+        self,
+        max_rows: int = 1000,
+        pgn_filter: set[int] | None = None,
+        source_filter: set[int] | None = None,
+        show_raw_hex: bool = False,
+    ) -> None:
+        self._rows: deque[DecodedFrame] = deque(maxlen=max_rows)
+        self.paused = False
+        self.pgn_filter = pgn_filter
+        self.source_filter = source_filter
+        self.show_raw_hex = show_raw_hex
+
+    def push(self, df: DecodedFrame) -> None:
+        if self.paused:
+            return
+        if self.pgn_filter is not None and df.pgn not in self.pgn_filter:
+            return
+        if self.source_filter is not None and df.source_addr not in self.source_filter:
+            return
+        self._rows.append(df)
+
+    def rows(self) -> list[DecodedFrame]:
+        return list(self._rows)
+
+    def clear(self) -> None:
+        self._rows.clear()
+
+    def toggle_pause(self) -> None:
+        self.paused = not self.paused
+
+    def toggle_raw_hex(self) -> None:
+        self.show_raw_hex = not self.show_raw_hex
+
+
+__all__ = ["DebugBuffer"]

pgntui/decode/canboat.py

@@ -0,0 +1,111 @@
+"""Thin wrapper around the bundled canboat pgns.json database."""
+
+from __future__ import annotations
+
+import json
+import struct  # noqa: F401  (retained for future tasks)
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Any
+
+from pgntui.drivers.base import Frame
+
+
+@dataclass(frozen=True, slots=True)
+class DecodedFrame:
+    timestamp: float
+    source_addr: int
+    pgn: int
+    name: str | None
+    fields: dict[str, Any] = field(default_factory=dict)
+
+
+# Aliases for field names that conventional tools (signalk etc.) expose
+# differently from the bare canboat `Name`. Keyed by (pgn, canboat field name).
+_FIELD_ALIASES: dict[tuple[int, str], str] = {
+    (127488, "Speed"): "Engine Speed",
+    (127488, "Boost Pressure"): "Engine Boost Pressure",
+    (127488, "Tilt/Trim"): "Engine Tilt/Trim",
+}
+
+
+class CanboatDecoder:
+    def __init__(self, db: dict[str, Any]) -> None:
+        self._db = db
+        pgn_list = db.get("PGNs") or db.get("pgns") or []
+        self._by_pgn: dict[int, list[dict[str, Any]]] = {}
+        for entry in pgn_list:
+            pgn = int(entry.get("PGN") or entry.get("pgn") or 0)
+            if pgn:
+                self._by_pgn.setdefault(pgn, []).append(entry)
+
+    @classmethod
+    def load_bundled(cls) -> CanboatDecoder:
+        with (
+            resources.files("pgntui.decode").joinpath("pgns.json").open("r", encoding="utf-8") as fh
+        ):
+            return cls(json.load(fh))
+
+    def has_pgn(self, pgn: int) -> bool:
+        return pgn in self._by_pgn
+
+    def decode(self, frame: Frame) -> DecodedFrame | None:
+        entries = self._by_pgn.get(frame.pgn)
+        if not entries:
+            return None
+        entry = entries[0]
+        fields = self._decode_fields(entry, frame.data, frame.pgn)
+        return DecodedFrame(
+            timestamp=frame.timestamp,
+            source_addr=frame.source_addr,
+            pgn=frame.pgn,
+            name=entry.get("Description") or entry.get("Id"),
+            fields=fields,
+        )
+
+    def _decode_fields(self, entry: dict[str, Any], data: bytes, pgn: int) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        bit_offset = 0
+        for f in entry.get("Fields", []) or entry.get("fields", []) or []:
+            size = int(
+                f.get("BitLength") or f.get("bitLength") or f.get("Length") or f.get("length") or 0
+            )
+            if size <= 0:
+                continue
+            name = f.get("Name") or f.get("name") or "?"
+            raw = _read_bits(data, bit_offset, size)
+            resolution_raw = f.get("Resolution")
+            if resolution_raw is None:
+                resolution_raw = f.get("resolution")
+            try:
+                resolution = float(resolution_raw) if resolution_raw is not None else 1.0
+            except (TypeError, ValueError):
+                resolution = 1.0
+            if resolution == 0:
+                resolution = 1.0
+            signed = bool(f.get("Signed") or f.get("signed"))
+            if signed and raw >= (1 << (size - 1)):
+                raw -= 1 << size
+            value: Any = raw * resolution if resolution != 1.0 else raw
+            out[name] = value
+            alias = _FIELD_ALIASES.get((pgn, name))
+            if alias:
+                out[alias] = value
+            bit_offset += size
+        return out
+
+
+def _read_bits(data: bytes, offset: int, length: int) -> int:
+    result = 0
+    for i in range(length):
+        bit_index = offset + i
+        byte_index = bit_index // 8
+        bit_in_byte = bit_index % 8
+        if byte_index >= len(data):
+            break
+        bit = (data[byte_index] >> bit_in_byte) & 1
+        result |= bit << i
+    return result
+
+
+__all__ = ["CanboatDecoder", "DecodedFrame"]