Expand README with output examples, BOM docs, architecture diagram
Add real YAML/CSV output examples generated from test fixtures, document --bom/--bom-wiring flags, layout optimization, inspection commands, and LTspice --ltspice-exe option.
This commit is contained in:
parent
5a5337566c
commit
fd822e07ce
297
README.md
297
README.md
@ -11,6 +11,8 @@ Two operating modes:
|
||||
- **Single module** -- External interface of one subcircuit (its connectors, test points, port interface)
|
||||
- **Inter-module** -- How multiple subcircuits/boards connect to each other
|
||||
|
||||
It also produces **Bill of Materials** output as CSV, and includes layout optimization to minimize cable crossings in rendered diagrams.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
@ -25,43 +27,239 @@ For `.asc` file metadata extraction (optional):
|
||||
pip install spice2wireviz[asc]
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### From netlist files
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Inter-module wiring (auto-detected from top-level X instances)
|
||||
spice2wireviz top_level.net -o wiring.yml --render
|
||||
spice2wireviz top_level.net -o wiring.yml
|
||||
|
||||
# Single module external interface
|
||||
spice2wireviz design.net -s amplifier_board -o amp.yml
|
||||
|
||||
# Only connectors and test points, no ground
|
||||
spice2wireviz design.net --include-prefixes J,TP --no-ground
|
||||
# Render to SVG/PNG/HTML (requires WireViz installed)
|
||||
spice2wireviz design.net -o wiring.yml --render --format sph
|
||||
|
||||
# Inspect before converting
|
||||
spice2wireviz design.net --list-subcircuits
|
||||
spice2wireviz design.net --list-components
|
||||
spice2wireviz design.net --dry-run
|
||||
# Component bill of materials
|
||||
spice2wireviz design.net --bom
|
||||
|
||||
# Wiring bill of materials (cables, wire counts, endpoints)
|
||||
spice2wireviz top_level.net --bom-wiring
|
||||
```
|
||||
|
||||
### From .asc schematics
|
||||
## Output examples
|
||||
|
||||
LTspice `.asc` files are supported with tiered netlist resolution:
|
||||
### Input: SPICE netlist
|
||||
|
||||
1. **Companion netlist** (automatic) -- If a `.net`, `.cir`, or `.sp` file exists alongside the `.asc` (same basename), it's used for full connectivity. LTspice generates these automatically when you run a simulation.
|
||||
2. **LTspice generation** (opt-in) -- Pass `--generate-netlist` to invoke LTspice and produce a `.net` file.
|
||||
3. **Metadata only** -- Without a netlist, only component refs/values are available. Diagram generation is blocked, but `--list-components` still works.
|
||||
A multi-board system with power supply, amplifier, and I/O board:
|
||||
|
||||
```spice
|
||||
.subckt power_supply VCC GND
|
||||
J1 AC_IN AC_GND AC_INLET
|
||||
.ends power_supply
|
||||
|
||||
.subckt amplifier VIN GND VOUT
|
||||
J1 VIN GND INPUT_CONN
|
||||
TP1 VOUT
|
||||
.ends amplifier
|
||||
|
||||
.subckt io_board SIG_IN SIG_OUT GND CTRL
|
||||
J1 SIG_IN SIG_OUT DB9_CONN
|
||||
J2 CTRL GND CTRL_CONN
|
||||
.ends io_board
|
||||
|
||||
* Top-level instantiation
|
||||
X1 VCC GND power_supply
|
||||
X2 VCC GND AUDIO_OUT amplifier
|
||||
X3 AUDIO_OUT CTRL_SIG GND ENABLE io_board
|
||||
|
||||
* Top-level connectors
|
||||
J_CHASSIS GND EARTH chassis_gnd
|
||||
TP_VCC VCC
|
||||
```
|
||||
|
||||
### Output: Inter-module WireViz YAML
|
||||
|
||||
```bash
|
||||
# .asc with companion .net in the same directory -- works like .net input
|
||||
spice2wireviz schematic.asc -s amplifier_board -o amp.yml
|
||||
spice2wireviz multi_board.net
|
||||
```
|
||||
|
||||
# No companion .net -- invoke LTspice to generate one
|
||||
spice2wireviz schematic.asc --generate-netlist -o wiring.yml
|
||||
```yaml
|
||||
metadata:
|
||||
title: 'Wiring diagram: multi_board'
|
||||
source: multi_board.net
|
||||
generator: spice2wireviz 2026.2.14
|
||||
connectors:
|
||||
J_CHASSIS:
|
||||
type: chassis_gnd
|
||||
pinlabels:
|
||||
- EARTH
|
||||
- GND
|
||||
notes: 'SPICE ref: J_CHASSIS'
|
||||
TP_VCC:
|
||||
type: TP
|
||||
style: simple
|
||||
pinlabels:
|
||||
- VCC
|
||||
notes: 'SPICE ref: TP_VCC'
|
||||
X1:
|
||||
type: power_supply
|
||||
pinlabels:
|
||||
- VCC
|
||||
- GND
|
||||
notes: 'SPICE instance: X1 (power_supply)'
|
||||
X2:
|
||||
type: amplifier
|
||||
pinlabels:
|
||||
- VIN
|
||||
- GND
|
||||
- VOUT
|
||||
notes: 'SPICE instance: X2 (amplifier)'
|
||||
X3:
|
||||
type: io_board
|
||||
pinlabels:
|
||||
- GND
|
||||
- SIG_IN
|
||||
- SIG_OUT
|
||||
- CTRL
|
||||
notes: 'SPICE instance: X3 (io_board)'
|
||||
cables:
|
||||
W1:
|
||||
colors:
|
||||
- BK
|
||||
wirelabels:
|
||||
- GND
|
||||
W3:
|
||||
colors:
|
||||
- RD
|
||||
wirelabels:
|
||||
- VCC
|
||||
W5:
|
||||
category: bundle
|
||||
colors:
|
||||
- BK
|
||||
- RD
|
||||
wirelabels:
|
||||
- GND
|
||||
- VCC
|
||||
W8:
|
||||
wirecount: 1
|
||||
wirelabels:
|
||||
- AUDIO_OUT
|
||||
connections:
|
||||
- - TP_VCC: 1
|
||||
- W3: 1
|
||||
- X1: 1
|
||||
- - X1: [2, 1]
|
||||
- W5: [1, 2]
|
||||
- X2: [2, 1]
|
||||
- - X2: 3
|
||||
- W8: 1
|
||||
- X3: 2
|
||||
```
|
||||
|
||||
# Inspect component metadata (no .net required)
|
||||
spice2wireviz schematic.asc --list-components
|
||||
Every connector includes a `notes` field tracing back to the original SPICE reference or instance. Ground wires are colored black (`BK`), power wires red (`RD`). Parallel wires between the same module pair are grouped into multi-wire cables (like `W5` above).
|
||||
|
||||
### Output: Single-module WireViz YAML
|
||||
|
||||
```bash
|
||||
spice2wireviz simple_board.net -s amplifier_board
|
||||
```
|
||||
|
||||
```yaml
|
||||
connectors:
|
||||
amplifier_board:
|
||||
type: Module Interface
|
||||
pinlabels:
|
||||
- VIN
|
||||
- GND
|
||||
- VOUT
|
||||
- SIGNAL_IN
|
||||
notes: 'SPICE subcircuit: .subckt amplifier_board'
|
||||
J1:
|
||||
type: PWR_CONN
|
||||
pinlabels:
|
||||
- VIN
|
||||
- GND
|
||||
J2:
|
||||
type: SIG_CONN
|
||||
pinlabels:
|
||||
- VOUT
|
||||
- SIGNAL_IN
|
||||
TP1:
|
||||
type: TP
|
||||
style: simple
|
||||
pinlabels:
|
||||
- N001
|
||||
cables:
|
||||
W_J1:
|
||||
category: bundle
|
||||
colors: ['', BK]
|
||||
wirelabels: [VIN, GND]
|
||||
W_J2:
|
||||
category: bundle
|
||||
wirecount: 2
|
||||
wirelabels: [VOUT, SIGNAL_IN]
|
||||
connections:
|
||||
- - amplifier_board: [1, 2]
|
||||
- W_J1: [1, 2]
|
||||
- J1: [1, 2]
|
||||
- - amplifier_board: [3, 4]
|
||||
- W_J2: [1, 2]
|
||||
- J2: [1, 2]
|
||||
```
|
||||
|
||||
Single-module mode generates a central "module header" connector representing the subcircuit's port interface, with star-topology cables radiating out to each boundary component (J*, TP*, P*).
|
||||
|
||||
### Output: Component BOM
|
||||
|
||||
```bash
|
||||
spice2wireviz simple_board.net --bom
|
||||
```
|
||||
|
||||
```csv
|
||||
Reference,Prefix,Value,Pins,Subcircuit,Attributes
|
||||
J1,J,PWR_CONN,2,amplifier_board,
|
||||
J2,J,SIG_CONN,2,amplifier_board,
|
||||
TP1,TP,,1,amplifier_board,
|
||||
```
|
||||
|
||||
Component BOM lists all boundary components (connectors, test points) with their reference, value, pin count, and which subcircuit they belong to. Works even on `.asc` files without connectivity data.
|
||||
|
||||
### Output: Wiring BOM
|
||||
|
||||
```bash
|
||||
spice2wireviz multi_board.net --bom-wiring
|
||||
```
|
||||
|
||||
```csv
|
||||
Cable,Wirecount,Nets,From,To
|
||||
W1,1,GND,J_CHASSIS,X1
|
||||
W3,1,VCC,TP_VCC,X1
|
||||
W5,2,"GND, VCC",X1,X2
|
||||
W6,1,GND,X1,X3
|
||||
W8,1,AUDIO_OUT,X2,X3
|
||||
```
|
||||
|
||||
Wiring BOM lists every cable with wire count, net names, and connected endpoints. Useful for generating cut lists and wire pull schedules.
|
||||
|
||||
## Inspection commands
|
||||
|
||||
Preview what's in a netlist before generating diagrams:
|
||||
|
||||
```bash
|
||||
# List subcircuit definitions
|
||||
$ spice2wireviz multi_board.net --list-subcircuits
|
||||
amplifier: ports=[VIN, GND, VOUT], boundary_components=2
|
||||
io_board: ports=[SIG_IN, SIG_OUT, GND, CTRL], boundary_components=2
|
||||
power_supply: ports=[VCC, GND], boundary_components=1
|
||||
|
||||
# Dry run (connector/cable/connection counts)
|
||||
$ spice2wireviz multi_board.net --dry-run
|
||||
Mode: inter
|
||||
Connectors: 5
|
||||
Cables: 5
|
||||
Connection sets: 5
|
||||
Connector names: J_CHASSIS, TP_VCC, X1, X2, X3
|
||||
```
|
||||
|
||||
## Filtering
|
||||
@ -69,21 +267,74 @@ spice2wireviz schematic.asc --list-components
|
||||
Cherry-pick what appears in the diagram:
|
||||
|
||||
```bash
|
||||
--include-prefixes J,TP # Only these component types
|
||||
--include-prefixes J,TP # Only these component types (default: J,TP,P,X)
|
||||
--exclude-prefixes X # Hide subcircuit modules
|
||||
--exclude-refs X3,J_DEBUG # Hide specific references
|
||||
--include-nets "SIG_*" # Glob patterns for net names
|
||||
--exclude-nets "*_DEBUG" # Exclude debug nets
|
||||
--no-ground # Hide GND connections
|
||||
--no-power # Hide VCC/VDD connections
|
||||
--no-group # Don't bundle parallel wires into multi-wire cables
|
||||
```
|
||||
|
||||
## LTspice .asc support
|
||||
|
||||
LTspice `.asc` schematic files are supported with tiered netlist resolution:
|
||||
|
||||
1. **Companion netlist** (automatic) -- If a `.net`, `.cir`, or `.sp` file exists alongside the `.asc` (same basename), it's used for full connectivity. LTspice generates these automatically when you run a simulation.
|
||||
2. **LTspice generation** (opt-in) -- Pass `--generate-netlist` to invoke LTspice and produce a `.net` file. Use `--ltspice-exe` to specify the LTspice binary path if it's not auto-detected.
|
||||
3. **Metadata only** -- Without a netlist, only component refs/values are available. Diagram generation is blocked, but `--list-components` and `--bom` still work.
|
||||
|
||||
```bash
|
||||
# .asc with companion .net in the same directory
|
||||
spice2wireviz schematic.asc -s amplifier_board -o amp.yml
|
||||
|
||||
# No companion .net -- invoke LTspice to generate one
|
||||
spice2wireviz schematic.asc --generate-netlist -o wiring.yml
|
||||
|
||||
# Specify LTspice binary path (Linux/wine, macOS, Windows)
|
||||
spice2wireviz schematic.asc --generate-netlist --ltspice-exe /path/to/ltspice
|
||||
|
||||
# Component BOM from .asc (no .net required)
|
||||
spice2wireviz schematic.asc --bom
|
||||
```
|
||||
|
||||
## Layout optimization
|
||||
|
||||
Both mappers apply layout optimization to minimize cable crossings in rendered diagrams:
|
||||
|
||||
- **Inter-module**: Sugiyama-lite layered graph drawing -- external connectors are placed at the left edge, modules are layered by BFS distance, barycenter ordering reduces crossings, and pins are reordered to group connections to the same neighbor.
|
||||
- **Single-module**: Star topology optimization -- boundary components are ordered by their connection pattern to the module header, header pins are grouped by target component, and pin sequences are parallelized.
|
||||
|
||||
This is automatic and requires no configuration.
|
||||
|
||||
## How it works
|
||||
|
||||
```
|
||||
.net/.cir/.sp ─────┐
|
||||
├─→ Parser ─→ ParsedNetlist ─→ Filters ─→ Mapper ─→ WireViz YAML
|
||||
.asc (+ companion) ┘ │ │
|
||||
│ └─→ Wiring BOM CSV
|
||||
└─→ Component BOM CSV
|
||||
```
|
||||
|
||||
The parser extracts subcircuit definitions (`.subckt`), instances (`X*`), and boundary components (`J*`, `TP*`, `P*`) from SPICE netlists. Filters remove unwanted elements. The mapper converts the remaining structure into WireViz connector/cable/connection format. The emitter serializes to deterministic YAML (byte-identical output for identical input) or CSV.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
uv sync --extra dev --extra asc
|
||||
uv run pytest
|
||||
uv run pytest # 188 tests
|
||||
uv run ruff check src/ tests/
|
||||
```
|
||||
|
||||
LTspice integration tests require LTspice installed and are marked:
|
||||
|
||||
```bash
|
||||
uv run pytest -m ltspice # Run only LTspice tests
|
||||
uv run pytest -m "not ltspice" # Skip LTspice tests (CI default)
|
||||
```
|
||||
|
||||
## Repository
|
||||
|
||||
[git.supported.systems/warehack.ing/spice2wireviz](https://git.supported.systems/warehack.ing/spice2wireviz)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user