Designing Wire Harnesses with WireViz - RespiraWorks/Ventilator GitHub Wiki
This page contains a tutorial that walks through how we at RespiraWorks use WireViz to create harnesses and publish the documentation for them. For full details on the WireViz tool, go to the WireViz github page.
You should definitely read the below, but we do have a couple of videos that walk you through how to use git with WireViz, which you might find helpful:
- Install Python, GraphViz, WireViz, and Pandas.
- Add the necessary parts to the RW JSON database.
- Define the harness in YAML and render it with WireViz.
- Create a page for it in our docs and add any necessary assembly notes.
- Build the docs locally to check your work.
- Commit the changes and open PR to merge it into the project.
The power of WireViz is that it allows us to design the wire harness and generate most of the documentation for that harness from the same source file, instead of repeating the work in two separate steps.
Here is an example of the output of this process. See the source file that generated this. |
---|
![]() |
- Install Python 3.7 or greater
- Install GraphViz
- Ensure both Python, Python\Scripts and GraphViz are in your system PATH variable.
- Run the command
pip3 install wireviz
to install wireviz - Run the command
pip3 install pandas
to install pandas
- RW documentation pages, including the harnessing design pages, are generated by linux scripts.
- If you have linux, you can use these scripts to build the docs virtually and check your work.
- If want to use these tools on mac or windows, you can install a linux virtual machine: Ubuntu VirtualBox Tutorial
- Recommended settings: 2048MB memory, 16GB virtual drive (dynamic), 2 CPUs allocated
- Remember to install git-lfs
- Start a new branch in git for your new harness.
- Find your part numbers, datasheets, and pinouts for each connector or termination in the harness.
- Wire type, gauge, and part numbers for the harness.
- Intended connectivity for the harness.
- For each connector, terminal, wire, or crimp contact, check if a part number exists in /master/docs/purchasing/parts.json.
- If not, add a new part entry and assign it a RespiraWorks part number.
- Remember, if your connector uses separately populated contacts, make sure those are in the json file too.
- This is what a json part entry looks like:
{
"pn": "ec-dinf4",
"notes": "4-PIN DIN Power input port",
"manufacturer": "Kycon",
"mpn": "KPJX-PM-4S",
"avg_price": 3.13,
"price_unit": "",
"sources": [
{
"supplier": "DigiKey",
"spn": "2092-KPJX-PM-4S-ND",
"price": 3.13,
"price_units": 1,
"url": "https://www.digikey.com/en/products/detail/kycon-inc/KPJX-PM-4S/9990081"
}
]
},
- Names should be descriptive of the harness function, unique, and contain no spaces.
- Place this file within the Ventilator/docs/wiring folder
- WireViz YAML files have a structure that looks like this. In the next steps we will start building up this structure.
connectors:
cables:
connections:
- Each endpoint in the WireViz YAML file has a designator X1, X2, X3, etc.
- Create an entry for each connector.
- For RespiraWorks, please at minimum use the pn, pincount, pinlabels, and type fields. The other fields are optional, but the more information you put here the more useful the documentation will be.
- The image field is optional, but can be used where a clarifying image, such as that of the connector pinout, or special assembly drawing, might be useful. If using this, make sure to put this image in the docs/wiring/images/ folder, and make it an appropriate size and resolution for the repo.
- When defining connectors that use separately installed contacts, add an
additional_components:
section to the connector definition.
connectors:
X1:
pn: ec-microfit-f-wire-2x2 # RW part number from purchasing JSON file
pincount: 4 # number of pins in the connector
pinlabels: [GND, +24V, GND, +24V] # names for the signal on the connector
type: 2x2-pin Molex Micro-Fit 3.0 # connector type
subtype: female # connector sub-type
mpn: 43025-0400 # manufacturer part number
manufacturer: Molex # manufacturer
image: # optional image
src: ./images/Molex-Micro-Fit-2x2-pinout.png # path to the image file
caption: Reference Pinout, view from mating face # text to display below the image
bgcolor: WH # Background color of entry
width: 200 # range: 1~65535; unit: points
additional_components: # defines additional components such as contacts
-
type: crimp # additional component type
subtype: Micro-Fit 3.0 Crimp Female 24-30awg # additional component name
qty_multiplier: populated # this multiples by the number of connector instances for the BOM
manufacturer: Molex # additional component manufacturer
mpn: 43030-0002 # additional component part number
pn: ec-microfit-crimp-f-24-30 # RW part number
- Define each cable as W1, W2, W3, etc. in the cables section.
- Note that all wires in each cable will be the same length.
- If you need different lengths of wire, you can create multiple cables and connect more than one to a single connector, in next step.
- Definite the part numbers, gauge, and color.
- See the WireViz Syntax Guide for color codes.
- Here is a sample wire definition:
cables:
W1:
pn: ew-pre2
wirecount: 2
type: Molex pre-crimped Mega-Fit
mpn: 0797582038
manufacturer: Molex
# more cable parameters:
length: 300 mm
gauge: 16 AWG
show_equiv: true # auto-calculate AWG equivalent
colors: [BK, BK]
- Now, we will create the connections between endpoints
- Each connection is a set of 3 ordered lists, one connector, one cable, and one connector.
- The first item in the first list connects to the first item in the second list, and the first item in the third list. Same for each subsequent item in the list.
- For example, both this connectivity definition:
connections:
-
- X1: [1-4]
- W1: [1-4]
- X2: [4-1]
- ...and this one, create the same connections:
connections:
-
- X1: [1,2,3,4]
- W1: [1-4]
- X2: [4,3,2,1]
- To check just your wireviz file (this can be done in either Windows or Linux):
- Open a command window and navigate to the Ventilator/docs/wiring folder.
- Run the command
wireviz [harness_name].yml
- If it runs without error messages, it probably completed successfully.
- You can check your work by opening the [harness_name].html file generated by wireviz in the source folder.
- Our documentation uses reStructured Text to write documentation for the assembly of the Ventilator, using the wiring diagrams you just created in WireViz.
- Create a blank text file [harness_name].rst to contain your documentation or copy another one as a template.
- Add [harness_name] to the wiring Table of Contents in /docs/wiring/index.rst
- Fill out the steps for making this harness, and any additional tools needed, like crimpers, soldering iron, heat gun, etc.
- Here is a sample of what a wiring RST file may look like:
.. _main_power_input:
Main power input
======================
.. csv-table:: **BOM**
:widths: 5, 60, 5, 5, 5, 10, 10, 10
:header-rows: 1
:delim: 0009
:file: ./power_entry.bom.tsv
.. image:: power_entry.png
:width: 800
:alt: Wiring diagram
You will need all the tools listed.
* Using items from above BOM as well as:
* 5mm heat shrink tubing [:ref:`ew-shrink5`]
* Instructions:
#. Insert the 4 pre-crimped cables :ref:`[2] <ew-pre2>` into the 2x2 Mega-Fit housing :ref:`[6] <ec-mega4>`.
#. Clip the crimped ends off the remaining free end of the cables.
#. Slide 15mm of heat shrink onto each of the 2 cables that will go to the DIN receptacle.
#. Slide on a few extra lengths of heat shrink tubing for cable management before you proceed.
#. Solder the cables to the DIN receptacle :ref:`[3] <ec-dinf4>` per the cable drawing. Apply the heat shrink to the junction.
#. Crimp the QC terminals :ref:`[4] <ec-qctf>` per the drawing.
#. Crimp the ring terminal :ref:`[5] <ec-ring>` per the drawing.
#. Do a gentle pull test to confirm proper seating of all the contacts.
#. Shrink the remaining pieces of heat shrink to make the cable more manageable.
Total price: USD 8.94
- To check the entire documentation build, including the parts directory and rst instructions. (This can only be done in Linux or in a Linux Virtual Machine):
- Follow the directions in RW Documentation Readme, Building the docs section to build and review the complete documentation.
- Open
docs/_build/html/index.html
- Navigate to Purchasing Documentation >> Parts and check that your parts are correct.
- Navigate to Wiring Documentation >> [harness name] and check that your wireviz diagrams and instructions are correct.
- Note, if you do not have access to Linux, this check can be done by a member with Linux in the PR process.
- Make sure you add and commit the following files:
- docs/wiring/[harness_name].yml
- docs/wiring/[harness_name].rst
- docs/wiring/index.rst
- docs/purchasing/parts.json file in if you added any parts
- Any files that you added to /images to reference in your [harness_name].yml file.
- No other files should be added. They will be automatically generated by the documentation system.
- Remember to then do a git push.
- Go to https://github.com/RespiraWorks/Ventilator/pulls and you should see your recent branch commit highlighted. Click the big green "Compare and Pull Request" button
- If you do not see your branch highlighted, click the green "New pull request" button and select your branch.
- Give your pull request a description and assign reviewers, labels, milestone, and project.
- Press the "Create Pull Request" button.