nur Bahnhof

Document Home Cabling

So you are doing some renovations and want to document where you put which cables?

I used wireviz to document cable connections in plain text and have something generate fancy images.

The examples here use german cable names (e.g. NYM-J), descriptions and [images]https://de.wikipedia.org/wiki/Liste_der_Schaltzeichen_(Elektrik/Elektronik):

Example cabling diagram, see end of post for the text source

Example cabling diagram, see end of post for the text source

Wireviz uses YAML as input format, the files can be split in three parts:

Connectors

This describes all parts where cables can be connected to.

 1connectors:
 2  # Template connectors
 3  1NPE: &1npe
 4    pinlabels: ["GND", "L1", "N"]
 5    pincolors: ["YEGN", "BN", "BU"]
 6    show_pincount: false
 7
 8  3NPE: &3npe
 9    pinlabels: ["GND", "L1", "N", "L2", "L3"]
10    pincolors: ["YEGN", "BN", "BU", "BK", "GY"]
11    show_pincount: false
12
13  WandVerteilerDose-1: &wandverteilerdose1
14    <<: *1npe
15    type: Verteilerdose
16  WandVerteilerDose-3: &wandverteilerdose3
17    <<: *3npe
18    type: Verteilerdose
19
20  WechselSchalter:
21    <<: *3npe
22    image:
23      src: ../../../static/static/wireviz/../../../static/static/wireviz/resources/Symbol_change_over_switch.svg.png
24
25  SchukoSteckdose:
26    <<: *1npe
27    type: Schuko
28    subtype: female
29    image:
30      src: ../../../static/static/wireviz/resources/Symbol_earthing_contact_plug_socket.svg.png
31      caption: CEE 7/3
32  HerdAnschluss:
33    <<: *3npe
34    type: 3/N/PE
35
36  Lampe:
37    <<: *1npe
38    image:
39      src: ../../../static/static/wireviz/resources/IEC_60417_-_Ref-No_5115.svg.png
40      height: 35
41
42  # Individual connectors
43  DoseStromquelle:
44    <<: *wandverteilerdose1
45    notes: "Stromquelle 🗲"

Going through that bit by bit:

Base cables

1  1NPE: &1npe
2# and
3  3NPE: &3npe

These are also the base of most other parts, depending on of they have two or three connections. They are resused elesewhere via yaml magic (<<: *1npe).

Wall connections

WandVerteilerDose-1 / -3, same as above, but with added type:.

Switch

(this part needs to be changed, they only have three connections, not 5)

Wechselschalter, same as 3NPE, bit with an added image.

Wall sockets

SchukoSteckdose and HerdAnschluss, normal german wall sockets and a special one for an electric hob.

Individual connectors

To mark the energy source in the wall I reused wandverteilerdose1 and added a note.

Cables

 1
 2cables:
 3  NYMJ-3-15: &nymj3
 4    type: "NYM-J"
 5    wirecount: 3
 6    length: 1
 7    gauge: 1.5 mm2
 8    colors: ["YEGN", "BN", "BU"]
 9  NYMJ-5-15: &nymj5
10    <<: *nymj3
11    type: "NYM-J"
12    wirecount: 5
13    gauge: 1.5 mm2
14    colors: ["YEGN", "BN", "BU", "BK", "GY"]
15
16  NYMJ-3-25:
17    <<: *nymj3
18    gauge: 2.5 mm2
19  NYMJ-5-25:
20    <<: *nymj5
21    gauge: 2.5 mm2
22
23  EinzelAder:
24    <<: *nymj3
25    wirecount: 1
26    colors: [BN]

The same setup as with the connectors, base with 1.5 mm2, three and five wires, then duplicated with thicker wire.

EinzelAder is used as simple connection between two points where I don’t need the others.

Connections

 1connections:
 2  # connection in the wall with the live wire to the first switch
 3  - - DoseStromquelle: [2]
 4    - EinzelAder.: [1]
 5    - WechselSchalter.SchalterEins: [2]
 6
 7  # ground and neutral connection to the lamp
 8  - - DoseStromquelle: [1, 3]
 9    - NYMJ-5-15.KabelZwischenSchaltern: [1, 3]
10    - Lampe.Lampe1: [1, 3]
11
12  # connection between switches
13  - - WechselSchalter.SchalterEins: [L2, L3]
14    - NYMJ-5-15.KabelZwischenSchaltern: [4-5]
15    - WechselSchalter.SchalterZwei: [L2, L3]
16
17  # switch to a lamp
18  - - Lampe.Lampe1: [2]
19    - EinzelAder.: [1]
20    - WechselSchalter.SchalterZwei: [2]

A list of connectors and cables, each list makes up one connection and can be longer than what I did here.

