Skip to content

Filare 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: # each item shorts two pins on the connector
    - first: <pin> # pin number or pin label
      second: <pin> # pin number or pin label
      side: <LEFT|RIGHT|null> # optional; anchor the loop to a side
      show_label: <bool> # defaults to true; hide the label when false
      color: <color> # optional stroke color
    # shorthand tuple/list form is also allowed:
    # - [<pin>, <pin>]  # treated as {first: <pin>, second: <pin>}

  # example:
  # loops:
  #   - first: 1
  #     second: 2
  #     side: LEFT
  #   - [3, 4]  # uses default side/label/color

Loops mark both pins as connected and render a short jumper on the chosen side (when provided). If side is omitted, Filare chooses a side based on the connector layout. Set show_label: false to hide the loop label for purely visual jumpers, and use color to highlight the jumper trace.

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/filare/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 rendering and pagination
include_bom: <bool> # Default = True
split_bom_page: <bool> # Default = False; when true, BOM renders to <name>.bom.html
bom_rows_per_page: <int> # Optional; when set with split_bom_page, paginate BOM rows with lettered suffixes
bom_force_single_page: <bool> # Default = False; keep BOM on a single page even if bom_rows_per_page is set

# Split tables and index
split_notes_page: <bool> # Default = False; split notes into <name>.notes.html
split_index_page: <bool> # Default = False; split index table into <name>.index.html
table_page_suffix_letters: <bool> # Default = True; use a/b/c suffixes when pagination produces multiple pages

# Cut and termination diagrams
include_cut_diagram: <bool> # Default = False
include_termination_diagram: <bool> # Default = False
cut_rows_per_page: <int> # Optional; paginate cut tables when set
termination_rows_per_page: <int> # Optional; paginate termination tables when set

Importing external SVG diagrams (DrawIO)

You can replace the auto-generated diagram with a DrawIO-exported SVG and control how it is placed on the page:

options:
  diagram_svg:
    src: diagrams/power-page.svg # path to the DrawIO-exported SVG
    width: 90% # optional; defaults to 95% max width
    height: 180mm # optional max/fixed height
    align: left # left, center (default), or right
    offset_x: 5mm # optional translation on the page
    offset_y: 0
    preserve_aspect_ratio: true # set to false to allow stretching

Relative src paths are resolved from the harness YAML file location (and any options.image_paths). The SVG is inlined (including linked images) and used for both HTML and SVG outputs; PDFs generated from HTML will include the imported diagram as well. When diagram_svg is set, PNG output is skipped to avoid mixing Graphviz and DrawIO renders.

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:

##ffffff ##895956 ##00ff00 ##ffff00 ##999999 ##ff66cc ##0066ff ##ff0000 ##000000 ##8000ff ...

##895956 ##ff0000 ##ff8000 ##ffff00 ##00ff00 ##0066ff ##8000ff ##999999 ##ffffff ##000000 ...

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.

Quantity multipliers (shared BOM scaling)

When generating a shared BOM across multiple harnesses, you can scale quantities with a multiplier file:

  1. Run uv run filare-qty <harness.yml> [--multiplier-file-name <path>] [--force-new] to create or update a JSON file (default quantity_multipliers.txt) with {<harness_name>: <int>} entries.
  2. Run uv run filare <harness.yml> --use-qty-multipliers [--multiplier-file-name <path>] ... to apply those multipliers while building shared_bom.tsv.

If the multiplier file is missing, filare-qty prompts for integer values. To protect an existing file, omit --force-new. Place the multiplier file alongside your harnesses or point --multiplier-file-name to a shared location (e.g., outputs/quantity_multipliers.txt).

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.