WireViz is a tool for easily documenting cables, wiring harnesses and connector pinouts. It takes plain text, YAML-formatted files as input and produces beautiful graphical output (SVG, PNG, ...) thanks to GraphViz. It handles automatic BOM (Bill of Materials) creation and has a lot of extra features.
- WireViz input files are fully text based
- No special editor required
- Human readable
- Easy version control
- YAML syntax
- UTF-8 input and output files for special character support
- Understands and uses color abbreviations as per IEC 60757 (black=BK, red=RD, ...)
- Auto-generates standard wire color schemes and allows custom ones if needed
- DIN 47100 (WT/BN/GN/YE/GY/PK/BU/RD/BK/VT/...)
- IEC 60757 (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/...)
- 25 Pair Color Code (BUWH/WHBU/OGWH/WHOG/GNWH/WHGN/BNWH/...)
- TIA/EIA 568 A/B (Subset of 25-Pair, used in CAT-5/6/...)
- Understands wire gauge in mm² or AWG
- Optionally auto-calculates equivalent gauge between mm² and AWG
- Is suitable for both very simple cables, and more complex harnesses.
- Allows for easy-autorouting for 1-to-1 wiring
- Generates BOM (Bill of Materials)
Note: WireViz is not designed to represent the complete wiring of a system. Its main aim is to document the construction of individual wires and harnesses.
connectors:
X1:
type: D-Sub
subtype: female
pinlabels: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI]
X2:
type: Molex KK 254
subtype: female
pinlabels: [GND, RX, TX]
cables:
W1:
gauge: 0.25 mm2
length: 0.2
color_code: DIN
wirecount: 3
shield: true
connections:
-
- X1: [5,2,3]
- W1: [1,2,3]
- X2: [1,3,2]
-
- X1: 5
- W1: sOutput file:
Bill of Materials (auto-generated)
Read the syntax description to learn about WireViz' features and how to use them.
See the tutorial page for sample code, as well as the example gallery to see more of what WireViz can do.
WireViz requires Python 3.7 or later (3.8 to support pdf).
WireWiz requires GraphViz to be installed in order to work. See the GraphViz download page for OS-specific instructions.
Note: Ubuntu 18.04 LTS users in particular may need to separately install Python 3.7 or above, as that comes with Python 3.6 as the included system Python install. The option to generate pdf is not supported for python 3.7, so it might not be possible to use with this version of Ubuntu. If you are forced to use Ubuntu 18.04 for some reason, fill up an issue/MR and I can provide a Docker image to perform the generation.
sudo apt install graphviz
sudo dnf install graphviz
The latest WireViz release can be downloaded from PyPI with the following command:
pip3 install wireviz
Note: The https://github.com/laurierloi/WireViz version sadly can't be downloaded from pypi at this time. If you have this need, submit a MR and it could be added under a different name.
Access to the current state of the development branch can be gained by cloning the repo and installing manually.
We suggest always installing wireviz within a python virtualenv. This avoids many issues caused by dependencies management.
# Cloning the repository
git clone git+https://github.com/laurierloi/WireViz
cd WireViz
# Setup virtualenv
python3 -m pip install --user virtualenv
python3 -m virtualenv venv-wireviz
source venv-wireviz/bin/activate
# Installing/Upgrading dependencies
pip install -U pip setuptools wheel
# Installing with local modification tracking
pip install -e .
If you would like to contribute to this project, make sure you read the contribution guidelines!
The latest version of wireviz allows the user to create harness documents. To do so, a shared metadata file (or multiple) must be provided to the wireviz command. Then, a list of harnesses to include within the document should also be provided. In the simplest case, 1 harness can be provided.
$ wireviz -d ~/path/to/file/metadata.yml ~/path/to/file/myharness1.yml ~/path/to/file/myharness2.yml
Depending on the options specified, this will output some or all of the following files:
titlepage.html Titlepage document. It has links to the different harness for easy navigation
shared_bom.tsv A BOM (bill of materials) for all items within the harness document
myharness{1,2}.gv GraphViz output
myharness{1,2}.svg Wiring diagram as vector image
myharness{1,2}.png Wiring diagram as raster image
myharness{1,2}.bom.tsv BOM (bill of materials) as tab-separated text file
myharness{1,2}.html HTML page with wiring diagram and BOM embedded
Wildcars in the file path are also supported to process multiple files at once, e.g.:
$ wireviz ~/path/to/files/*.yml
To see how to specify the output formats, as well as additional options, run:
$ wireviz --help
$ wireviz -d examples/metadata.yml examples/ex*.yml
Then open examples/titlepage.html to open the document root
Please see the documentation of the build_examples.py script for info on building the demos, examples and tutorial.
See CHANGELOG.md
This is very much a work in progress. Source code, API, syntax and functionality may change wildly at any time.