350 lines
15 KiB
Markdown
350 lines
15 KiB
Markdown
# WireViz Syntax
|
|
|
|
## Main sections
|
|
|
|
```yaml
|
|
connectors: # dictionary of all used connectors
|
|
<string>: # unique connector designator/name
|
|
... # connector attributes (see below)
|
|
<string>:
|
|
...
|
|
...
|
|
|
|
cables: # dictionary of all used cables and wires
|
|
<string>: # unique cable designator/name
|
|
... # cable attributes (see below)
|
|
<string>:
|
|
...
|
|
...
|
|
|
|
connections: # list of all connections to be made
|
|
# between cables and connectors
|
|
-
|
|
... # connection set (see below)
|
|
-
|
|
...
|
|
...
|
|
|
|
additional_bom_items: # custom items to add to BOM
|
|
- <bom-item> # BOM item (see below)
|
|
...
|
|
|
|
```
|
|
|
|
## Connector attributes
|
|
|
|
```yaml
|
|
<string>: # unique connector designator/name
|
|
# general information about a connector (all optional)
|
|
type: <string>
|
|
subtype: <string>
|
|
color: <color> # see below
|
|
notes: <string>
|
|
|
|
# product information (all optional)
|
|
manufacturer: <string>
|
|
manufacturer_part_number: <string>
|
|
internal_part_number: <string>
|
|
|
|
# pinout information
|
|
# at least one of the following must be specified
|
|
# if more than one is specified, list lenghts must match pincount, and each other
|
|
pincount: <int> # if omitted, is set to length of specified list(s)
|
|
pins: <List> # if omitted, is autofilled with [1, 2, ..., pincount]
|
|
pinlabels: <List> # if omitted, is autofilled with blanks
|
|
|
|
# rendering information (all optional)
|
|
style: <style> # may be set to simple for single pin connectors
|
|
show_name: <bool> # defaults to true for regular connectors,
|
|
# false for simple connectors
|
|
show_pincount: <bool> # defaults to true for regular connectors
|
|
# false for simple connectors
|
|
hide_disconnected_pins: <bool> # defaults to false
|
|
|
|
# loops and shorts (#48)
|
|
loops: <List> # TODO
|
|
|
|
# BOM options (all optional)
|
|
ignore_in_bom: <bool> # defaults to false TODO
|
|
bom_items: # list of additional BOM entries for this cable/bundle TODO
|
|
- <bom-item> # BOM item (see below)
|
|
...
|
|
|
|
# auto-generation
|
|
autogenerate: <bool> # optional; defaults to false; see below
|
|
|
|
```
|
|
|
|
### Auto-generation of connectors
|
|
|
|
The `autogenerate: true` option is especially useful for very simple, recurring connectors such as crimp ferrules, splices, and others, where it would be a hassle to individually assign unique designators for every instance.
|
|
|
|
By default, when defining a connector, it will be generated once using the specified designator, and can be referenced multiple times, in different connection sets (see below).
|
|
|
|
If `autogenerate: true` is set, the connector will _not_ be generated at first. When defining the `connections` section (see below), every time the connector is mentioned, a new instance with an auto-incremented designator is generated and attached.
|
|
|
|
Since the auto-incremented and auto-assigned designator is not known to the user, one instance of the connector can not be referenced again outside the point of creation. The `autogenerate: true` option is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out. If more wires are to be attached (e.g. for a three-way splice, or a crimp where multiple wires are joined), a separate connector with `autogenerate: false` and a user-defined, unique designator needs to be used.
|
|
|
|
## Cable attributes
|
|
|
|
```yaml
|
|
<string>: # unique cable designator/name
|
|
# general information about a connector (all optional)
|
|
category: <category> # may be set to bundle;
|
|
# generates one BOM item for every wire in the bundle
|
|
# instead of a single item for the entire cable;
|
|
# renders with a dashed outline
|
|
type: <string>
|
|
gauge: <int/float/string> # allowed formats:
|
|
# <int/float> is assumed to be mm2
|
|
# <int/float> mm2 is understood
|
|
# <int> AWG is understood
|
|
# <string> custom units and formats are allowed
|
|
# but unavailable for auto-conversion
|
|
show_equiv: <bool> # defaults to false; can auto-convert between mm2 and AWG
|
|
# and display the result when set to true
|
|
length: <int/float> # is assumed to be in meters
|
|
shield: <bool> # defaults to false
|
|
# the shield can be accessed in connections
|
|
# using 's' as the wire number
|
|
notes: <string>
|
|
|
|
# product information (all optional)
|
|
manufacturer: <string>
|
|
manufacturer_part_number: <string>
|
|
internal_part_number: <string>
|
|
|
|
# conductor information
|
|
# the following combinations are permitted:
|
|
# wirecount only no color information is specified
|
|
# colors only wirecount is inferred from list length
|
|
# wirecount + color_code colors are auto-generated based on the specified
|
|
# color code (see below) to match the wirecount
|
|
# wirecount + colors colors list is trimmed or repeated to match the wirecount
|
|
wirecount: <int>
|
|
colors: <List> # list of colors (see below)
|
|
color_code: <str> # one of the supported cable color codes (see below)
|
|
|
|
# BOM options (all optional)
|
|
ignore_in_bom: <bool> # defaults to false TODO
|
|
bom_items: # list of additional BOM entries for this cable/bundle TODO
|
|
- <bom-item> # BOM item (see below)
|
|
...
|
|
|
|
# rendering information (all optional)
|
|
show_name: <bool> # defaults to true
|
|
show_wirecount: <bool> # defaults to true
|
|
|
|
```
|
|
|
|
## Connection sets
|
|
|
|
A connection set is used to connect multiple components together. Multiple connections can be easily created in parallel within one connection set, by specifying a list of individual pins (for `connectors`) or wires (for `cables`) for every component along the way.
|
|
|
|
```yaml
|
|
connections:
|
|
- # Each list entry is a connection set
|
|
- <component> # Each connection set is itself a list of items
|
|
- <component> # Items must alternatingly belong to the connectors and cables sections
|
|
-...
|
|
|
|
- # example (single connection)
|
|
- <connector>: <pin> # attach one pin of the connector
|
|
- <cable>: <wire> # attach one wire of the cable
|
|
- <connector> # for simple connectors, pin 1 is implicit
|
|
- <cable>: s # for shielded wires, s attaches to the shield
|
|
|
|
- # example (multiple parallel connections)
|
|
- <connector>: [<pin>, ..., <pin> ] # attach multiple pins in parallel
|
|
- <cable>: [<wire>, ..., <wire>] # attach multiple wires in parallel
|
|
- <connector> # auto-generate a new connector for every parallel connection
|
|
- <cable>: [<wire>-<wire>] # specify a range of wires to attach in parallel
|
|
- [<connector>, ..., <connector>] # specify multiple simple connectors to attach in parallel
|
|
# these may be unique, auto-generated, or a mix of both
|
|
|
|
...
|
|
```
|
|
|
|
- Each connection set is a list of components.
|
|
- The minimum number of items is two.
|
|
- The maximum number of items is unlimited.
|
|
- Items must alternatingly belong to the `connectors` and the `cables` sections.
|
|
- When a connection set defines multiple parallel connections, the number of specified `<pin>`s and `<wire>`s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set.
|
|
|
|
### Single connections
|
|
|
|
#### Connectors
|
|
|
|
- `- <designator>: <int/string>` attaches a pin of the connector, referring to a pin number (from the connector's `pins` attribute) or a pin label (from its `pinlabels` attribute), provided the label is unique.
|
|
|
|
- `- <designator>` is allowed for simple connectors, since they have only one pin to connect.
|
|
For connectors with `autogenerate: true`, a new instance, with auto-generated designator, is created.
|
|
|
|
#### Cables
|
|
|
|
- `<designator>: <wire>` attaches a specific wire of a cable, using its number.
|
|
|
|
### Multiple parallel connections
|
|
|
|
#### Connectors
|
|
|
|
- `- <designator>: [<pin>, ..., <pin>]`
|
|
|
|
Each `<pin>` may be:
|
|
|
|
- `<int/string>` to refer to a specific pin, using its number (from its `pins` attribute) or its label (from its `pinlabels` attribute, provided the label is unique for this connector)
|
|
|
|
- `<int>-<int>` auto-expands to a range. E.g. `1-4` auto-expands to `1,2,3,4`; `9-7` will auto-expand to `9,8,7`.
|
|
|
|
- Mixing types is allowed, e.g. `[<pin>, <pinlabel>, <pin>-<pin>, <pin>]`
|
|
|
|
- `- [<designator>, ..., <designator>]`
|
|
|
|
Attaches multiple different single pin connectors, one per connection in the set.
|
|
For connectors with `autogenerate: true`, a new instance, with auto-generated designator, is created with every mention.
|
|
Auto-generated and non-autogenerated connectors may be mixed.
|
|
|
|
- `- <designator>`
|
|
|
|
Attaches multiple instances of the same single pin connector, one per connectioin in the set.
|
|
For connectors with `autogenerate: true`, a new instance, with auto-generated designator, is created for every connection in the set.
|
|
Since only connectors with `pincount: 1` can be auto-generated, pin number 1 is implicit.
|
|
|
|
#### Cables
|
|
|
|
- `<designator>: [<wire>, ..., <wire>]`
|
|
|
|
Each `<wire>` may be:
|
|
|
|
- `<int>` to refer to a specific wire, using its number.
|
|
- `<int>-<int>` auto-expands to a range.
|
|
|
|
|
|
## BOM items
|
|
|
|
Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM,
|
|
unless the `ignore_in_bom` attribute is set to `true`.
|
|
|
|
Additional BOM entries can be generated in the sections marked `<bom-item>` above.
|
|
|
|
<!-- :warning: BOM items inside connectors/cables are not implemented yet, but should be soon (#50) -->
|
|
|
|
```yaml
|
|
-
|
|
description: <string>
|
|
qty: <int/string> # when used in the additional_bom_items section:
|
|
# <int> manually specify qty.
|
|
# when used within a component:
|
|
# <int> manually specify qty.
|
|
# pincount match number of pins of connector
|
|
# wirecount match number of wires of cable/bundle
|
|
# connectioncount match number of connected pins
|
|
# all the following are optional:
|
|
unit: <string>
|
|
designators: <List>
|
|
manufacturer: <string>
|
|
manufacturer_part_number: <string>
|
|
internal_part_number: <string>
|
|
```
|
|
|
|
## Colors
|
|
|
|
Colors are defined via uppercase, two character strings.
|
|
Striped/banded wires can be specified by simply concatenating multiple colors, with no space inbetween, eg. `GNYE` for green-yellow.
|
|
|
|
The following colors are understood:
|
|
|
|
- `BK`  (black)
|
|
- `WH`  (white)
|
|
- `GY`  (grey)
|
|
- `PK`  (pink)
|
|
- `RD`  (red)
|
|
- `OG`  (orange)
|
|
- `YE`  (yellow)
|
|
- `OL`  (olive green)
|
|
- `GN`  (green)
|
|
- `TQ`  (turquoise)
|
|
- `LB`  (light blue)
|
|
- `BU`  (blue)
|
|
- `VT`  (violet)
|
|
- `BN`  (brown)
|
|
- `BG`  (beige)
|
|
- `IV`  (ivory)
|
|
- `SL`  (slate)
|
|
- `CU`  (copper)
|
|
- `SN`  (tin)
|
|
- `SR`  (silver)
|
|
- `GD`  (gold)
|
|
|
|
<!-- color list generated with a helper script: -->
|
|
<!-- https://gist.github.com/formatc1702/3c93fb4c5e392364899283f78672b952 -->
|
|
|
|
## Cable color codes
|
|
|
|
Supported color codes:
|
|
|
|
- `DIN` for [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
...
|
|
|
|
- `IEC` for [IEC 62](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) ("ROY G BIV")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
...
|
|
|
|
- `TEL` and `TELALT` for [25-pair color code](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system)
|
|
- `T568A` and `T568B` for [TIA/EIA-568](https://en.wikipedia.org/wiki/TIA/EIA-568#Wiring) (e.g. Ethernet)
|
|
- `BW` for alternating black and white
|
|
|
|
|
|
|
|
## Multiline strings
|
|
|
|
Connectors accept multiline strings in the `type`, `subtype` and `notes` attributes.
|
|
Cables accept multiline strings in the `type` and `notes` attributes.
|
|
|
|
### Method 1
|
|
|
|
By using `|`, every following indented line is treated as a new line.
|
|
|
|
```yaml
|
|
attribute: |
|
|
This is line 1.
|
|
This is line 2.
|
|
```
|
|
|
|
### Method 2
|
|
|
|
By using double quoted strings, `\n` within the string is converted to a new line.
|
|
|
|
```yaml
|
|
attribute: "This is line 1.\nThis is line 2."
|
|
```
|
|
|
|
Plain (no quotes) or single quoted strings do not convert `\n`.
|
|
|
|
See [yaml-multiline.info](https://yaml-multiline.info/) for more information.
|
|
|
|
## Inheritance
|
|
|
|
Add link to YAML spec.
|