Skip to content

syntax.md

Latest commit

 

History

History
443 lines (344 loc) · 19.2 KB

syntax.md

File metadata and controls

443 lines (344 loc) · 19.2 KB

WireViz Syntax

Main sections

connectors:  # dictionary of all used connectors
  <str>   :    # unique connector designator/name
    ...          # connector attributes (see below)
  <str>   :
    ...
  ...

cables:      # dictionary of all used cables and wires
  <str>   :    # unique cable designator/name
    ...          # cable attributes (see below)
  <str>   :
    ...
  ...

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)
  ...

metadata:  # dictionary of meta-information describing the harness
  <key>   : <value>  # any number of key value pairs (see below)
  ...

options:  # dictionary of common attributes for the whole harness
  <str>   : <value>  # optional harness attributes (see below)
  ...

Connector attributes

<str>   :  # unique connector designator/name
  # general information about a connector (all optional)
  type: <str>
  subtype: <str>
  color: <color>  # see below
  image: <image>  # see below
  notes: <str>

  # product information (all optional)
  ignore_in_bom: <bool>  # if set to true the connector is not added to the BOM
  pn: <str>              # [internal] part number
  manufacturer: <str>    # manufacturer name
  mpn: <str>             # manufacturer part number
  supplier: <str>        # supplier name
  spn: <str>             # supplier part number
  additional_components: # additional components
    - <additional-component> # additional component (see below)

  # pinout information
  # at least one of the following must be specified
  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

  # pin color marks (optional)
  pincolors: <List>  # list of colors to be assigned to the respective pins;
                     # if list length is lower than connector pinout,
                     # no color marks will be added to remaining pins

  # rendering information (all optional)
  bgcolor: <color>       # Background color of diagram connector box
  bgcolor_title: <color> # Background color of title in diagram connector box
  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
  loops: <List[loop]>  # every list item is a loop object representing two pins
                 # on the connector that are to be shorted
	  loop:
		- <first>: the first <pin> of the loop
		- <second>: the second <pin> of the loop
		- <side>: either "LEFT" or "RIGHT"
		- show_label: <bool> defaults to true, will show the loop label

Cable attributes

<str>   :  # 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: <str>
  gauge: <int/float/str>  # allowed formats:
                          # <int/float> mm2  is understood
                          # <int> AWG        is understood
                          # <int/float>      is assumed to be mm2
                          # <str>            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>[ <unit>]  # <int/float> is assumed to be in meters unless <unit> is specified
                                # e.g. length: 2.5 -> assumed to be 2.5 m
                                # or   length: 2.5 ft -> "ft" is used as the unit
                                # Units are not converted during BOM generation;
                                # different units result in separate BOM entries.
  shield: <bool/color>  # defaults to false
                        # setting to true will display the shield as a thin black line
                        # using a color (see below) will render the shield in that color
                        # A shield can be accessed by using 's' as the wire ID
  color: <color>  # see below
  image: <image>  # see below
  notes: <str>

  # product information (all optional)
  ignore_in_bom: <bool>  # if set to true the cable or wires are not added to the BOM
  pn: <str>              # [internal] part number
  manufacturer: <str>    # manufacturer name
  mpn: <str>             # manufacturer part number
  supplier: <str>        # supplier name
  spn: <str>             # supplier part number
  additional_components: # additional components
    - <additional-component> # additional component (see below)

  # 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)

  wirelabels: <List>  # optional; one label for each wire

  # rendering information (all optional)
  bgcolor: <color>          # Background color of diagram cable box
  bgcolor_title: <color>    # Background color of title in diagram cable box
  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.

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.
  • <pin> may reference a pin's unique ID (as per the connector's pins attribute, auto-numbered from 1 by default) or its label (as per pinlabels).
  • <wire> may reference a wire's number within a cable/bundle, its label (as per wirelabels) or, if unambiguous, its color.

Single connections

Connectors

  • - <designator>: <int/str>, <str>__<int> 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/str> 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.

    • __ where str is the name of the pin and int is it's number. This can be used to differentiate pins which have the same label (i.e. GND)

    • 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.
    • <str> to refer to a wire's label or color, if unambiguous.
## Metadata entries

