François
477f3abd40
Add LICENSE (full EUPL v1.2 text from the SPDX archive) and a README covering build, commands, tests, project layout, and the licence notice. Project is now declared open-source under EUPL-1.2. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
117 lines
4.9 KiB
Markdown
117 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
Status: early work-in-progress.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build -j
|
|
./build/essim
|
|
```
|
|
|
|
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`.
|
|
|
|
To run the test suite:
|
|
|
|
```sh
|
|
./build/essim_tests
|
|
# or
|
|
ctest --test-dir build
|
|
```
|
|
|
|
To skip building tests:
|
|
|
|
```sh
|
|
cmake -S . -B build -DBUILD_TESTING=OFF
|
|
```
|
|
|
|
## TUI commands
|
|
|
|
Type `help` inside the shell for the live list, or `help <name>` for the per-command synopsis. At a glance:
|
|
|
|
| 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 |
|
|
|
|
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`).
|
|
|
|
## 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
|
|
```
|
|
|
|
## Licence
|
|
|
|
Copyright (c) 2026 François Dausseur
|
|
|
|
Licensed under the **European Union Public Licence (EUPL), Version 1.2** —
|
|
the "Licence". You may not use this work except in compliance with the
|
|
Licence. You may obtain a copy of the Licence in the [`LICENSE`](LICENSE)
|
|
file or at <https://joinup.ec.europa.eu/software/page/eupl>.
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the Licence is distributed on an "AS IS" basis,
|
|
**WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND**, either express or
|
|
implied. See the Licence for the specific language governing permissions
|
|
and limitations under the Licence.
|
|
|
|
SPDX-License-Identifier: EUPL-1.2
|