diff --git a/examples/example1.png b/examples/example1.png new file mode 100644 index 0000000..ac10d2f Binary files /dev/null and b/examples/example1.png differ diff --git a/examples/example2.png b/examples/example2.png new file mode 100644 index 0000000..9e88249 Binary files /dev/null and b/examples/example2.png differ diff --git a/examples/example2.yml b/examples/example2.yml index 9b854ed..54adfaf 100644 --- a/examples/example2.yml +++ b/examples/example2.yml @@ -1,4 +1,4 @@ -templates: +templates: # defining templates to be used later on - &molex_f type: Molex KK 254 gender: female @@ -11,11 +11,11 @@ templates: nodes: X1: - <<: *molex_f + <<: *molex_f # copying items from the template pinout: [GND, +5V, SCL, SDA, MISO, MOSI, SCK, N/C] X2: <<: *molex_f - <<: *con_i2c + <<: *con_i2c # it is possible to copy from more than one template X3: <<: *molex_f <<: *con_i2c diff --git a/readme.md b/readme.md index f25e63a..b9bdd78 100644 --- a/readme.md +++ b/readme.md @@ -2,17 +2,15 @@ ## Summary -WireViz is a simple yet flexible markup language for documenting cables, wiring harnesses and connector pinouts with beautiful graphical output. - -It is based on [GraphViz](https://www.graphviz.org/) and designed as an "extension" of it. A parser reads a WireViz file and generates valid GraphViz output, which can instantly be rendered to SVG/PNG. +WireViz is a simple yet flexible, YAML-based markup language for documenting cables, wiring harnesses and connector pinouts with beautiful graphical output (SVG, PNG, ...) thanks to [GraphViz](https://www.graphviz.org/). ## Features -* WireViz is fully text based +* WireViz input files are fully text based * No special editor required * Human readable * Easy version control - * GraphViz-like syntax + * YAML syntax * Understands and uses color abbreviations as per [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) (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 @@ -27,87 +25,50 @@ _Note_: WireViz is not designed to represent the complete wiring of a system. It ## Example -WireViz input file: +[WireViz input file](examples/example1.yml): - // define connectors + nodes: + X1: + type: D-Sub + gender: female + pinout: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI] + random: yes + X2: + type: Molex KK 254 + gender: female + pinout: [GND, RX, TX, N/C, OUT, IN] - X1 [type="D-Sub", - gender="female", - pin_labels="DCD|RX|TX|DTR|GND|DSR|RTS|CTS|RI", - ] + wires: + W1: + mm2: 0.25 + length: 0.2 + color_code: DIN + num_wires: 3 + shield: true - X2 [type="Molex KK 254", - gender="female", - pin_labels="GND|RX|TX|NC|OUT|IN", - ] - - // define wire - - W1 [mm2=0.25, - length=0.2, - num_wires=3, - colors="din47100", - shield=true - ] - - // define connections - - X1:5 -> W1:1 -> X2:1 // GND - X1:2 -> W1:2 -> X2:3 // TX-RX - X1:3 -> W1:3 -> X2:2 // RX-TX - X1:5 -> W1:S // shield - X2:5 -> X2:6 // loop + connections: + - # format: connector->wire->connector + - X1: [5,2,1] + - W1: [1,2,3] + - X2: [1,3,2] + - # format: connector->wire or wire->connector + - X1: 5 + - W1: s + - # loop: connector-connector + - X2: 5 + - X2: 6 Output file: -![Sample output diagram](idea/example1.png) +![Sample output diagram](examples/example1.png) -GraphViz code generated by parser: +[Example 2](examples/example2.yml) - digraph G { - graph [rankdir = LR, ranksep=2, fontname = "arial"]; - edge [arrowhead=none, fontname = "arial"]; - node [shape=record, style=rounded, fontname = "arial"]; - - X1[label="X1 | {D-Sub DE-9|female|9-pin} | {{DCD|RX|TX|DTR|GND|DSR|RTS|CTS|RI} | {1|2|3|4|5|6|7|8|9}}}"] - - X2[label="X2 | {Molex KK 254|female|6-pin} | {{1|2|3|4|5|6} | {|||||}}}"] - - {edge[style=bold] - X2:p5:w -> X2:p6:w - } - - W1[label="W1 | {3x|0.25 mm²| + S|0.2 m} | {{1|2|3|} | {WH|BN|GN|Shield} | {1|2|3|}}}"] - - {edge[style=bold] - {edge[color="#000000:#ffffff:#000000"] X1:p5 -> W1:w1i; W1:w1o -> X2:p1} - {edge[color="#000000:#666600:#000000"] X1:p2 -> W1:w2i; W1:w2o -> X2:p3} - {edge[color="#000000:#00ff00:#000000"] X1:p3 -> W1:w3i; W1:w3o -> X2:p2} - {X1:p5 -> W1:wsi; } - } - - - } - -[Example 2](idea/example2.dot) - -![](idea/example2.png) +![](examples/example2.png) ## Status -This is very much a work in progress. -A Python module and test scripts are available. Running the test script will generate GraphViz output. -The parser will follow later; contributions are welcome! - -## To do - -* Add simple connectors (ferrules, cable lugs) - * no pinout - * graphical representation? -* Add support for cable splicing (as connector type) -* Display picture of connector underneath (including pin 1 location) -* Create parser (to make WireViz work as a GraphViz extension) -* Automatic BOM generation +This is very much a [work in progress](todo.md). ## License diff --git a/todo.md b/todo.md index 70d3d83..f27e892 100644 --- a/todo.md +++ b/todo.md @@ -1,14 +1,23 @@ +# To-do: + +* Set global parameters (show_pins, ...) and allow override on per-item basis * Generic connectors * ferrules * blade terminals * loose ends + * graphical representation? +* Support for cable splicing (as connector type) * new wire look? * distinguish between cables and wire bundles * improve nomenclature * terminal (connector, ferrule, blade, loose) * link (cable, wire bundle) * show from/to inside wire node +* Allow custom GraphViz code before/after WireViz-generated code +* Display picture of connector underneath (including pin 1 location) * export to PDF with frame, title block, ... +* Automatic BOM generation +* Allow * make "unit tests" for different features/situations * missing parameters * connection formats