electronics/essim
1
0
Fork 0
Code Issues 3 Pull Requests Packages Releases Wiki Activity

User-facing docs: --commands-md flag, doc/user/ tree, anonymised script.

Browse Source 
- `essim --commands-md [file]` instantiates the Tui, calls
  `Tui::DumpCommandsMd(ostream&)` which iterates the live registry and
  emits Markdown grouped by interactive/other, then exits. Single
  source of truth: a new `CommandSpec` field surfaces automatically.
- CMake `doc` target now `DEPENDS essim` and chains:
    doxygen → gen_api_md.py → doc/api/
    essim --commands-md      → doc/user/commands.md
- `doc/user/` adds:
    - index.md (hand-written) — first session, interactive-screen
      conventions, save/restore/replay overview.
    - scripting.md (hand-written) — `set`/`$var` expansion semantics,
      `source` event-paced execution, script-save denylist, worked
      example pointing at test/system.essim.
    - commands.md (auto-generated, regenerated by the `doc` target).
- Top-level README refocused on quick start; pointers to the new
  doc tree (user/, api/, DESIGN.md) instead of an inline command table.
- doc/README.md and DESIGN.md document the two-pipeline doc workflow.
- `test/system.essim` and user docs anonymised: bkp → backplane,
  vdn1/2/3 → payload1/2/3, cb3p → payload4, bpb/cob/ssu →
  peripheral1/2/3; netlist file names + variable names + paths all
  replaced with generic equivalents.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Foué
2026-05-12 08:29:45 +02:00
parent 66460262af
commit 043fef0a31
16 changed files with 825 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
README.md
View File

@@ -1,10 +1,13 @@
# essim — system digital twin
Interactive simulator for the interconnections between cards in a system. Built around a domain model of **modules → parts → pins / signals → connections**, with importers for Mentor Graphics and ODS pinout sheets, and a TUI shell for browsing, search, connection authoring, scripting, and snapshot save/restore.
Interactive simulator for the inter-card connections inside a system. Built
around a domain model of **modules → parts → pins / signals → connections**,
with importers for Mentor Graphics, Altium and ODS pinout sheets, a TUI shell
with scripting, snapshots and BFS net analysis.
Status: early work-in-progress.
## Build
## Quick start
```sh
cmake -S . -B build
@@ -17,9 +20,15 @@ Requirements:
- A C++17 compiler.
- CMake 3.14+.
- System packages: `libzip` and `pugixml` (Arch: `pacman -S libzip pugixml`).
- FTXUI (v6.1.9) and doctest (v2.4.11) are fetched at configure time via `FetchContent`.
- FTXUI (v6.1.9) and doctest (v2.4.11) are fetched at configure time via
`FetchContent`.
To run the test suite:
Inside the shell, type `help` for the live command list — or read the
auto-generated reference at [`doc/user/commands.md`](doc/user/commands.md).
A worked bring-up script is at [`test/system.essim`](test/system.essim);
load it with `source test/system.essim`.
## Tests
```sh
./build/essim_tests
@@ -27,77 +36,39 @@ To run the test suite:
ctest --test-dir build
```
To skip building tests:
Skip building tests entirely:
```sh
cmake -S . -B build -DBUILD_TESTING=OFF
```
## TUI commands
## Documentation
Type `help` inside the shell for the live list, or `help <name>` for the per-command synopsis. At a glance:
- [`doc/user/`](doc/user/) — user guide, command reference, scripting.
- [`doc/api/`](doc/api/) — auto-generated C++ API reference.
- [`DESIGN.md`](DESIGN.md) — implementation notes (domain conventions, TUI
internals, gotchas).
- [`doc/README.md`](doc/README.md) — how the doc pipeline is wired.
| Command | Purpose |
|---|---|
| `new` | create a new (empty) system; resets the script-save buffer |
| `load <module> <file> <mentor\|altium\|ods>` | load a module from a netlist / pinout file |
| `save <file>` / `restore <file>` | snapshot the current system / replace it from a snapshot |
| `source <file>` | replay a file of commands (interactive ones rejected) |
| `script-save <file>` | dump commands run since last `new` as a replay-ready script |
| `set-type` | tag a part's connector type (interactive screen if no args) |
| `set-signal-type <module> <signal> <power\|gnd\|other>` | override the auto-detected signal type |
| `connect` | connect a part across two modules (interactive screen if no args) |
| `search` | live-filter parts/signals (interactive screen if no args) |
| `explore` | browse modules → parts/signals/connections → details |
| `verify` | report pins whose connected signal type doesn't match the connector role |
Regenerate auto-generated parts after substantive code changes:
Persistent command history lives at `$XDG_DATA_HOME/essim/history` (or `%LOCALAPPDATA%\essim\history` on Windows once ported).
## Tests
Layered with [doctest](https://github.com/doctest/doctest):
- **Unit tests** on pure helpers: tokenizer, natural-order comparator, longest common prefix, signal-type heuristics, VPX transform mapping.
- **Round-trip tests** on the persist layer: a synthetic system is built in code, saved, restored, and compared field by field (modules, parts, connector types, NC pins, signal-type overrides, connections + `pin_map`).
```sh
cmake --build build --target doc # needs doxygen + python3
```
## Project layout
```
src/
main.cpp — launches Tui
system/ — domain model
syselmts.hpp SystemElement + SystemElementContainer<T>
modules.{hpp,cpp} Module, Modules
parts.{hpp,cpp} Part, Parts
pins.{hpp,cpp} Pin, Pins
signals.{hpp,cpp} Signal, Signals (auto-typed at construction)
signal_type.hpp SignalType + helpers
connect.{hpp,cpp} Connection (endpoints + pin_map + transform_name)
transform.{hpp,cpp} Transform / IdentityTransform / TransformRegistry
transform_vpx.{hpp,cpp} 3U-VPX-specific transforms (3 connector pairs)
pin_role.{hpp,cpp} per-(connector_type, pin) expected SignalType
persist.{hpp,cpp} save / restore (tab-delimited)
system.{hpp,cpp} System: owns Modules + Connections
imports/ — adapters that populate the domain
import_base.hpp
import_mentor.{hpp,cpp}
import_ods.{hpp,cpp}
tui/ — FTXUI shell, split by responsibility
tui.{hpp,cpp} class Tui + Run() + screen-mode dispatcher
tui_helpers.{hpp,cpp} free helpers (ToLower, NaturalLess, …)
shell.cpp Print / Submit / Dispatch / Finalize / persistence
completion.cpp command + path Tab completion
commands.cpp registry of all built-in commands
screen_main.cpp visualisation area + bottom input
screen_search.cpp live filter on parts / signals
screen_connect.cpp part-to-part connection authoring
screen_settype.cpp connector type tagging
screen_explore.cpp modules → parts/signals/connections → detail
tests/ — doctest suite (essim_tests target)
CLAUDE.md — implementation notes
LICENSE — EUPL-1.2
src/system/ domain model (Module/Part/Pin/Signal, Connection, Transform, …)
src/imports/ Mentor / Altium / ODS netlist importers
src/tui/ FTXUI shell (commands, screens, completion, history)
tests/ doctest suite
doc/ api/ + user/ Markdown trees, Doxyfile.in, gen_api_md.py
test/ sample netlists + system.essim bring-up script
```
Full layout & rationale in [`DESIGN.md`](DESIGN.md).
## Licence
Copyright (c) 2026 François Dausseur