Filters and variants

The filters and variants are mechanisms used to modify the circuit components. Both concepts are closely related. In fact variants can use filters.

The current implementation of the filters allow to exclude components from some of the processing stages. The most common use is to exclude them from some output. You can also change components fields/properties and also the 3D model.

Variants are currently used to create assembly variants. This concept is used to manufacture one PCB used for various products. You can learn more about KiBot variants on the following example repo. The example is currently using KiCad 6, if you want to see the example files for KiCad 5 go here.

As mentioned above the current use of filters is to mark some components. Mainly to exclude them, but also to mark them as special. This is the case of do not change components in the BoM.

Filters and variants are defined in separated sections. A filter section looks like this:

filters:
 - name: 'a_short_name'
   type: 'generic'
   comment: 'A description'
   # Filter options

Supported filters

  • expand_text_vars: (Expand Text Variables) This filter expands KiCad 6 text variables (${VARIABLE}).

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • include_kicad_env : [boolean=true] Also expand KiCad environment variables.

      • include_os_env : [boolean=false] Also expand system environment variables.

      • name : [string=’’] Used to identify this particular filter definition.

  • field_modify: (Field Modifier) Changes the content of one or more fields.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • fields : [string|list(string)=’Datasheet’] Fields to convert.

      • include : [string|list(string)=’’] Name of the filter to select which components will be affected. Applied to all if nothing specified here.

      • name : [string=’’] Used to identify this particular filter definition.

      • regex : [string=’(https?://\S+)’] Regular expression to match the field content. Only fields that matches will be modified. An empty regex will match anything. The example matches an HTTP URL.

      • replace : [string=’<a href=”\1”>\1</a>’] Text to replace, can contain references to sub-expressions. The example converts an HTTP URL into an HTML link, like the URLify filter.

  • field_rename: (Field Renamer) This filter implements a field renamer.
    The internal _kicost_rename filter emulates the KiCost behavior.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • name : [string=’’] Used to identify this particular filter definition.

      • rename : [list(dict)] Fields to rename.

        • Valid keys:

          • field : [string=’’] Name of the field to rename.

          • name : [string=’’] New name.

  • generic: (Generic filter) This filter is based on regular expressions.
    It also provides some shortcuts for common situations.
    Note that matches aren’t case sensitive and spaces at the beginning and the end are removed.
    The internal _mechanical filter emulates the KiBoM behavior for default exclusions.
    The internal _kicost_dnp filter emulates KiCost’s dnp field.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • config_field : [string=’Config’] Name of the field used to classify components.

      • config_separators : [string=’ ,’] Characters used to separate options inside the config field.

      • exclude_all_hash_ref : [boolean=false] Exclude all components with a reference starting with #.

      • exclude_any : [list(dict)] A series of regular expressions used to exclude parts. If a component matches ANY of these, it will be excluded. Column names are case-insensitive.

        • Valid keys:

          • column : [string=’’] Name of the column to apply the regular expression. Use _field_lcsc_part to get the value defined in the global options.

          • field : Alias for column.

          • invert : [boolean=false] Invert the regex match result.

          • match_if_field : [boolean=false] Match if the field exists, no regex applied. Not affected by invert.

          • match_if_no_field : [boolean=false] Match if the field doesn’t exists, no regex applied. Not affected by invert.

          • regex : [string=’’] Regular expression to match.

          • regexp : Alias for regex.

          • skip_if_no_field : [boolean=false] Skip this test if the field doesn’t exist.

      • exclude_bottom : [boolean=false] Exclude components on the bottom side of the PCB.

      • exclude_config : [boolean=false] Exclude components containing a key value in the config field. Separators are applied.

      • exclude_empty_val : [boolean=false] Exclude components with empty ‘Value’.

      • exclude_field : [boolean=false] Exclude components if a field is named as any of the keys.

      • exclude_not_in_bom : [boolean=false] Exclude components marked Exclude from bill of materials (KiCad 6+).

      • exclude_not_on_board : [boolean=false] Exclude components marked Exclude from board (KiCad 6+).

      • exclude_refs : [list(string)] List of references to be excluded. Use R* for all references with R prefix.

      • exclude_smd : [boolean=false] Exclude components marked as smd in the PCB.

      • exclude_tht : [boolean=false] Exclude components marked as through-hole in the PCB.

      • exclude_top : [boolean=false] Exclude components on the top side of the PCB.

      • exclude_value : [boolean=false] Exclude components if their ‘Value’ is any of the keys.

      • exclude_virtual : [boolean=false] Exclude components marked as virtual in the PCB.

      • include_only : [list(dict)] A series of regular expressions used to include parts. If there are any regex defined here, only components that match against ANY of them will be included. Column/field names are case-insensitive. If empty this rule is ignored.

        • Valid keys:

          • column : [string=’’] Name of the column to apply the regular expression. Use _field_lcsc_part to get the value defined in the global options.

          • field : Alias for column.

          • invert : [boolean=false] Invert the regex match result.

          • match_if_field : [boolean=false] Match if the field exists, no regex applied. Not affected by invert.

          • match_if_no_field : [boolean=false] Match if the field doesn’t exists, no regex applied. Not affected by invert.

          • regex : [string=’’] Regular expression to match.

          • regexp : Alias for regex.

          • skip_if_no_field : [boolean=false] Skip this test if the field doesn’t exist.

      • invert : [boolean=false] Invert the result of the filter.

      • keys : [string|list(string)=dnf_list] [dnc_list,dnf_list] List of keys to match. The dnf_list and dnc_list internal lists can be specified as strings. Use dnf_list for [‘dnf’, ‘dnl’, ‘dnp’, ‘do not fit’, ‘do not load’, ‘do not place’, ‘no stuff’, ‘nofit’, ‘noload’, ‘noplace’, ‘nostuff’, ‘not fitted’, ‘not loaded’, ‘not placed’]. Use dnc_list for [‘dnc’, ‘do not change’, ‘fixed’, ‘no change’].

      • name : [string=’’] Used to identify this particular filter definition.

  • rot_footprint: (Footprint Rotator) This filter can rotate footprints, used for the positions file generation.
    Some manufacturers use a different rotation than KiCad.
    The JLCPCB Rotation Offset and JLCPCB Position Offset fields can be used to adjust special cases.
    The internal _rot_footprint filter implements the simplest case.

    • Valid keys:

      • bennymeg_mode : [boolean=true] Implements the rot_fields and offset_fields in the same way that the bennymeg/JLC-Plugin-for-KiCad tool. Note that the computation for bottom rotations is wrong, forcing the user to uses arbitrary rotations. The correct computation is (180 - component rot) + angle but the plugin does 180 - (component rot + angle). This option forces the wrong computation for compatibility. This option also controls the way offset signs are interpreted. When enabled the offsets matches this plugin, when disabled matches the interpretation used by the matthewlai/JLCKicadTools plugin. Disabling this option you’ll get better algorithms, but loose compatibility with this plugin.

      • comment : [string=’’] A comment for documentation purposes.

      • extend : [boolean=true] Extends the internal list of rotations with the one provided. Otherwise just use the provided list. Note that the provided list has more precedence than the internal list.

      • invert_bottom : [boolean=false] Rotation for bottom components is negated, resulting in either: (- component rot - angle) or when combined with negative_bottom, (angle - component rot).

      • mirror_bottom : [boolean=false] The original component rotation for components in the bottom is mirrored before applying the adjust so you get (180 - component rot + angle). This is used by JLCPCB.

      • name : [string=’’] Used to identify this particular filter definition.

      • negative_bottom : [boolean=true] Rotation for bottom components is computed via subtraction as (component rot - angle).

      • offset_fields : [string|list(string)=’JLCPCB Position Offset,JLCPosOffset’] List of fields that can contain a position offset. The optional fields can contain a comma separated x,y position offset. This concept is from the bennymeg/JLC-Plugin-for-KiCad tool.

      • offsets : [list(list(string))] A list of pairs regular expression/offset. Footprints matching the regular expression will be moved the specified offset. The offset must be two numbers separated by a comma. The first is the X offset. The signs matches the matthewlai/JLCKicadTools plugin specs.

      • rot_fields : [string|list(string)=’JLCPCB Rotation Offset,JLCRotOffset’] List of fields that can contain a rotation offset. The optional fields can contain a counter-clockwise orientation offset in degrees. This concept is from the bennymeg/JLC-Plugin-for-KiCad tool.

      • rotations : [list(list(string))] A list of pairs regular expression/rotation. Footprints matching the regular expression will be rotated the indicated angle. The angle matches the matthewlai/JLCKicadTools plugin specs.

      • rotations_and_offsets : [list(dict)] A list of rules to match components and specify the rotation and offsets. This is a more flexible version of the rotations and offsets options. Note that this list has more precedence.

        • Valid keys:

          • angle : [number=0.0] Rotation offset to apply to the matched component.

          • apply_angle : [boolean=true] Apply the angle offset.

          • apply_offset : [boolean=true] Apply the position offset.

          • field : [string=’footprint’] Name of field to apply the regular expression. Use _field_lcsc_part to get the value defined in the global options. Use Footprint for the name of the footprint without a library. Use Full Footprint for the name of the footprint including the library.

          • offset_x : [number=0.0] X position offset to apply to the matched component.

          • offset_y : [number=0.0] Y position offset to apply to the matched component.

          • regex : [string=’’] Regular expression to match.

          • regexp : Alias for regex.

      • skip_bottom : [boolean=false] Do not rotate components on the bottom.

      • skip_top : [boolean=false] Do not rotate components on the top.

  • spec_to_field: (Spec to Field) This filter extracts information from the specs obtained from component distributors and fills fields.
    I.e. create a field with the RoHS status of a component.
    In order to make it work you must be able to get prices using the KiCost options of the bom output. Make sure you can do this before trying to use this filter.
    Usage example.

    • Valid keys:

      • from_output : [string=’’] Name of the output used to collect the specs. Currently this must be a bom output with KiCost enabled and a distributor that returns specs.

      • specs : [list(dict)|dict] One or more specs to be copied.

        • Valid keys:

          • field : [string=’’] Name of the destination field.

          • spec : [string|list(string)=’’] Name/s of the source spec/s. The following names are uniform across distributors: ‘_desc’, ‘_value’, ‘_tolerance’, ‘_footprint’, ‘_power’, ‘_current’, ‘_voltage’, ‘_frequency’, ‘_temp_coeff’, ‘_manf’ and ‘_size’.

          • collision : [string=’warning’] [warning,error,ignore] How to report a collision between the current value and the new value.

          • policy : [string=’overwrite’] [overwrite,update,new] Controls the behavior of the copy mechanism. overwrite always copy the spec value, update copy only if the field already exist, new copy only if the field doesn’t exist..

          • type : [string=’string’] [percent,voltage,power,current,value,string] How we compare the current value to determine a collision. value is the component value i.e. resistance for R*.

      • check_dist_coherence : [boolean=true] Check that the data we got from different distributors is equivalent.

      • check_dist_fields : [string|list(string)=’’] List of fields to include in the check. For a full list of fields consult the specs option.

      • comment : [string=’’] A comment for documentation purposes.

      • name : [string=’’] Used to identify this particular filter definition.

  • subparts: (Subparts) This filter implements the KiCost subparts mechanism.

    • Valid keys:

      • check_multiplier : [list(string)] List of fields to include for multiplier computation. If empty all fields in split_fields and manf_pn_field are used.

      • comment : [string=’’] A comment for documentation purposes.

      • manf_field : [string=’manf’] Field for the manufacturer name.

      • manf_pn_field : [string=’manf#’] Field for the manufacturer part number.

      • modify_first_value : [boolean=true] Modify even the value for the first component in the list (KiCost behavior).

      • modify_value : [boolean=true] Add ‘- p N/M’ to the value.

      • mult_separators : [string=’:’] Separators used for the multiplier. Each character in this string is a valid separator.

      • multiplier : [boolean=true] Enables the subpart multiplier mechanism.

      • name : [string=’’] Used to identify this particular filter definition.

      • ref_sep : [string=’#’] Separator used in the reference (i.e. R10#1).

      • separators : [string=’;,’] Separators used between subparts. Each character in this string is a valid separator.

      • split_fields : [list(string)] List of fields to split, usually the distributors part numbers.

      • split_fields_expand : [boolean=false] When true the fields in split_fields are added to the internal names.

      • use_ref_sep_for_first : [boolean=true] Force the reference separator use even for the first component in the list (KiCost behavior).

      • value_alt_field : [string=’value_subparts’] Field containing replacements for the Value field. So we get real values for split parts.

  • urlify: (URLify) Converts URL text in fields to HTML URLs.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • fields : [string|list(string)=’Datasheet’] Fields to convert.

      • name : [string=’’] Used to identify this particular filter definition.

  • value_split: (Value Splitter) This filter extracts information from the value and fills other fields.
    I.e. extracts the tolerance and puts it in the tolerance field.
    Usage example.

    • Valid keys:

      • autoplace : [boolean=true] Try to figure out the position for the added fields.

      • autoplace_mechanism : [string=’bottom’] [bottom,top] Put the new field at the bottom/top of the last field.

      • comment : [string=’’] A comment for documentation purposes.

      • name : [string=’’] Used to identify this particular filter definition.

      • package : [string=’yes’] [yes,no,soft] Policy for the package. yes = overwrite existing value, no = don’t touch, soft = copy if not defined.

      • power : [string=’yes’] [yes,no,soft] Policy for the power rating. yes = overwrite existing value, no = don’t touch, soft = copy if not defined.

      • replace_source : [boolean=true] Replace the content of the source field using a normalized representation of the interpreted value.

      • source : [string=’Value’] Name of the field to use as source of information.

      • temp_coef : [string=’yes’] [yes,no,soft] Policy for the temperature coefficient. yes = overwrite existing value, no = don’t touch, soft = copy if not defined.

      • tolerance : [string=’yes’] [yes,no,soft] Policy for the tolerance. yes = overwrite existing value, no = don’t touch, soft = copy if not defined.

      • visible : [boolean=false] Make visible the modified fields.

      • voltage : [string=’yes’] [yes,no,soft] Policy for the voltage rating. yes = overwrite existing value, no = don’t touch, soft = copy if not defined.

  • var_rename: (Variant Renamer) This filter implements the VARIANT:FIELD=VALUE renamer to get FIELD=VALUE when VARIANT is in use.
    As an example: a field named V1:MPN with value 1N4001 will change the field MPN to be 1N4001 when the variant in use is V1.
    Note that this mechanism can be used to change a footprint, i.e. VARIANT:Footprint assigned with Diode_SMD:D_0805_2012Metric will change the footprint when VARIANT is in use. Of course the footprints should be similar, or your PCB will become invalid.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • force_variant : [string=’’] Use this variant instead of the current variant. Useful for IBoM variants.

      • name : [string=’’] Used to identify this particular filter definition.

      • separator : [string=’:’] Separator used between the variant and the field name.

      • variant_to_value : [boolean=false] Rename fields matching the variant to the value of the component.

  • var_rename_kicost: (Variant Renamer KiCost style) This filter implements the kicost.VARIANT:FIELD=VALUE renamer to get FIELD=VALUE when VARIANT is in use.
    It applies the KiCost concept of variants (a regex to match the VARIANT).
    As an example: a field named kicost.V1:MPN with value 1N4001 will change the field MPN to be 1N4001 when a variant in use matches the V1 string.
    Note that this mechanism can be used to change a footprint, i.e. kicost.VARIANT:Footprint assigned with Diode_SMD:D_0805_2012Metric will change the footprint when VARIANT is matched. Of course the footprints should be similar, or your PCB will become invalid.
    The internal _var_rename_kicost filter is configured to emulate the KiCost behavior. You can create other filters to fine-tune the behavior, i.e. you can make the mechanism to be triggered by fields like kibot.VARIANT|FIELD.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • name : [string=’’] Used to identify this particular filter definition.

      • prefix : [string=’kicost.’] A mandatory prefix. Is not case sensitive.

      • separator : [string=’:’] Separator used between the variant and the field name.

      • variant : [string=’’] Variant regex to match the VARIANT part. When empty the currently selected variant is used.

      • variant_to_value : [boolean=false] Rename fields matching the variant to the value of the component.

Examples for filters

The tests/yaml_samples directory contains all the regression tests. Many of them test the filters functionality.

Built-in filters

  • _datasheet_link converts Datasheet fields containing URLs into HTML links

  • _expand_text_vars is a default expand_text_vars filter

  • _kibom_dnc_Config it uses the internal dnc_list to exclude components with

    • Value matching any of the keys

    • Any of the keys in the Config field (comma or space separated)

  • _kibom_dnf_Config it uses the internal dnf_list to exclude components with

    • Value matching any of the keys

    • Any of the keys in the Config field (comma or space separated)

  • _kicost_dnp used emulate the way KiCost handles the dnp field.

    • If the field is 0 the component is included, otherwise excluded.

  • _kicost_rename is a field_rename filter that applies KiCost renamings.

    • Includes all manf# and manf variations supported by KiCost

    • Includes all distributor part number variations supported by KiCost

    • ‘version’ → ‘variant’

    • ‘nopop’ → ‘dnp’

    • ‘description’ → ‘desc’

    • ‘pdf’ → ‘datasheet’

  • _mechanical is used to exclude:

    • References that start with #

    • Virtual components

    • References that match: ’^TP[0-9]*’ or ‘^FID’

    • Part names that match: ‘regex’: ‘mount.hole’ or ’solder.bridge’ or ‘solder.jump’ or ’test.point’

    • Footprints that match: ‘test.point’ or ’mount.hole’ or ‘fiducial’

  • _none does nothing, useful when you want to remove a filter with default value

  • _only_smd is used to get only SMD parts

  • _only_tht is used to get only THT parts

  • _only_virtual is used to get only virtual parts

  • _rot_footprint is a default rot_footprint filter

  • _rot_footprint_jlcpcb is a rot_footprint filter with option specific for JLCPCB

  • _value_split splits the Value field but the field remains and the extra data is not visible

  • _value_split_replace splits the Value field and replaces it

  • _var_rename is a default var_rename filter

  • _var_rename_kicost is a default var_rename_kicost filter

Note that the kibom… filters uses a field named Config, but you can customise them invoking _kibom_dnf_FIELD. This will create an equivalent filter, but using the indicated FIELD.

Supported variants

  • ibom: (IBoM variant style) .

    The Config field (configurable) contains a value.
    If this value matches with a value in the whitelist is included.
    If this value matches with a value in the blacklist is excluded.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • dnc_filter : [string|list(string)=’’] Name of the filter to mark components as ‘Do Not Change’. Use ‘_kibom_dnc’ for the default KiBoM behavior.

      • dnf_filter : [string|list(string)=’’] Name of the filter to mark components as ‘Do Not Fit’. Use ‘_kibom_dnf’ for the default KiBoM behavior. Use ‘_kicost_dnp’’ for the default KiCost behavior.

      • exclude_filter : [string|list(string)=’’] Name of the filter to exclude components from BoM processing. Use ‘_mechanical’ for the default KiBoM behavior.

      • file_id : [string=’’] Text to use as the replacement for %v expansion.

      • name : [string=’’] Used to identify this particular variant definition.

      • pre_transform : [string|list(string)=’’] Name of the filter to transform fields before applying other filters. Use ‘_var_rename’ to transform VARIANT:FIELD fields. Use ‘_var_rename_kicost’ to transform kicost.VARIANT:FIELD fields. Use ‘_kicost_rename’ to apply KiCost field rename rules.

      • sub_pcbs : [list(dict)] Used for multi-board workflows as defined by KiKit. I don’t recommend using it, for detail read this. But if you really need it you can define the sub-PCBs here. Then you just use VARIANT[SUB_PCB_NAME] instead of just VARIANT.

        • Valid keys:

          • name : [string=’’] Name for this sub-pcb.

          • ref : Alias for reference.

          • reference : [string=’’] Use it for the annotations method. This is the reference for the kikit:Board footprint used to identify the sub-PCB. Note that you can use any footprint as long as its position is inside the PCB outline. When empty the sub-PCB is specified using a rectangle.

          • bottom_right_x : Alias for brx.

          • bottom_right_y : Alias for bry.

          • brx : [number|string] The X position of the bottom right corner for the rectangle that contains the sub-PCB.

          • bry : [number|string] The Y position of the bottom right corner for the rectangle that contains the sub-PCB.

          • center_result : [boolean=true] Move the resulting PCB to the center of the page. You can disable it only for the internal tool, KiKit should always do it.

          • file_id : [string=’’] Text to use as the replacement for %v expansion. When empty we use the parent file_id plus the name of the sub-PCB.

          • strip_annotation : [boolean=false] Remove the annotation footprint. Note that KiKit will remove all annotations, but the internal implementation just the one indicated by ref. If you need to remove other annotations use an exclude filter.

          • tlx : [number|string] The X position of the top left corner for the rectangle that contains the sub-PCB.

          • tly : [number|string] The Y position of the top left corner for the rectangle that contains the sub-PCB.

          • tolerance : [number|string] Used to enlarge the selected rectangle to include elements outside the board. KiCad 5: To avoid rounding issues this value is set to 0.000002 mm when 0 is specified.

          • tool : [string=’internal’] [internal,kikit] Tool used to extract the sub-PCB..

          • top_left_x : Alias for tlx.

          • top_left_y : Alias for tly.

          • units : [string=’mm’] [millimeters,inches,mils,mm,cm,dm,m,mil,inch,in] Units used when omitted.

      • variant_field : [string=’Config’] Name of the field that stores board variant for component.

      • variants_blacklist : [string|list(string)=’’] List of board variants to exclude from the BOM.

      • variants_whitelist : [string|list(string)=’’] List of board variants to include in the BOM.

  • kibom: (KiBoM variant style) .

    The Config field (configurable) contains a comma separated list of variant directives.
    -VARIANT excludes a component from VARIANT.
    +VARIANT includes the component only if we are using this variant.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • config_field : [string=’Config’] Name of the field used to classify components.

      • dnc_filter : [string|list(string)=’_kibom_dnc_CONFIG_FIELD’] Name of the filter to mark components as ‘Do Not Change’. Use ‘_kibom_dnc’ for the default KiBoM behavior.

      • dnf_filter : [string|list(string)=’_kibom_dnf_CONFIG_FIELD’] Name of the filter to mark components as ‘Do Not Fit’. Use ‘_kibom_dnf’ for the default KiBoM behavior. Use ‘_kicost_dnp’_kibom_dnf_CONFIG_FIELD’ for the default KiCost behavior.

      • exclude_filter : [string|list(string)=’_mechanical’] Name of the filter to exclude components from BoM processing. Use ‘_mechanical’ for the default KiBoM behavior.

      • file_id : [string=’’] Text to use as the replacement for %v expansion.

      • name : [string=’’] Used to identify this particular variant definition.

      • pre_transform : [string|list(string)=’’] Name of the filter to transform fields before applying other filters. Use ‘_var_rename’ to transform VARIANT:FIELD fields. Use ‘_var_rename_kicost’ to transform kicost.VARIANT:FIELD fields. Use ‘_kicost_rename’ to apply KiCost field rename rules.

      • sub_pcbs : [list(dict)] Used for multi-board workflows as defined by KiKit. I don’t recommend using it, for detail read this. But if you really need it you can define the sub-PCBs here. Then you just use VARIANT[SUB_PCB_NAME] instead of just VARIANT.

        • Valid keys:

          • name : [string=’’] Name for this sub-pcb.

          • ref : Alias for reference.

          • reference : [string=’’] Use it for the annotations method. This is the reference for the kikit:Board footprint used to identify the sub-PCB. Note that you can use any footprint as long as its position is inside the PCB outline. When empty the sub-PCB is specified using a rectangle.

          • bottom_right_x : Alias for brx.

          • bottom_right_y : Alias for bry.

          • brx : [number|string] The X position of the bottom right corner for the rectangle that contains the sub-PCB.

          • bry : [number|string] The Y position of the bottom right corner for the rectangle that contains the sub-PCB.

          • center_result : [boolean=true] Move the resulting PCB to the center of the page. You can disable it only for the internal tool, KiKit should always do it.

          • file_id : [string=’’] Text to use as the replacement for %v expansion. When empty we use the parent file_id plus the name of the sub-PCB.

          • strip_annotation : [boolean=false] Remove the annotation footprint. Note that KiKit will remove all annotations, but the internal implementation just the one indicated by ref. If you need to remove other annotations use an exclude filter.

          • tlx : [number|string] The X position of the top left corner for the rectangle that contains the sub-PCB.

          • tly : [number|string] The Y position of the top left corner for the rectangle that contains the sub-PCB.

          • tolerance : [number|string] Used to enlarge the selected rectangle to include elements outside the board. KiCad 5: To avoid rounding issues this value is set to 0.000002 mm when 0 is specified.

          • tool : [string=’internal’] [internal,kikit] Tool used to extract the sub-PCB..

          • top_left_x : Alias for tlx.

          • top_left_y : Alias for tly.

          • units : [string=’mm’] [millimeters,inches,mils,mm,cm,dm,m,mil,inch,in] Units used when omitted.

      • variant : [string|list(string)=’’] Board variant(s).

  • kicost: (KiCost variant style) .

    The variant field (configurable) contains one or more values.
    If any of these values matches the variant regex the component is included.
    By default a pre-transform filter is applied to support kicost.VARIANT:FIELD and field name aliases used by KiCost.
    Also a default dnf_filter implements the KiCost DNP mechanism.

    • Valid keys:

      • comment : [string=’’] A comment for documentation purposes.

      • dnc_filter : [string|list(string)=’’] Name of the filter to mark components as ‘Do Not Change’. Use ‘_kibom_dnc’ for the default KiBoM behavior.

      • dnf_filter : [string|list(string)=’’] Name of the filter to mark components as ‘Do Not Fit’. Use ‘_kibom_dnf’ for the default KiBoM behavior. Use ‘_kicost_dnp’’ for the default KiCost behavior.

      • exclude_filter : [string|list(string)=’’] Name of the filter to exclude components from BoM processing. Use ‘_mechanical’ for the default KiBoM behavior.

      • file_id : [string=’’] Text to use as the replacement for %v expansion.

      • name : [string=’’] Used to identify this particular variant definition.

      • pre_transform : [string|list(string)=’’] Name of the filter to transform fields before applying other filters. Use ‘_var_rename’ to transform VARIANT:FIELD fields. Use ‘_var_rename_kicost’ to transform kicost.VARIANT:FIELD fields. Use ‘_kicost_rename’ to apply KiCost field rename rules.

      • separators : [string=’,;/ ‘] Valid separators for variants in the variant field. Each character is a valid separator. Only supported internally, don’t use it if you plan to use KiCost.

      • sub_pcbs : [list(dict)] Used for multi-board workflows as defined by KiKit. I don’t recommend using it, for detail read this. But if you really need it you can define the sub-PCBs here. Then you just use VARIANT[SUB_PCB_NAME] instead of just VARIANT.

        • Valid keys:

          • name : [string=’’] Name for this sub-pcb.

          • ref : Alias for reference.

          • reference : [string=’’] Use it for the annotations method. This is the reference for the kikit:Board footprint used to identify the sub-PCB. Note that you can use any footprint as long as its position is inside the PCB outline. When empty the sub-PCB is specified using a rectangle.

          • bottom_right_x : Alias for brx.

          • bottom_right_y : Alias for bry.

          • brx : [number|string] The X position of the bottom right corner for the rectangle that contains the sub-PCB.

          • bry : [number|string] The Y position of the bottom right corner for the rectangle that contains the sub-PCB.

          • center_result : [boolean=true] Move the resulting PCB to the center of the page. You can disable it only for the internal tool, KiKit should always do it.

          • file_id : [string=’’] Text to use as the replacement for %v expansion. When empty we use the parent file_id plus the name of the sub-PCB.

          • strip_annotation : [boolean=false] Remove the annotation footprint. Note that KiKit will remove all annotations, but the internal implementation just the one indicated by ref. If you need to remove other annotations use an exclude filter.

          • tlx : [number|string] The X position of the top left corner for the rectangle that contains the sub-PCB.

          • tly : [number|string] The Y position of the top left corner for the rectangle that contains the sub-PCB.

          • tolerance : [number|string] Used to enlarge the selected rectangle to include elements outside the board. KiCad 5: To avoid rounding issues this value is set to 0.000002 mm when 0 is specified.

          • tool : [string=’internal’] [internal,kikit] Tool used to extract the sub-PCB..

          • top_left_x : Alias for tlx.

          • top_left_y : Alias for tly.

          • units : [string=’mm’] [millimeters,inches,mils,mm,cm,dm,m,mil,inch,in] Units used when omitted.

      • variant : [string=’’] Variants to match (regex).

      • variant_field : [string=’variant’] Name of the field that stores board variant/s for component. Only supported internally, don’t use it if you plan to use KiCost.

Changing the 3D model, simple mechanism

This mechanism allows small changes to the 3D model. Is simple to use, but the information is located in the schematic.

If a component defines the field _3D_model then its value will replace the 3D model. You can use var_rename or var_rename_kicost filter to define this field only for certain variants. In this way you can change the 3D model according to the component variant.

When the component has more than one 3D model you must provide a comma separated list of models to replace the current models.

Changing the 3D model, complex mechanism

When the a component has a long list of 3D models and you want to keep all the information in the PCB you can use this mechanism.

The information is stored in the Text items of the footprint. If you want to change the 3D models for certain variant you must add an item containing:

%VARIANT_NAME:SLOT1,SLOT2,SLOTN%

Where VARIANT_NAME is the name of the variant that will change the list of 3D models. The SLOT1,SLOT2,SLOTN is a comma separated list of 3D model positions in the list of 3D models. All the slots listed will be enabled, the rest will be disabled.

Here is an example. In this example we have a display whose aspect and connectio can radically change according to the variant. We have two variants:

  • left, uses a ERM1602DNS-2.1 with a connector on the left and two other pins on the right

  • top, uses a WH1602B-TMI-JT# with a single connector on the top

We have the following list of 3D models:

${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_2x07_P2.54mm_Vertical.wrl
${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x16_P2.54mm_Vertical.wrl
${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x01_P2.54mm_Vertical.wrl
${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x01_P2.54mm_Vertical.wrl
${KIPRJMOD}/steps/WH1602B-TMI-JT#.step
${KIPRJMOD}/steps/ERM1602DNS-2.1.step

The ERM1602DNS-2.1 uses slots 1, 3, 4 and 6. So the effective list will be:

${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_2x07_P2.54mm_Vertical.wrl
${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x01_P2.54mm_Vertical.wrl
${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x01_P2.54mm_Vertical.wrl
${KIPRJMOD}/steps/ERM1602DNS-2.1.step

The WH1602B-TMI-JT# uses slots 2 and 5. So the effective list will be:

${KISYS3DMOD}/Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x16_P2.54mm_Vertical.wrl
${KIPRJMOD}/steps/WH1602B-TMI-JT#.step

To achieve it we define the following texts in the footprint: %left:1,3,4,6% and %top:2,5%. Here are both variants:

Left variant

Left variant

Top variant

Top variant

If you preffer to use the variant specific matching mechanism you can use the following syntax:

$TEXT_TO_MATCH:SLOT1,SLOT2,SLOTN$

In this case the variant will be applied to the TEXT_TO_MATCH, if it matches (equivalent to a component fitted) the SLOT will be used.

Some important notes:

  • If you want to control what models are used when no variant is used you’ll need to create a default variant. This is what the above example does. In this case the default variant shows all the connectors, but no display. Note that changing the 3D model needs the variants infrastructure.

  • If you are using variants and a lot of them select the same slots you can add a special text: %_default_:SLOTS%. This will be used if none %VARIANT_NAME:SLOT% matched.

  • If you want to disable a model and avoid any kind of warning add _Disabled_by_KiBot to the 3D model path. This could be needed if you want to remove some model and you don’t want to adjust the slot numbers.

  • This mechanism can be used with any of the available variants. For this reason we use the VARIANT_NAME and we avoid relying on any variant specific mechanism. But you can use the alternative syntax if you preffer the variant specific matching system.

DNF and DNC internal keys

The current list of DNF keys is:

  • dnf

  • dnl

  • dnp

  • do not fit

  • do not place

  • do not load

  • nofit

  • nostuff

  • noplace

  • noload

  • not fitted

  • not loaded

  • not placed

  • no stuff

The current list of DNC keys is:

  • dnc

  • do not change

  • no change

  • fixed

You can define your own lists as the int_bom_fil_1.kibot.yaml shows.