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:

TL;DR

  • 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.
wireviz_example

How to install WireViz:

  • 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

(Optional) Install a Linux virtual machine

  • 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

Step 1:

  • Start a new branch in git for your new harness.

Step 2: Gather information and create parts in the RW parts directory

  • 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"
      }
    ]
  },

Step 3: Create a blank [harness_name].yml text file or start by copying an existing one

  • 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:

Step 3: Define the endpoints (i.e. connectors and terminals)

  • 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

Step 4: Define the wires and assign part numbers

  • 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]

Step 5: Define the connectivity

  • 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]

Step 6: Check your work in wireviz

  • 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.

Step 7: Create assembly documentation

  • 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

Step 8: Check complete documentation

  • 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.

Step 9: Commit your changes to the branch and start a PR

  • 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.
⚠️ **GitHub.com Fallback** ⚠️