Files

François 792e4745d3 Merge search and net screens into explore; drop both commands.

`explore` was already a superset of `search` (4 columns: module → type
→ filtered children → detail, with parts/signals/connections — vs
search's 2 columns of parts/signals only). It now also subsumes the
former `net` screen: when a signal entry is selected, the detail pane
shows the local pins followed by a `Net members (across connections)`
section listing every `(module, signal, type)` reachable through the
BFS over `Connection::pin_map`, with the count + dominant type and an
INCONSISTENT flag in the signal-detail header.

Removed:
- `src/tui/screen_search.cpp`, `src/tui/screen_net.cpp`.
- `commands["search"]`, `commands["net"]` (including its textual
  inline form). The `find_net` / `Net` API stays for explore's BFS
  panel and the analyze screen's net-mix check.
- `[s]` and `[n]` letter shortcuts on the dashboard.
- `net_*` and `search_*` state members + builders + constructor
  inits.

screen_idx renumbering (the slots vacated by search + net are
removed, not left dead):
  0 = console  (unchanged)
  1 = connect
  2 = set-connector-type
  3 = explore  (unchanged number, but now subsumes search + net)
  4 = dashboard (boot)
  5 = analyze

Palette signal items now jump to `explore` prefilled on the signals
tab with the child filter seeded to the exact signal name; the BFS
section in the detail pane is what shows the cross-module net.

Net-member rows in the detail pane are deliberately read-only for
now (Enter is a no-op): the signal-type popup is scoped to the
currently selected module, so opening it on a peer-module member
would mis-fire. Cross-module Enter navigation can come later if
needed.

DESIGN.md and user docs updated accordingly.

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

2026-05-14 21:49:26 +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-connector-type backplane J20 vpx-3u-bkp-p0
> set-connector-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-connector-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, set-connector-type, explore, analyze. 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