WireViz connection sets and branching

The connections section is an ordered list of connection sets. Each set describes one or more parallel paths through alternating connector and cable entries. WireViz does not impose a two-endpoint harness model: a path can pass through several cables and connectors, and several paths can share a connector pin. The rules come from the 0.4.1 parser and connection resolver.

A set is a table of parallel lanes

connectors:
  X1: {pincount: 4}
  X2: {pincount: 4}
cables:
  W1:
    colors: [RD, BK, WH, BU]
    length: 1
connections:
  - - X1: [1, 2, 3, 4]
    - W1: [1, 2, 3, 4]
    - X2: [4, 3, 2, 1]

Read the lists by position. The first lane is X1:1 → W1:1 → X2:4. The fourth lane is X1:4 → W1:4 → X2:1. All explicitly supplied lists in one set must expand to the same length.

Each mapping entry should contain exactly one component designator. A set has at least one entry and can start or end with a cable. Components must alternate between connector and cable/arrow positions; two cables directly adjacent to one another are not valid.

Selector forms

Bare designators are useful for simple terminals whose actual ID is numeric 1. They do not mean “select whichever pin exists.” Use explicit selectors for custom pin IDs.

Normal cable connections resolve a pin label to its corresponding pins entry and a color or wire label to its conductor number. Duplicated labels/colors cannot serve as references. If the same token occurs in both alternative naming lists at different positions, the reference is also ambiguous. Numeric-looking selector strings are converted to integers during range expansion; see the YAML reference for consequences with IDs such as "01".

Shields and open ends

connectors:
  X1:
    pins: [1, 2, SH]
  X2:
    pins: [1, 2]
cables:
  W1:
    colors: [WH, BU]
    shield: SN
    length: 1
connections:
  - - X1: [1, 2]
    - W1: [1, 2]
    - X2: [1, 2]
  - - X1: SH
    - W1: s

The shield is connected only at X1; ending that set with the cable leaves the other endpoint unspecified. A set beginning with a cable similarly leaves its left endpoint unspecified. The shield does not consume an ordinary wire number. See the shielded cable example.

Branch through a named splice

connectors:
  X1: {pincount: 1}
  X2: {pincount: 1}
  X3: {pincount: 1}
  S1:
    style: simple
    type: Three-way splice
    show_name: true
cables:
  W1: {colors: [RD], length: 0.4}
  W2: {colors: [RD], length: 0.3}
  W3: {colors: [RD], length: 0.6}
connections:
  - [X1, W1, S1]
  - [S1, W2, X2]
  - [S1, W3, X3]

All three paths use the same S1 pin. The splice is a normal simple connector with a descriptive type; WireViz does not infer a manufacturing process or splice capacity from that description. A named instance is essential when the same splice is referenced repeatedly. See the branched harness example.

Connector mating without a cable

Single-line arrows join individual pins. A list supplies the arrow for each parallel lane. Double-line arrows join connector components as a whole.

connectors:
  X1: {pincount: 2}
  X2: {pincount: 2}
  X3: {pincount: 2}
connections:
  - - X1: [1, 2]
    - ["--", "<-->"]
    - X2: [1, 2]
  - [X2, "<==>", X3]

Arrows occupy cable positions and cannot be the first or last item in a set. They create no cable, gauge, length, or cable BOM entry. Use actual pin IDs for pin-mating arrows: that code path does not run the same label-resolution routine as normal cable connections. Arrow direction controls the drawing and does not establish electrical signal validation.

Include an unconnected component

connectors:
  X1: {pincount: 4}
connections:
  - [X1]

This instantiates X1 even without wires. Merely defining X1 under connectors would leave it unused and absent from the generated harness. Connector loops can be added independently through the connector properties.