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
Ok so the code is fairly easy to read...lets break things down:
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_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]
The next section of the code relates to the cable itself (cables: Section). We want to use something sensible but we only need two wires and I would like to specify the insulation jacket colour and the length as well as the gauge. To achieve that we can update the code as follows:
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
I have chosen to call the cable C as opposed to W1. It makes more sense to me. Feel free to use your own variable names...
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]
The entire code for reference looks like this:
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!
Jump into a command prompt and navigate to the directory where you have saved your YAML code:
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:
Essentially 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:
The rest of the code should be self explanatory.
We now need to obtain some images of our connectors. I downloaded some stock images with white backgrounds:
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.
I think that's all for now - take care always - Langster!