Metadata-Version: 2.4
Name: pgntui
Version: 0.6.37
Summary: Cross-platform TUI for NMEA 2000 with canboat decoding and pluggable drivers
Project-URL: Homepage, https://github.com/phobicdotno/pgntui
Project-URL: Source, https://github.com/phobicdotno/pgntui
Project-URL: Bug Tracker, https://github.com/phobicdotno/pgntui/issues
Project-URL: Changelog, https://github.com/phobicdotno/pgntui/releases
Author: Karstein Kvistad (phobicdotno)
License: MIT License
        
        Copyright (c) 2026 Karstein Kvistad (phobicdotno)
        
        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.
License-File: LICENSE
Keywords: canboat,marine,n2k,nmea2000,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console :: Curses
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyserial>=3.5
Requires-Dist: textual>=8.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: dist
Requires-Dist: pyinstaller>=6.6; extra == 'dist'
Description-Content-Type: text/markdown

# pgntui

Cross-platform TUI for NMEA 2000 with canboat decoding.

Read live N2K frames through pluggable drivers, decode them with the
canboat PGN database, and route values into JSON-defined dashboards. Record
sessions to `.pgnlog` and replay them later — no boat required.

![pgntui dashboard](docs/screenshots/dashboard.png)

Expand any signal (`[+]`) to reveal its sparkline; set the sparkline height
from the Settings menu, and browse/play recordings from File → Open recording.

| Settings menu | Open recording |
| --- | --- |
| ![Settings menu](docs/screenshots/settings-menu.png) | ![Open recording](docs/screenshots/open-recording.png) |

## Install

The easiest path is `pipx`:

    pipx install pgntui

Don't have `pipx`? Install it with pip, then make sure it is on PATH:

    python -m pip install --user pipx
    python -m pipx ensurepath

Open a new terminal afterwards so the PATH change takes effect. On
Debian/Ubuntu you can use `sudo apt install pipx` instead, and on macOS
`brew install pipx`.

If your system Python is older than 3.11, point pipx at a newer interpreter:

    pipx install --python python3.12 pgntui

Or run in a project venv:

    python3 -m venv .venv && . .venv/bin/activate
    pip install pgntui

Standalone single-file binaries for macOS (arm64, x86_64), Linux (x86_64) and
Windows (x86_64) are attached to each GitHub release.

## Quickstart

Scaffold the example workspace and launch:

    pgntui --example      # writes the example workspace at the OS default location
    pgntui                # opens the TUI; no driver yet, debug tab will be empty

Replay a recording:

    pgntui replay path/to/session.pgnlog

Run with a real driver — pgntui picks the driver named in `config.toml`:

    pgntui                # uses driver.name from <workspace>/config.toml

## Workspace layout

`pgntui` reads everything from a workspace directory. By default the location
follows `platformdirs.user_config_dir("pgntui")`:

| OS      | Default workspace                          |
|---------|--------------------------------------------|
| Linux   | `~/.config/pgntui`                         |
| macOS   | `~/Library/Application Support/pgntui`     |
| Windows | `%LOCALAPPDATA%\pgntui\pgntui`             |

(On Windows `platformdirs` nests `<appauthor>\<appname>`, so the path segment
`pgntui` appears twice — e.g. `C:\Users\you\AppData\Local\pgntui\pgntui`.)

Override with `--workspace <path>` on the command line.

