François
792e4745d3
`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>
104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# essim — user guide
|
||
|
||
A short, task-oriented introduction to using essim. For an exhaustive
|
||
reference of every command, see [`commands.md`](commands.md) (auto-
|
||
generated from the binary). For scripting and `$variable` expansion,
|
||
see [`scripting.md`](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:
|
||
|
||
```text
|
||
> 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`](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`](scripting.md)), then `source` it whenever you start
|
||
fresh.
|
||
|
||
## Where to look next
|
||
|
||
- [`commands.md`](commands.md) — exhaustive command reference,
|
||
regenerated from the binary on every `cmake --build build --target doc`.
|
||
- [`analysis.md`](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`](scripting.md) — `set` / `$var` / `${var}`, `source`
|
||
semantics, the script-save denylist.
|
||
- [`DESIGN.md`](../../DESIGN.md) — implementation notes, useful if
|
||
you want to add a command or a screen.
|
||
- [`../api/`](../api/) — auto-generated C++ API reference.
|