The preflight section

This section is used to specify tasks that will be executed before generating any output.

Supported preflights

  • annotate_pcb: : [dict] Annotates the PCB according to physical coordinates. This preflight modifies the PCB and schematic, use it only in revision control environments.
    Used to assign references according to footprint coordinates.
    The project must be fully annotated first.

    • Valid keys:

      • bottom_main_ascending : [boolean=true] Sort the main axis in ascending order for the bottom layer. For X this is left to right and for Y top to bottom.

      • bottom_main_axis : [string=’y’] [x,y] Use this axis as main sorting criteria for the bottom layer.

      • bottom_secondary_ascending : [boolean=true] Sort the secondary axis in ascending order for the bottom layer. For X this is left to right and for Y top to bottom.

      • bottom_start : [number=101] First number for references at the bottom layer. Use -1 to continue from the last top reference.

      • grid : [number=1.0] Grid size in millimeters.

      • top_main_ascending : [boolean=true] Sort the main axis in ascending order for the top layer. For X this is left to right and for Y top to bottom.

      • top_main_axis : [string=’y’] [x,y] Use this axis as main sorting criteria for the top layer.

      • top_secondary_ascending : [boolean=true] Sort the secondary axis in ascending order for the top layer. For X this is left to right and for Y top to bottom.

      • top_start : [number=1] First number for references at the top layer.

      • use_position_of : [string=’footprint’] [footprint,reference] Which coordinate is used.

  • annotate_power: : [boolean=false] Annotates all power components. This preflight modifies the schematic, use it only in revision control environments.
    Used to solve ERC problems when using filters that remove power reference numbers.

  • check_zone_fills: : [boolean=false] Zones are filled before doing any operation involving PCB layers. The original PCB remains unchanged. If you need to abort when the zone fill creates significant changes to a layer use the CheckZoneFill internal template.

  • erc_warnings: : [boolean=false] Option for run_erc. ERC warnings are considered errors.

  • fill_zones: : [boolean=false] Fill all zones again and save the PCB.

  • filters: : [list(dict)] A list of entries to filter out ERC/DRC messages. Note that ignored errors will become KiBot warnings (i.e. (W058) …).
    To farther ignore these warnings use the filters option in the global section.

    • Valid keys:

      • error : [string=’’] Error id we want to exclude. A name for KiCad 6 or a number for KiCad 5, but always a string.

      • error_number : Alias for number.

      • filter : [string=’’] Name for the filter, for documentation purposes.

      • filter_msg : Alias for filter.

      • number : [number=0] Error number we want to exclude. KiCad 5 only.

      • regex : [string=’’] Regular expression to match the text for the error we want to exclude.

      • regexp : Alias for regex.

  • ignore_unconnected: : [boolean=false] Option for run_drc. Ignores the unconnected nets. Useful if you didn’t finish the routing. It will also ignore KiCad 6 warnings.

  • pcb_replace: : [dict] Replaces tags in the PCB. I.e. to insert the git hash or last revision date. This is useful for KiCad 5, use set_text_variables when using KiCad 6.
    This preflight modifies the PCB. Even when a back-up is done use it carefully.

    • Valid keys:

      • date_command : [string=’’] Command to get the date to use in the PCB.\ `git log -1 --format='%as' -- "$KIBOT_PCB_NAME"`\ Will return the date in YYYY-MM-DD format.\ `date -d @`git log -1 --format='%at' -- "$KIBOT_PCB_NAME"` +%Y-%m-%d_%H-%M-%S`\ Will return the date in YYYY-MM-DD_HH-MM-SS format.\ Important: on KiCad 6 the title block data is optional. This command will work only if you have a date in the PCB/Schematic.

      • replace_tags : [dict|list(dict)] Tag or tags to replace.

        • Valid keys:

          • after : [string=’’] Text to add after the output of command.

          • before : [string=’’] Text to add before the output of command.

          • command : [string=’’] Command to execute to get the text, will be used only if text is empty. KIBOT_PCB_NAME variable is the name of the current PCB.

          • tag : [string=’’] Name of the tag to replace. Use version for a tag named @version@.

          • tag_delimiter : [string=’@’] Character used to indicate the beginning and the end of a tag. Don’t change it unless you really know about KiCad’s file formats.

          • text : [string=’’] Text to insert instead of the tag.

  • run_drc: : [boolean=false] Runs the DRC (Distance Rules Check). To ensure we have a valid PCB. The report file name is controlled by the global output pattern (%i=drc %x=txt).
    Note that the KiCad 6+ Test for parity between PCB and schematic option is not supported.
    If you need to check the parity use the update_xml preflight.
    KiCad 6 introduced warnings they are currently counted be the unconnected counter of KiBot.
    This will change in the future.

  • run_erc: : [boolean=false] Runs the ERC (Electrical Rules Check). To ensure the schematic is electrically correct. The report file name is controlled by the global output pattern (%i=erc %x=txt).

  • sch_replace: : [dict] Replaces tags in the schematic. I.e. to insert the git hash or last revision date. This is useful for KiCad 5, use set_text_variables when using KiCad 6.
    This preflight modifies the schematics. Even when a back-up is done use it carefully.

    • Valid keys:

      • date_command : [string=’’] Command to get the date to use in the SCH.\ `git log -1 --format='%as' -- "$KIBOT_SCH_NAME"`\ Will return the date in YYYY-MM-DD format.\ `date -d @`git log -1 --format='%at' -- "$KIBOT_SCH_NAME"` +%Y-%m-%d_%H-%M-%S`\ Will return the date in YYYY-MM-DD_HH-MM-SS format.\ Important: on KiCad 6 the title block data is optional. This command will work only if you have a date in the SCH/Schematic.

      • replace_tags : [dict|list(dict)] Tag or tags to replace.

        • Valid keys:

          • after : [string=’’] Text to add after the output of command.

          • before : [string=’’] Text to add before the output of command.

          • command : [string=’’] Command to execute to get the text, will be used only if text is empty. KIBOT_SCH_NAME variable is the name of the current sheet. KIBOT_TOP_SCH_NAME variable is the name of the top sheet.

          • tag : [string=’’] Name of the tag to replace. Use version for a tag named @version@.

          • tag_delimiter : [string=’@’] Character used to indicate the beginning and the end of a tag. Don’t change it unless you really know about KiCad’s file formats.

          • text : [string=’’] Text to insert instead of the tag.

  • set_text_variables: : [dict|list(dict)] Defines KiCad 6 variables. They are expanded using ${VARIABLE}, and stored in the project file.
    This preflight replaces pcb_replace and sch_replace when using KiCad 6.
    The KiCad project file is modified.

    • Valid keys:

      • after : [string=’’] Text to add after the output of command.

      • before : [string=’’] Text to add before the output of command.

      • command : [string=’’] Command to execute to get the text, will be used only if text is empty. This command will be executed using the Bash shell. Be careful about spaces in file names (i.e. use “$KIBOT_PCB_NAME”). The KIBOT_PCB_NAME environment variable is the PCB file and the KIBOT_SCH_NAME environment variable is the schematic file.

      • expand_kibot_patterns : [boolean=true] Expand %X patterns. The context is schematic.

      • name : [string=’’] Name of the variable. The version variable will be expanded using ${version}.

      • text : [string=’’] Text to insert instead of the variable.

      • variable : Alias for name.

  • update_qr: : [boolean=false] Update the QR codes. Complements the qr_lib output.
    The KiCad 6 files and the KiCad 5 PCB needs manual update, generating a new library isn’t enough.

  • update_xml: : [boolean=false|dict] Update the XML version of the BoM (Bill of Materials). To ensure our generated BoM is up to date.
    Note that this isn’t needed when using the internal BoM generator (bom).
    You can compare the PCB and schematic netlists using it.

    • Valid keys:

      • check_pcb_parity : [boolean=false] Check if the PCB and Schematic are synchronized. This is equivalent to the Test for parity between PCB and schematic of the DRC dialog. Only available for KiCad 6+.

      • as_warnings : [boolean=false] Inform the problems as warnings and don’t stop.

      • enabled : [boolean=true] Enable the update. This is the replacement for the boolean value.

