TUI Plan¶

Current status: canarchy tui is a full-screen Textual application with bus status, live traffic, decoded signals, J1939 activity (summary ribbon + recent table), UDS transactions, an append-only alerts log (including replay activity), and a command entry. It streams the bus live in the background, and the active Traffic, Signals, J1939, UDS, or Findings workspace uses the available body height. Tables remain sortable/filterable with an operator-controlled backlog. The full-screen + live-streaming milestone (Suggested Implementation Order items 1, 2, and 6) is now implemented; the text-mode shell and its one-shot tui --command mode have been retired. Live capture uses a cancellable background worker, retains completed or paused buffers until they are rendered, and reports received, drained, queued, dropped, and high-water counts in the status pane. Direct live DBC/J1939/UDS enrichment remains a later milestone; those panes currently consume structured events from commands that already produce them.

Because the app is full-screen it requires an interactive terminal; in a non-TTY / scripted context it prints guidance and exits non-zero. Use the individual commands (capture, decode, j1939 monitor, …) for non-interactive runs — the CLI remains the authoritative contract.

Commands and hotkeys (typed into the command entry):

/capture <iface> — start a live background capture on the interface. Exactly one interface: an empty token (/capture "") or extra arguments (/capture can0 --candump) are refused in the alerts log and leave a running capture untouched — run the full capture command for anything with flags
/stop (or the x key) — stop the live capture
/filter <pane> [text] — substring-filter a pane (traffic, decoded, j1939, uds); no text clears the filter
/sort <pane> [column] — sort a pane by column index or name (toggles direction)
/clear (or the c key) — reset every pane; this is the only slash command that discards pane data
/help — list the shared hotkey table in the alerts log; it is read-only and leaves rows, filters, counters, and the live capture untouched
/save <name>, /load <name> — session management
/dbc <ref> — inspect a DBC (local path or opendbc:<name>)
/doctor, /config — environment health / effective configuration
/quit, /exit (or the q key) — exit the TUI
Any real CANarchy command typed at the prompt runs through the shared parser and folds into the panes.

A slash command whose arguments cannot be tokenised — an unmatched quote or a dangling backslash — is reported in the alerts log; the TUI keeps running and the current view is preserved.

Keys: space pause/resume the live feed, [ / ] shrink/grow the backlog, ctrl+f maximize the focused table, arrow keys navigate rows, Alt+1–Alt+5 select workspaces, v switches Traffic between identifier summary and event log, F4 freezes inspection or returns live, F3 expands activity, and Enter inspects a complete row at narrow widths. F2 switches to the latest command result; Esc returns. Traffic filters can use the shared id==, pgn==, and sa== frame predicates; plain text remains a substring filter.

This document remains the forward-looking plan for protocol enrichment; the responsive workspace layout is implemented.

Goal¶

Define the initial TUI scope as a presentation layer over the existing CANarchy engine rather than as a separate application with its own business logic.

The TUI should help operators with live analysis, demos, and triage while preserving the project rule that the CLI remains the authoritative contract.

Constraints¶

The TUI must follow these rules:

it consumes the same structured events used by the CLI and REPL
it does not introduce protocol logic that cannot also be reached through commands
it does not invent a separate session or transport model
it triggers the same command and engine actions already exposed through the CLI
it remains deterministic enough that coding agents can reason about state transitions and outputs

This means the TUI is a view over the engine, not a second implementation of the engine.

Initial Operator Workflows¶

The first TUI milestone should support these workflows:

Watch live bus activity and confirm the interface is active.
See decoded or protocol-aware views without leaving the live traffic context.
Monitor J1939 PGN activity and source-address behavior.
Inspect recent UDS transactions during scan or trace workflows.
Review alerts, warnings, and replay activity in one place.
Execute an existing command quickly from inside the TUI.

Initial Pane Set¶

1. Bus Status¶

Purpose:

show active interface or capture source
show passive versus active mode
show session context where relevant

Data dependencies:

session state
transport status metadata
current command or workflow context

2. Live Traffic Table¶

Purpose:

show recent frames in arrival order
provide a stable raw view for quick triage

Data dependencies:

frame events

Suggested columns:

timestamp
interface
CAN ID
DLC
data

3. Decoded Signals¶

Purpose:

show decoded messages and signal values next to recent frame activity

Data dependencies:

decoded_message
signal

Suggested columns:

message name
signal name
value
units

4. J1939 Activity¶

Purpose:

give J1939-first visibility without forcing the operator back to raw IDs

Data dependencies:

j1939_pgn

Suggested columns:

PGN
source address
destination address
priority
payload summary

5. UDS Transactions¶

Purpose:

present request and response activity as transactions rather than isolated frames

Data dependencies:

uds_transaction

Suggested columns:

service
service name
request ID
response ID
ECU address
request bytes
response bytes

6. Alerts And Replay¶

Purpose:

keep warnings, active actions, and replay activity visible

Data dependencies:

alert
replay_event

7. Command Entry¶

Purpose:

provide a lightweight command launcher that routes back through the existing parser

Data dependencies:

shared command parser and command dispatch

The command entry should execute real commands, not a TUI-only command grammar.

Event Dependencies¶

The current event model is already sufficient for an initial TUI milestone:

frame
decoded_message
signal
j1939_pgn
uds_transaction
replay_event
alert

The TUI should subscribe to these events through one shared event stream abstraction.

The TUI should not need protocol-specific adapters that bypass the engine.

State Model¶

The TUI should keep a thin UI state layer only for presentation concerns such as:

selected pane
current filters and sort order
focused row or selected event
visible time window or backlog size
command entry draft

It should rely on the existing application state for:

session context
active interface
loaded DBC path
current capture source
protocol-aware events

Non-Goals For The First TUI Milestone¶

Do not add these in the first pass:

TUI-only protocol workflows
a separate plugin or extension layer just for the TUI
custom transport backends that only the TUI can use
complex multi-window terminal orchestration
feature parity with mature CAN dashboards before the shared event model is fully exercised

Suggested Implementation Order¶

Expand the event subscription boundary used by CLI, REPL, and TUI for background live updates.
Build on the shipped TUI shell with richer bus status, live traffic, and alerts presentation.
Add decoded signal and J1939 panes.
Add the UDS transaction pane.
Extend command entry with better session-aware context display.
Add pane-level filtering, focus handling, and backlog/window controls.

Acceptance Mapping¶

This plan satisfies the issue goals by making these points explicit:

the TUI scope and constraints are documented
the initial pane list and event dependencies are clear
follow-on implementation can proceed without inventing separate domain logic