I often need to create diagrams showing how to make wiring harnesses for test cables in work. I have tried previous versions of WireViz and found it to be useful but needed a little more work. I am not a coder by any stretch of the imagination and YAML (Yet Another Markup Language) syntax is new to me.
Here is the Hackaday article on WireViz:
https://hackaday.com/2020/06/23/an-open-source-tool-to-document-your-wiring/
Installing WireViz is fairly simple assuming one has Python installed properly and the system variables in the path. Instructions for installing Python correctly here:
https://docs.python.org/3/using/windows.html#
Ensure you add the python path to the system variables...if this doesn't happen WireViz does not work.
Next grab the latest version of Wireviz....
Open a command prompt and type:
pip install wireviz
Once installed check things are working by typing:
wireviz --version
If things are working correctly the result should read:
WireViz 0.4.1
If that doesn't happen please check your python installation and system variables etc.
For reference here is the git repository for the WireViz Project - it contains useful information and example files:
https://github.com/wireviz/WireViz
If WireViz has correctly installed we can start to create a simple wiring harness diagram. Lets create a simple test cable - a BNC to screw terminals connector on one end and a red 4 mm banana connector and a black 4 mm banana connector at the other end with two red and black wires which are 24 AWG. Lets make the cable 400 mm in length.
To describe this in YAML we create a text file. I like to use notepad++ but one can use any text editor they wish providing it can save the file with a yml extension. We can call it whatever we like but it is good practice to use a sensible filename. I called mine BNC2Banana.yml. Ensure you save it in a folder you can locate.
While we are at it lets create a folder called IMG within the same folder we are using to store the text file. We will need this later...
Lets look at the example code provided for some context:
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: s
The code creates a wiring harness with two connector types (X1 and X2) - a 9 pin D-type connector and a three pin molex kk connector with 2.54 mm pitch. An RS232 serial cable has the following signals present: DCD, RX, TX, DTR, GND, DSR, RTS, CTS and RI. The code makes connections to GND, RX and TX which will be present at the Molex Connector. The wire type is set in the cables: section - the wire gauge used will be 0.25 mm squared cable and will use the DIN colour code and the cable itself will be 200 mm in length or 0.2 metres.
If we run this code the output looks like this:
We are going to edit this code for our own purposes to create our test cable:
Instead of calling the connectors X1 and X2 lets use variable names that make sense: Lets call them what they actually are:
4mm_Red_Banana:
4mm_Black_Banana:
BNC_SCREW_Terminal:
Let us also update the type and pinlables variables to something more appropriate:
type:
Therefore our code should look like this:
connectors: 4mm_Red_Banana: 4mm_Banana_Red # Red 4mm Banana type: 4 mm Red Banana Connector pinlabels: [+VE] 4mm_Black_Banana: 4mm_Banana_Black # Black 4mm Banana type: 4 mm Black Banana Connector pinlabels: [GND] BNC_SCREW_Terminal: # Female BNC to Screw Terminals type: BNC Connector female - Screw Terminal pinlabels: [+VE, GND]
cables: C: colors: [RD, BK] # number of wires implicit in color list gauge: 0.25 mm2 # also accepts AWG as unit show_equiv: true # auto-calculate AWG equivalent from metric gauge length: 0.4 # length in m shield: false
Finally we need to write the code which describes how the connectors and cables are connected which is denoted in the connectors: section...I like how simple this actually is to read...
The BNC connector pin 1 needs to connect to the cable C1 which will have a red insulation jacket and then on to the red 4 mm banana connector. The BNC connector pin 2 needs to connect to Cable C2 which will have a black insulation jacket which in turn connects to the black 4 mm banana connector.
The code looks like this:
connections: - - BNC_SCREW_Terminal: [1] - C.C1: [1] - 4mm_Red_Banana: [1] - - BNC_SCREW_Terminal: [2] - C.C1: [2] - 4mm_Black_Banana: [1]
connectors: 4mm_Red_Banana: # Red 4mm Banana type: 4 mm Red Banana Connector pinlabels: [+VE] 4mm_Black_Banana: # Black 4mm Banana type: 4 mm Black Banana Connector pinlabels: [GND] BNC_SCREW_Terminal: # Female BNC to Screw Terminals type: BNC Connector female - Screw Terminal pinlabels: [+VE, GND] cables: C: colors: [RD, BK] # number of wires implicit in color list gauge: 0.25 mm2 # also accepts AWG as unit show_equiv: true # auto-calculate AWG equivalent from metric gauge length: 0.4 # length in m shield: false connections: - - BNC_SCREW_Terminal: [1] - C.C1: [1] - 4mm_Red_Banana: [1] - - BNC_SCREW_Terminal: [2] - C.C1: [2] - 4mm_Black_Banana: [1]
Save the code - always a good idea!
Type the following command:
WireViz BNC2BananaSimple.yml
If everything has gone according to plan you should see the following response:
A number of files should have been created in the folder:
- An SVG file
- An HTML file
- A TSV file
- A PNG file
If we look at the PNG file we can see our cable harness diagram:
The other files are copies of the above diagram except the TSV file which is a tab separated value file making up the bill of materials.
The above diagram should be more than enough information for a wiring person to create a wiring loom but due to the improvements in WireViz we can now add more code which in turn creates more information.
As 4 mm banana connectors are essentially all the same part apart from the number we can use some programming tricks to make the code slightly more easy to understand and we can add more information to make our diagram more comprehensive and the bill of materials more explicit:
connectors: 4mm_Red_Banana: &4mm_Banana_t # https://uk.rs-online.com/web/p/banana-connectors/2080252 pinlabels: [+VE] type: 4 mm Red Banana Connector manufacturer: RS Components mpn: 2080252 supplier: uk.rs-online.com spn: 2080252 subtype: male color: RD image: src: IMG/4mm.Red.Banana.png 4mm_Black_Banana: # https://uk.rs-online.com/web/p/banana-connectors/2080251 <<: *4mm_Banana_t pinlabels: [GND] type: 4 mm Black Banana Connector mpn: 2080251 spn: 2080251 color: BK image: src: IMG/4mm.Black.Banana.png BNC_SCREW_Terminal: # https://uk.rs-online.com/web/p/coaxial-adapters/1242521 pinlabels: [+VE, GND] type: BNC Connector Male - Screw Terminal manufacturer: RS Components mpn: 1242521 supplier: RS Components spn: 1242521 subtype: female color: BK image: src: IMG/BNC-SCREW-TERM-MALE.png
The change in the connectors section is the line containing this:
&4mm_Banana_tEssentially what this line of code does is create a template for the 4 mm banana connector type.
It means that connectors of the same type but with slightly different attributes can be used without quite so much typing needed. If we look at the next connector section it references the template with this line of code:
<<: *4mm_Banana_t
We now need to obtain some images of our connectors. I downloaded some stock images with white backgrounds:
In my opinion that is a more than satisfactory diagram for a test cable harness. There are ways to set the page size adding a header section to ensure that the code is more readable. I would like to be able to add a template with a title block but at the moment this feature isn't working.
I think that's all for now - take care always - Langster!
The BNC to Screw Terminal Connector
The Red 4 mm Banana Connector
The Black 4 mm Banana Connector
Save these pictures (or find your own) into the IMG folder we created earlier. Be sure to rename them to the same names used in the code:
- 4mm.Red.Banana.png
- 4mm.Black.Banana.png
- BNC-SCREW-TERM-MALE.png
The rest of the code remains unchanged but for completeness here it is in case it is needed:
connectors: 4mm_Red_Banana: &4mm_Banana_t # https://uk.rs-online.com/web/p/banana-connectors/2080252 pinlabels: [+VE] type: 4 mm Red Banana Connector manufacturer: RS Components mpn: 2080252 supplier: uk.rs-online.com spn: 2080252 subtype: male color: RD image: src: IMG/4mm.Red.Banana.png 4mm_Black_Banana: # https://uk.rs-online.com/web/p/banana-connectors/2080251 <<: *4mm_Banana_t pinlabels: [GND] type: 4 mm Black Banana Connector mpn: 2080251 spn: 2080251 color: BK image: src: IMG/4mm.Black.Banana.png BNC_SCREW_Terminal: # https://uk.rs-online.com/web/p/coaxial-adapters/1242521 pinlabels: [+VE, GND] type: BNC Connector Male - Screw Terminal manufacturer: RS Components mpn: 1242521 supplier: RS Components spn: 1242521 subtype: female color: BK image: src: IMG/BNC-SCREW-TERM-MALE.png cables: C: colors: [RD, BK] # number of wires implicit in color list gauge: 0.25 mm2 # also accepts AWG as unit show_equiv: true # auto-calculate AWG equivalent from metric gauge length: 0.4 # length in m shield: false mpn: UL1007-24AWG connections: - - BNC_SCREW_Terminal: [1] - C.C1: [1] - 4mm_Red_Banana: [1] - - BNC_SCREW_Terminal: [2] - C.C1: [2] - 4mm_Black_Banana: [1]
With that done we can now re-run the WireViz command and we get a different and in my opinion, a much improved diagram:
In my opinion that is a more than satisfactory diagram for a test cable harness. There are ways to set the page size adding a header section to ensure that the code is more readable. I would like to be able to add a template with a title block but at the moment this feature isn't working.
Here is the full code in case it might provide further insight:
metadata: title: BNC <-> 4 mm Banana pn: BNC2Banana01 authors: Created: 2025-09-14 name: Lang date: 2025-09-14 Approved: name: Lang date: 2025-09-14 revisions: A: name: Lang date: 2025-09-14 changelog: Initial commit template: name: din-6771 sheetsize: A3 connectors: 4mm_Red_Banana: &4mm_Banana_t # https://uk.rs-online.com/web/p/banana-connectors/2080252 pinlabels: [+VE] type: 4 mm Red Banana Connector manufacturer: RS Components mpn: 2080252 supplier: uk.rs-online.com spn: 2080252 subtype: male color: RD image: src: IMG/4mm.Red.Banana.png 4mm_Black_Banana: # https://uk.rs-online.com/web/p/banana-connectors/2080251 <<: *4mm_Banana_t pinlabels: [GND] type: 4 mm Black Banana Connector mpn: 2080251 spn: 2080251 color: BK image: src: IMG/4mm.Black.Banana.png BNC_SCREW_Terminal: # https://uk.rs-online.com/web/p/coaxial-adapters/1242521 pinlabels: [+VE, GND] type: BNC Connector Male - Screw Terminal manufacturer: RS Components mpn: 1242521 supplier: RS Components spn: 1242521 subtype: female color: BK image: src: IMG/BNC-SCREW-TERM-MALE.png cables: C: colors: [RD, BK] # number of wires implicit in color list gauge: 0.25 mm2 # also accepts AWG as unit show_equiv: true # auto-calculate AWG equivalent from metric gauge length: 0.4 # length in m shield: false mpn: UL1007-24AWG connections: - - BNC_SCREW_Terminal: [1] - C.C1: [1] - 4mm_Red_Banana: [1] - - BNC_SCREW_Terminal: [2] - C.C1: [2] - 4mm_Black_Banana: [1]
It is possible to use WireViz using Linux but I haven't had the time to try it. I am confident it works just as well.
I used this blog post as reference material for this post but I changed it slightly. If blog readers need more examples on how to use WireViz please leave a comment below.
