WireViz cables and wire bundles

Complete cable schema, gauge and length units, wire count inference, shields, color palettes, bundle part numbers, and native defaults.

A cable contains numbered conductors and can optionally have a shield. A bundle uses the same connection model but represents separate wires in the BOM. This page follows the 0.4.1 Cable implementation and BOM generator.

A cable definition

cables:
  W1:
    type: Shielded sensor cable
    gauge: 22 AWG
    length: 1.25 m
    colors: [RD, BK, WH]
    wirelabels: [SUPPLY, RETURN, SIGNAL]
    shield: SN
    color: BK

This is a definition fragment; reference W1 in connections to include it in the harness. color describes the outer cable, while colors describes individual conductors. shield is separate from those conductors and is addressed as s in a connection. See the shielded cable example.

Complete field reference

Field	Value	Behavior or default
Mapping key	String	Cable definition/designator, for example `W1`; do not add a `name` property.
`type`	Text	Cable or wire type description.
`category`	String	`bundle` enables individual-wire presentation and BOM behavior; omit for a normal cable.
`gauge`	Number or value-and-unit text	Optional; a bare number defaults to mm².
`gauge_unit`	String	Unit for a numeric gauge, commonly `AWG` or `mm²`.
`show_equiv`	Boolean	Default false; adds the library's approximate AWG/mm² lookup value to the diagram.
`length`	Number or value-and-unit text	Default `0`; a bare number defaults to metres.
`length_unit`	String	Default `m` for a numeric length.
`wirecount`	Integer	Count of regular conductors; inferred from nonempty `colors` when omitted.
`colors`	List of color strings	Per-wire colors; default empty, with inference and repetition rules below.
`color_code`	Palette name	`DIN`, `IEC`, `BW`, `TEL`, `TELALT`, `T568A`, or `T568B`.
`wirelabels`	List of integers or strings	Labels aligned with numbered wires; default empty list. Nonnumeric text is usually the clearest reference.
`color`	Color	Outer cable color.
`shield`	Boolean or color	Default false. `true` adds a shield; a color such as `SN` also selects its color.
`manufacturer`	Text or bundle list	Manufacturer name.
`mpn`	Text or bundle list	Manufacturer part number.
`supplier`	Text or bundle list	Supplier name.
`spn`	Text or bundle list	Supplier part number.
`pn`	Text or bundle list	Internal part number.
`image`	Image mapping	Optional image; see images.
`notes`	Multiline text	Notes within the component box.
`bgcolor`	Color	Component box background override.
`bgcolor_title`	Color	Designator/title row background override.
`show_name`	Boolean	Defaults to true except for anonymous generated names.
`show_wirecount`	Boolean	Default true.
`show_wirenumbers`	Boolean	Defaults to true for a regular cable, false for a bundle.
`ignore_in_bom`	Boolean	Default false; excludes the cable or bundle wires' automatic BOM entries.
`additional_components`	List of component mappings	Associated parts; default empty list.

Numeric values and units

These two forms are equivalent ways to declare a 22 AWG cable:

gauge: 22
gauge_unit: AWG

gauge: 22 AWG

gauge: 22 alone means 22 mm², not 22 AWG. Likewise, length: 1.25 means 1.25 m. To use another length unit, write length: 2 ft or use numeric length: 2 and length_unit: ft.

The value-and-unit form is split on a single space. A quoted numeric-only string such as length: "1.25" fails; use the YAML number 1.25. Extra spaces can also prevent parsing. An inline unit takes precedence over the separate unit field and produces a warning if both are present. Inline awg is normalized to AWG, and inline mm2 becomes mm².

The library does not convert stored cable lengths or normalize mixed-unit BOM totals. Choose consistent units before aggregating material requirements. show_equiv uses a fixed approximate gauge lookup table and can show Unknown for a value absent from that table. It is a display aid, not a conductor-sizing calculation. Gauge helper source.

Unit labels are not an exhaustive validated enumeration. The gauge string parser also accepts tokens such as 4/0 AWG; a value being accepted does not guarantee an equivalence-table entry. Numeric zero gauge is another release-specific edge case: it can pass parsing but be omitted by truth-value checks in parts of the diagram/BOM description. Review the generated output when using zero-AWG notation or custom gauge formats.

Wire count and palette precedence

With an explicit positive wirecount, nonempty colors takes priority over color_code. The selected palette repeats if it is shorter than the count and is truncated if it is longer. With neither palette, the engine creates blank color entries.

Without an explicit count, a nonempty colors list determines the count. A color_code alone is insufficient because the parser does not infer how many palette colors you intend to use. wirelabels also does not infer the count. A shield does not increase wirecount.

Wire numbers are one-based. Unique colors and unique wire labels can also identify conductors in normal cable connections. Repeated colors are valid visually, but cannot be used as an unambiguous reference. The label s is prohibited on a shielded cable because it is reserved for the shield. Keep the wire-label list aligned with the actual conductor count.

Bundles and per-wire purchasing information

connectors:
  X1: {pincount: 2}
  X2: {pincount: 2}
cables:
  W1:
    category: bundle
    gauge: 0.5
    length: 0.75
    colors: [RD, BK]
    manufacturer: Example Wire
    mpn: [WIRE-RED, WIRE-BLACK]
connections:
  - - X1: [1, 2]
    - W1: [1, 2]
    - X2: [1, 2]

A bundle has a dashed outline in the native diagram and contributes each wire to the BOM at the bundle's length. The five product-information fields accept either one value shared by every wire or a list with exactly wirecount entries. Lists are rejected for a regular cable. One bundle still has a common gauge and length; use separate cable/bundle definitions when these differ between wires. Open the wire bundle example.