```yaml
  # Meta-information describing the harness

  # Valus supported can be found in src/wireviz/metadata.py

Options

  # Common attributes for the whole harness.
  # All entries are optional and have default values.

  # Background color of diagram and HTML output
  bgcolor: <color>             # Default = 'WH'

  # Background color of other diagram elements
  bgcolor_node: <color>        # Default = 'WH'
  bgcolor_connector: <color>   # Default = bgcolor_node
  bgcolor_cable: <color>       # Default = bgcolor_node
  bgcolor_bundle: <color>      # Default = bgcolor_cable

  # How to display colors as text in the diagram
  # 'full' : Lowercase full color name
  # 'FULL' : Uppercase full color name
  # 'hex'  : Lowercase hexadecimal values
  # 'HEX'  : Uppercase hexadecimal values
  # 'short': Lowercase short color name
  # 'SHORT': Uppercase short color name
  # 'ger'  : Lowercase short German color name
  # 'GER'  : Uppercase short German color name
  color_mode: <str>            # Default = 'SHORT'

  # Fontname to use in diagram and HTML output
  fontname: <str>              # Default = 'arial'

  # If True, show only a BOM entry reference together with basic info
  # about additional components inside the diagram node (connector/cable box).
  # If False, show all info about additional components inside the diagram node.
  mini_bom_mode: <bool>        # Default = True

BOM items and additional components

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 items can be added to the BOM as either part of a connector or cable or on their own.

Parts can be added to a connector or cable in the section <additional-component> which will also list them in the graph.

-
  type: <str>  # type of additional component
  # all the following are optional:
  subtype: <str>  # additional description (only shown in bom)
  qty: <int/float>  # qty to add to the bom (defaults to 1)
  qty_multiplier: <str>  # multiplies qty by a feature of the parent component
                  # when used in a connector:
                  # pincount         number of pins of connector
                  # populated        number of populated positions in a connector
                  # when used in a cable:
                  # wirecount        number of wires of cable/bundle
                  # terminations     number of terminations on a cable/bundle
                  # length           length of cable/bundle
                  # total_length     sum of lengths of each wire in the bundle
  unit: <str>
  pn: <str>            # [internal] part number
  manufacturer: <str>  # manufacturer name
  mpn: <str>           # manufacturer part number
  supplier: <str>      # supplier name
  spn: <str>           # supplier part number
  bgcolor: <color>     # Background color of entry in diagram component box

Alternatively items can be added to just the BOM by putting them in the section <bom-item> above.

-
  description: <str>
  # all the following are optional:
  qty: <int/float>  # qty to add to the bom (defaults to 1)
  unit: <str>
  designators: <List>
  pn: <str>            # [internal] part number
  manufacturer: <str>  # manufacturer name
  mpn: <str>           # manufacturer part number
  supplier: <str>      # supplier name
  spn: <str>           # supplier part number

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 ##000000 (black)
  • WH ##ffffff (white)
  • GY ##999999 (grey)
  • PK ##ff66cc (pink)
  • RD ##ff0000 (red)
  • OG ##ff8000 (orange)
  • YE ##ffff00 (yellow)
  • OL ##708000 (olive green)
  • GN ##00ff00 (green)
  • TQ ##00ffff (turquoise)
  • LB ##a0dfff (light blue)
  • BU ##0066ff (blue)
  • VT ##8000ff (violet)
  • BN ##895956 (brown)
  • BG ##ceb673 (beige)
  • IV ##f5f0d0 (ivory)
  • SL ##708090 (slate)
  • CU ##d6775e (copper)
  • SN ##aaaaaa (tin)
  • SR ##84878c (silver)
  • GD ##ffcf80 (gold)

It is also possible to specify colors as hexadecimal RGB values, e.g. #112233 or #FFFF00:#009900. Remember quoting strings containing a # in the YAML file.

Cable color codes

Supported color codes:

Images

Both connectors and cables accept including an image with a caption within their respective nodes.

image:
  src: <path>        # path to the image file
  # optional parameters:
  caption: <str>     # text to display below the image
  bgcolor: <color>   # Background color of entry in diagram component box
  width: <int>       # range: 1~65535; unit: points
  height: <int>      # range: 1~65535; unit: points
  # if only one dimension (width/height) is specified, the image is scaled proportionally.
  # if both width and height are specified, the image is stretched to fit.

For more fine grained control over the image parameters, please see advanced_image_usage.md.

Multiline strings

The following attributes accept multiline strings:

  • type
  • subtype (connectors only)
  • notes
  • manufacturer
  • mpn
  • supplier
  • spn
  • image.caption

Method 1

By using |, every following indented line is treated as a new line.

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.

attribute: "This is line 1.\nThis is line 2."

Plain (no quotes) or single quoted strings do not convert \n.

See yaml-multiline.info for more information.

Inheritance

YAML anchors and references are useful for defining and referencing information that is used more than once in a file, e.g. when using defining multiple connectors of the same type or family. See Demo 02 for an example.