Files

François 90502c0762 Dashboard + palette + analyze screen; consolidated categorization rules.

UI restructuring:

- Dashboard (`screen_dashboard.cpp`, `screen_idx = 6`) is the new home
  screen at boot. Reads Overview / Health / Analysis / Modules from
  the current System every frame; per-module rows list parts grouped
  by `connector_type` and a Power/Gnd inference summary (yellow when
  any name-Power signal is refuted). Scrollable via PgUp/PgDn/Home/End.
  Letter shortcuts: `c`=console, `s`=search, `p`=plug (alias of
  connect), `t`=set-type, `e`=explore, `n`=net, `a`=analyze, `q`=quit.
- Global Ctrl-P palette (`screen_palette.cpp`) — fuzzy-finds over
  registered commands + module / signal names. Activation runs the
  bare command or jumps to the matching screen with state seeded.
- Unified analyze screen (`screen_analyze.cpp`, `screen_idx = 7`):
  tabbed layout (`Issues / Groups / Types`), Tab or ←→ to switch
  tabs, ↑/↓ to navigate the focused list. Replaces the previous
  shell-bouncing `[v]erify` shortcut — `verify` content is now in
  the Issues tab. Types tab attaches the decision rationale to each
  signal row (fan-out / voltage / hard floor).
- Context help panel: `RenderHelpPanel(title, entries)` in
  `tui_helpers.{hpp,cpp}` rendered on the right of every screen.
- Console (former "log") rename: screen 0 is `[c]onsole` in the UI
  and "console" in its help-panel title. The underlying screen and
  the shell prompt are unchanged.
- Esc from any non-home screen returns to the dashboard. The
  dashboard itself swallows Esc; quit via `q` / the `quit` command.
  `quit` now calls `screen_ptr->Exit()` directly so it works from
  any screen including via the palette.

Signal type inference:

- `Signal::type` defaults to `Other` — auto-inference no longer
  happens at construction.
- `infer_signal_types(System*)` is called at the end of every load.
  Three rules: GndShield from name alone; Power requires name match
  + a hard fan-out floor (< 3 pins = always Other, regardless of
  name or voltage) + at least one positive structural signal
  (fan-out ≥ 4 OR voltage pattern in the name like `3V3`, `5V`).
- Thresholds exposed in `analysis.hpp` (`POWER_FANOUT_HARD_FLOOR`,
  `POWER_FANOUT_CONFIRM_MIN`, `has_voltage_pattern`) so the analyze
  screen can render the same rationale without duplicating logic.
- `set-signal-type` still wins; save/restore round-trips the type.

Analysis groups & anomalies:

- New `GroupKind::DiffBus` — ≥ 2 diff pairs sharing the same
  outer-stem with consecutive integer indices are aggregated into a
  single bus (`MDI[0..3]_P/N`). `MDI0` and `PCIE_TX_0` index forms
  both accepted. Solo pairs under a bus-able stem fall back to
  `DiffPair`.
- New `AnomalyKind::DiffBusGap` for missing lanes.

Documentation:

- `DESIGN.md`: dedicated "Categorization rules (normative)" section
  consolidating signal type, NC origin, signal groups, anomalies,
  component kind, and connector wiring rules with exact thresholds
  and decision order.
- `doc/user/analysis.md` (new): user-facing version of the same
  rules in plain language. Linked from `doc/user/index.md`.

Tests: +6 new cases (62 total). Adjusted `test_persist.cpp` to set
the signal type explicitly in the fixture (no more auto-inference).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-14 20:23:33 +02:00

4.1 KiB

Raw Blame History

essim — user guide

A short, task-oriented introduction to using essim. For an exhaustive reference of every command, see commands.md (auto- generated from the binary). For scripting and $variable expansion, see scripting.md.

What essim is

A digital twin for the inter-card connections inside a system. You load modules (cards/boards) from netlist or pinout files, tag their connectors with a connector_type, connect them across modules, and verify that the signal types match the connector role expectations. You can save a snapshot, restore it later, or replay a session as a script.

┌──────────┐    ┌──────────┐
│ Module A │    │ Module B │
│  Part J1 │◀──▶│  Part P1 │   <— a Connection (built by `connect`)
│   pins   │    │   pins   │
└──────────┘    └──────────┘

First session

After launching ./build/essim, the prompt accepts a sequence of commands. The most common bring-up looks like this:

> new
> load backplane /path/to/netlists/backplane.NET altium
> load payload1  /path/to/netlists/payload.qcv mentor
> set-type backplane J20 vpx-3u-bkp-p0
> set-type payload1  P0  vpx-3u-payload-p0
> connect backplane J20 payload1 P0
> verify
> save my-system.essim

Things to try at any time:

Action	How
List every command	`help`
Help on one command	`help <name>`
Scroll back through output	`PageUp` / `PageDown`, `Home`, `End`
Re-run a previous command	↑ / ↓ (also `history` is on disk)
Tab-complete a command name	`set‹Tab›` → `set-type` etc.
Cancel a multi-step prompt	`Esc`
Leave essim	`quit` (or `exit`)

Interactive screens

Some commands open a dedicated full-screen layout when invoked with no arguments (the help listing tags these [interactive]). They all share the same conventions:

A title bar essim → <name> — <short description> is shown at the top.
Tab cycles focus between fields; the active field's label flips to reverse video so it's obvious where the next keystroke goes.
Esc leaves the screen and returns to the main prompt.
The screens are user-facing only — they are never allowed inside a sourced script. A sourced script must use the inline form of these commands instead.

Today's interactive screens: connect, search, set-type, explore, net. See commands.md for each.

Saving, restoring, replaying

Three orthogonal mechanisms persist your work:

save <file> writes a binary-tab-delimited snapshot of the whole system (modules, parts, signals, connector types, signal-type overrides, connections, pin maps). restore <file> replaces the current system with the snapshot.
script-save <file> writes a replay-ready text script of every command issued since the last new. The interactive bits and the noisy commands (clear, help, …) are filtered out automatically.
source <file> reads a script line by line. Comments start with #, blank lines are skipped, leading ~/ in paths is expanded, and while a script is running a centred "Computing…" modal shows the progress (one line per ~30 ms tick).

A typical workflow: experiment in the shell, script-save the part that works, hand-edit the script to introduce $variables (see scripting.md), then source it whenever you start fresh.

Where to look next

commands.md — exhaustive command reference, regenerated from the binary on every cmake --build build --target doc.
analysis.md — how essim classifies signals (Power / Gnd / Other), how it detects buses and diff pairs, what the analyze screen actually reports and why.
scripting.md — set / $var / ${var}, source semantics, the script-save denylist.
DESIGN.md — implementation notes, useful if you want to add a command or a screen.
../api/ — auto-generated C++ API reference.

4.1 KiB Raw Blame History Unescape Escape