Layout:

    <workspace>/
      config.toml            # driver + theme + paths
      signals/*.json         # signal definitions (PGN -> field -> widget)
      containers/*.json      # dashboard layouts (tab -> grid of signals)
      recordings/            # .pgnlog files written by the R hotkey
      logs/                  # CSV exports

Run `pgntui --example` to drop a working sample inside this directory.

## JSON library

[`library/`](library/) in the repo ships ready-made signal + container sets
for one tab per NMEA Simulator page — GPS, Environmental, Boat, Batteries,
Engine (main / status / transmission), Tanks, Binary, DC and Charge, AC,
Windlass, Thruster. Copy the pages you want into your workspace:

    cp library/gps/signals/*.json      <workspace>/signals/
    cp library/gps/containers/*.json   <workspace>/containers/

See [`library/README.md`](library/README.md) for the page list and unit
conventions.

## Drivers

Built-in driver entry points (`pgntui.drivers`):

- `actisense-ngt1` — Actisense NGT-1 USB serial gateway (`pyserial`)
- `file-replay` — replay an Actisense `.pgnlog` capture

Pick one in `config.toml`:

    [driver]
    name = "actisense-ngt1"
    port = "/dev/tty.usbserial-XXXX"   # macOS / Linux
    # port = "COM4"                    # Windows
    baud = 115200

Third-party drivers can register additional entry points under the
`pgntui.drivers` group.

### Actisense NGT-1

The NGT-1 is a USB↔NMEA 2000 gateway. The easiest path is the in-app
**Connection** menu — run `pgntui`, press `C` (or click **Connection** in the
title bar), pick the port and speed, and press **Test** to confirm it's
receiving. **Save** writes the choice to `config.toml`; **Connect** goes live
without a restart.

Prefer the command line? Find the port and test it there:

    pgntui --list-ports          # list serial ports
    pgntui probe --port COM4     # 2-second connection test + verdict

Then set `driver.name = "actisense-ngt1"` and `driver.port` in `config.toml`
(`COM4` on Windows, `/dev/ttyUSB0` on Linux, `/dev/tty.usbserial-XXXX` on
macOS) and run `pgntui` — incoming PGNs scroll on the Debug tab and feed the
dashboards. The driver speaks the Actisense BST serial protocol
(`DLE STX`…`DLE ETX` framing, `0x93` receive / `0x94` send). Writes
(`analog_out`/`digital_out`) additionally need `--enable-write` and
`app.write_enabled = true`.

## Signal types

Signal JSON files declare how each PGN field renders:

- `analog_in` — gauge / numeric readout (RPM, speed, depth, temperature)
- `digital_in` — boolean lamp (alarm, anchor light, bilge pump state)
- `analog_out` — write-back analog control (sends an outbound frame)
- `digital_out` — write-back toggle (sends an outbound frame)

`analog_out` and `digital_out` need `--enable-write` on the CLI **and**
`app.write_enabled = true` in `config.toml`; otherwise they render as
read-only.

## Themes

Six builtins ship in the wheel:

- `dark` (default)
- `light`
- `amber-crt`
- `green-phosphor`
- `mono-ascii`
- `rainbow-disco`

Custom themes are JSON files referenced from `config.toml`:

    [app]
    theme = "dark"

## Replay

Replay an Actisense-format `.pgnlog`:

    pgntui replay capture.pgnlog

The replay driver respects the original frame spacing. Press the `R` hotkey
inside the TUI to start/stop recording the live stream to a new
`.pgnlog` file under `<workspace>/recordings/`.

## Hotkeys

    Tab / Shift+Tab     next / previous container tab
    D                   jump to Debug tab
    R                   start / stop recording
    C                   open the Connection menu (NGT-1 port / speed / test)
    A                   show the About dialog
    Q / Ctrl+Q          quit immediately
    ?                   show help line in status bar

## Layout sketch

```
+---------------------------------------------------+
|  pgntui                                           |
+---------------------------------------------------+
| [Main] [Engine] [Nav] [Debug]                     |
+---------------------------------------------------+
|  RPM     1450    Speed   6.8 kn   Depth 12.3 m    |
|  +----+         +----+           +----+           |
|  |####|         |##  |           |#   |           |
|  +----+         +----+           +----+           |
|                                                   |
|  Bilge OFF     Anchor Light ON                    |
+---------------------------------------------------+
| [Tab] Next  [D] Debug  [R] Rec  [Q] Quit          |
| status: idle                                      |
+---------------------------------------------------+
```

## Status

Early days — expect rough edges. Solid enough to use for real on a boat whose
NMEA 2000 network you already trust, or on a test-bench setup.

- Works: TUI shell, canboat decoder, signal routing, file replay,
  Actisense NGT-1 driver (read), recording.
- Partial: NGT-1 write-back is wired but field-tested only against a tiny
  PGN subset.
- Not yet: TwoCAN / Yacht Devices native drivers, more layout primitives,
  per-signal alarm thresholds in the UI.

Bug reports and patches welcome — file an issue at
<https://github.com/phobicdotno/pgntui/issues>.

## License

MIT. See [LICENSE](LICENSE).

## Links

- Source: <https://github.com/phobicdotno/pgntui>
- Issues: <https://github.com/phobicdotno/pgntui/issues>
- Releases: <https://github.com/phobicdotno/pgntui/releases>