Here is an example of a preflight section:

preflight:
  run_erc: true
  update_xml: true
  run_drc: true
  check_zone_fills: true
  ignore_unconnected: false

More about pcb_replace and sch_replace

These options are supposed to be used in a version control environment. This is because, unlike other options, they modify the PCB and/or schematic and might damage them. In a version control environment you can just roll-back the changes.

Don’t be afraid, they make a back-up of the files and also tries to disable dangerous changes. But should be used carefully. They are ideal for CI/CD environment where you don’t actually commit any changes.

Filtering DRC and ERC errors

Sometimes KiCad reports DRC or ERC errors that you can’t get rid off. This could be just because you are part of a team including lazy people that doesn’t want to take the extra effort to solve some errors that aren’t in fact errors, just small violations made on purpose. In this case you could exclude some known errors.

For this you must declare filters entry in the preflight section. Then you can add as many filter entries as you want. Each filter entry has an optional description and defines to which error type is applied (number) and a regular expression that the error must match to be ignored (regex). Like this:

filters:
  - filter: 'Optional filter description'
    error: 'Error_type'
    regex:  'Expression to match'

Here is a KiCad 5 example, suppose you are getting the following errors:

** Found 1 DRC errors **
ErrType(4): Track too close to pad
    @(177.185 mm, 78.315 mm): Track 1.000 mm [Net-(C3-Pad1)] on F.Cu, length: 1.591 mm
    @(177.185 mm, 80.715 mm): Pad 2 of C3 on F.Cu and others

** Found 1 unconnected pads **
ErrType(2): Unconnected items
    @(177.185 mm, 73.965 mm): Pad 2 of C4 on F.Cu and others
    @(177.185 mm, 80.715 mm): Pad 2 of C3 on F.Cu and others

And you want to ignore them. You can add the following filters:

filters:
  - filter: 'Ignore C3 pad 2 too close to anything'
    error: '4'
    regex:  'Pad 2 of C3'
  - filter: 'Ignore unconnected pad 2 of C4'
    error: '2'
    regex:  'Pad 2 of C4'

If you need to match text from two different lines in the error message try using (?s)TEXT(.*)TEXT_IN_OTHER_LINE.

If you have two or more different options for a text to match try using (OPTION1|OPTION2).

A complete Python regular expressions explanation is out of the scope of this manual. For a complete reference consult the Python manual.

KiCad 6 uses strings to differentiate errors, use them for the error field. To keep compatibility you can use the number or error_number options for KiCad 5.

Note that this will ignore the errors, but they will be reported as warnings. If you want to suppress these warnings take a look at Filtering KiBot warnings

Important note: this will create a file named kibot_errors.filter in the output directory.