Ryan Malloy
08c92bfefb
Implement three-tier resolution for LTspice .asc schematic files: 1. Companion netlist - finds .net/.cir/.sp beside the .asc (automatic) 2. LTspice generation - invokes LTspice binary (opt-in via --generate-netlist) 3. Metadata-only fallback - extracts component refs/values without connectivity Safety: DataCompleteness enum forces callers to check completeness. CLI blocks diagram generation on METADATA_ONLY with clear remediation. Metadata enrichment is additive-only with protected field guards. Also: update project URLs to Gitea, add .asc usage docs to README, fix pre-existing ruff warning in test_single_module.py.
90 lines
2.7 KiB
Markdown
90 lines
2.7 KiB
Markdown
# spice2wireviz
|
|
|
|
Convert LTspice SPICE netlists to WireViz wiring diagrams.
|
|
|
|
## What it does
|
|
|
|
`spice2wireviz` reads SPICE netlist files (`.net`, `.cir`, `.sp`) and LTspice schematics (`.asc`) and generates [WireViz](https://github.com/wireviz/WireViz) YAML that documents the physical wiring: connectors, test points, and inter-module cables.
|
|
|
|
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
|
|
|
|
## Install
|
|
|
|
```bash
|
|
uv tool install spice2wireviz
|
|
# or
|
|
pip install spice2wireviz
|
|
```
|
|
|
|
For `.asc` file metadata extraction (optional):
|
|
|
|
```bash
|
|
pip install spice2wireviz[asc]
|
|
```
|
|
|
|
## Usage
|
|
|
|
### From netlist files
|
|
|
|
```bash
|
|
# Inter-module wiring (auto-detected from top-level X instances)
|
|
spice2wireviz top_level.net -o wiring.yml --render
|
|
|
|
# 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
|
|
|
|
# Inspect before converting
|
|
spice2wireviz design.net --list-subcircuits
|
|
spice2wireviz design.net --list-components
|
|
spice2wireviz design.net --dry-run
|
|
```
|
|
|
|
### From .asc schematics
|
|
|
|
LTspice `.asc` 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.
|
|
3. **Metadata only** -- Without a netlist, only component refs/values are available. Diagram generation is blocked, but `--list-components` still works.
|
|
|
|
```bash
|
|
# .asc with companion .net in the same directory -- works like .net input
|
|
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
|
|
|
|
# Inspect component metadata (no .net required)
|
|
spice2wireviz schematic.asc --list-components
|
|
```
|
|
|
|
## Filtering
|
|
|
|
Cherry-pick what appears in the diagram:
|
|
|
|
```bash
|
|
--include-prefixes J,TP # Only these component types
|
|
--exclude-refs X3,J_DEBUG # Hide specific references
|
|
--include-nets "SIG_*" # Glob patterns for net names
|
|
--no-ground # Hide GND connections
|
|
--no-power # Hide VCC/VDD connections
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
uv sync --extra dev --extra asc
|
|
uv run pytest
|
|
uv run ruff check src/ tests/
|
|
```
|
|
|
|
## Repository
|
|
|
|
[git.supported.systems/warehack.ing/spice2wireviz](https://git.supported.systems/warehack.ing/spice2wireviz)
|