WireViz
=======

Summary
-------

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.

Features
--------

-  WireViz input files are fully text based

   -  No special editor required
   -  Human readable
   -  Easy version control
   -  YAML syntax

-  Understands and uses color abbreviations as per `IEC 60757`_
   (black=BK, red=RD, …)

   -  Optionally outputs colors as abbreviation (e.g. ‘YE’), full name
      (e.g. ‘yellow’) or hex value (e.g. ‘#ffff00’), with choice of
      UPPER or lower case

-  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 62`_ (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/…)

-  Understands wire gauge in mm² or AWG

   -  Optionally auto-calculates and displays AWG equivalent when
      specifying mm²

-  Allows more than one connector per side, as well as loopbacks
-  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.

Examples
--------

Demo 01
~~~~~~~

`WireViz input file`_:

.. code:: yaml

   connectors:
     X1:
       type: D-Sub
       subtype: female
       pinout: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI]
     X2:
       type: Molex KK 254
       subtype: female
       pinout: [GND, RX, TX]

   cables:
     W1:
       gauge: 0.25 mm2
       length: 0.2
       color_code: DIN
       wirecount: 3
       shield: true

   connections:
     -
       - X1: [5,2,1]
       - W1: [1,2,3]
       - X2: [1,3,2]
     -
       - X1: 5
       - W1: s

Output file:

.. figure:: examples/demo01.png
   :alt: Sample output diagram

   Sample output diagram

`Bill of Materials`_ (auto-generated)

Demo 02
~~~~~~~

|image0|

`Source`_ - `Bill of Materials <examples/demo02.bom.tsv>`__

Tutorial and example gallery
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See the `tutorial page`_ for sample code, as well as the `example
gallery`_ to see more of what WireViz can do.

Usage
-----

::

   $ python3 wireviz.py ~/path/to/file/mywire.yml

This will output the following files

::

   mywire.gv         GraphViz output
   mywire.svg        Wiring diagram as vector image
   mywire.png        Wiring diagram as raster image
   mywire.bom.tsv    BOM (bill of materials) as tab-separated text file
   mywire.html       HTML page with wiring diagram and BOM embedded

Status
------

This is very much a `work in progress`_. Source code, API, syntax and
functionality may change wildly at any time.

Requirements
------------

Developed and tested using Python 3.7; mi

.. _GraphViz: https://www.graphviz.org/
.. _IEC 60757: https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system
.. _DIN 47100: https://en.wikipedia.org/wiki/DIN_47100
.. _IEC 62: https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system
.. _WireViz input file: examples/demo01.yml
.. _Bill of Materials: examples/demo01.bom.tsv
.. _Source: examples/demo02.yml
.. _tutorial page: tutorial/readme.md
.. _example gallery: examples/readme.md
.. _work in progress: todo.md

.. |image0| image:: examples/demo02.png