266 lines
10 KiB
Markdown
266 lines
10 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
|
|
|
|
<!-- TODO -->
|
|
|
|
## 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
|
|
|
|
<!-- TODO -->
|
|
|
|
## 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.
|
|
|
|
<!-- TODO -->
|
|
: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.
|