I did split it in multiple parts to increase readability and also to make wireviz generate exactly this image. Each connection can also only contain the same amount of pins/wires for all parts in that list.

The pins and wires can be referenced by number (1) or name (L2).

The parts referenced here come from the above connectors/cables. You do not have to create individual ones for each part used here, but can create individual ones, that are only referenced here: GenericCableName.SpecialCableName

If you omit the last part, you will get e.g. a cable without additional identifier GenericCableName. (keep the trailing dot).

Automate generation of images when source changes

1fd  '\.wireviz\.yaml' content | entr wireviz /_

I use fd (you might know find) to search for files ending in .wireviz.yaml in a directory named content (I use hugo to generate this blog, thats where it expects stuff). All file paths are then given to entr, which will run wireviz ${filepath} each time a file changes on disk.

That way I don’t have to run wireviz manually each time I change something.

VSCode

When you use VSCode, you can install a run on save and e.g. Graphviz Interactive Preview extension, add this to your config file:

1    "emeraldwalk.runonsave": {
2        "commands": [
3            {
4                "match": "\\.yml$",
5                "cmd": "wireviz --format ghpst ${file}"
6            },
7        ]
8    }

This will also run wireviz, generate graphviz as output file, which you then can open/preview in VSCode.

Source of the diagram

 1# images from wikipedia, CC-0
 2# <https://de.wikipedia.org/wiki/Liste_der_Schaltzeichen_(Elektrik/Elektronik)>
 3
 4title: "Verkabelung Wechselschalter mit Licht"
 5
 6connectors:
 7  #
 8  ## three wires, earth, live, neutral
 9  1NPE: &1npe
10    pinlabels: ["GND", "L1", "N"]
11    pincolors: ["YEGN", "BN", "BU"]
12    show_pincount: false
13
14  ## same as above but with two additional live wires
15  3NPE: &3npe
16    pinlabels: ["GND", "L1", "N", "L2", "L3"]
17    pincolors: ["YEGN", "BN", "BU", "BK", "GY"]
18
19  WandVerteilerDose-1: &wandverteilerdose1
20    <<: *1npe
21    type: Verteilerdose
22  WandVerteilerDose-3: &wandverteilerdose3
23    <<: *3npe
24    type: Verteilerdose
25
26  WechselSchalter:
27    <<: *3npe
28    image:
29      src: ../../../static/static/wireviz/../../../static/static/wireviz/resources/Symbol_change_over_switch.svg.png
30
31  SchukoSteckdose:
32    <<: *1npe
33    type: Schuko
34    subtype: female
35    image:
36      src: ../../../static/static/wireviz/resources/Symbol_earthing_contact_plug_socket.svg.png
37      caption: CEE 7/3
38  HerdAnschluss:
39    <<: *3npe
40    type: 3/N/PE
41
42  Lampe:
43    <<: *1npe
44    image:
45      src: ../../../static/static/wireviz/resources/IEC_60417_-_Ref-No_5115.svg.png
46      height: 35
47
48  # Individual connectors
49  DoseStromquelle:
50    <<: *wandverteilerdose1
51    notes: "Stromquelle 🗲"
52
53cables:
54  NYMJ-3-15: &nymj3
55    type: "NYM-J"
56    wirecount: 3
57    length: 1
58    gauge: 1.5 mm2
59    colors: ["YEGN", "BN", "BU"]
60  NYMJ-5-15: &nymj5
61    <<: *nymj3
62    type: "NYM-J"
63    wirecount: 5
64    gauge: 1.5 mm2
65    colors: ["YEGN", "BN", "BU", "BK", "GY"]
66
67  NYMJ-3-25:
68    <<: *nymj3
69    gauge: 2.5 mm2
70  NYMJ-5-25:
71    <<: *nymj5
72    gauge: 2.5 mm2
73
74  EinzelAder:
75    <<: *nymj3
76    wirecount: 1
77    colors: [BN]
78
79connections:
80  - - DoseStromquelle: [2]
81    - EinzelAder.: [1]
82    - WechselSchalter.SchalterEins: [2]
83
84  - - DoseStromquelle: [1, 3]
85    - NYMJ-5-15.KabelZwischenSchaltern: [1, 3]
86    - Lampe.Lampe1: [1, 3]
87
88  - - WechselSchalter.SchalterEins: [L2, L3]
89    - NYMJ-5-15.KabelZwischenSchaltern: [4-5]
90    - WechselSchalter.SchalterZwei: [L2, L3]
91
92  - - Lampe.Lampe1: [2]
93    - EinzelAder.: [1]
94    - WechselSchalter.SchalterZwei: [2]

Comments

#documentation #wireviz

Reply to this post by email ↪