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.
draw_stackup: : [boolean=False|dict] Draw the PCB stackup. Needs KiCad 7 or newer. To specify the position and size of the drawing you can use two methods.
You can specify it using the pos_x, pos_y, width, height and layer options.
But you can also draw a rectangle in your PCB with the size and layer you want.
Then draw another thing inside the rectangle, select both and create a group (right mouse button, then Grouping -> Group). Now edit the group and change its name to kibot_stackup. After running this preflight the rectangle will contain the stackup.drc: : [boolean=false|dict] Runs the DRC (Distance Rules Check). To ensure we have a valid PCB. You need a valid fp-lib-table installed. If not KiBot will try to temporarily install the template.
This is a replacement for the run_drc preflight that needs KiCad 8 or newer.
GUI exclusions and schematic parity are supported.Valid keys:
output : [string=’%f-%i%I%v.%x’] Name for the generated archive (%i=drc %x=according to format). Affected by global options.
all_track_errors: [boolean=false] Report all the errors for all the tracks, not just the first.dir: [string=’’] Sub-directory for the report.dont_stop: [boolean=false] Continue even if we detect errors.enabled: [boolean=true] Enable the check. This is the replacement for the boolean value.filters: [list(dict)] Used to manipulate the violations. Avoid using the filters preflight.Valid keys:
change_to: [string=’ignore’] [error,warning,ignore] The action of the filter. Changing to ignore is the default and is used to suppress a violation, but you can also change it to be an error or a warning. Note that violations excluded by KiCad are also analyzed, so you can revert a GUI exclusion.error: [string=’’] Error id we want to exclude.filter: [string=’’] Name for the filter, for documentation purposes.filter_msg : Alias for filter.
regex: [string=’’] Regular expression to match the text for the error we want to exclude.regexp : Alias for regex.
format: [string|list(string)=’HTML’][RPT,HTML,CSV,JSON] Format/s used for the report. You can specify multiple formats.ignore_unconnected: [boolean=false] Ignores the unconnected nets. Useful if you didn’t finish the routing.schematic_parity: [boolean=true] Check if the PCB and the schematic are coincident.units: [string=’millimeters’] [millimeters,inches,mils] Units used for the positions. Affected by global options.warnings_as_errors: [boolean=false] Warnings are considered errors, they still reported as errors, but consider it an error.
erc: : [boolean=false|dict] Runs the ERC (Electrical Rules Check). To ensure the schematic is electrically correct. You need a valid sym-lib-table installed. If not KiBot will try to temporarily install the template.
This is a replacement for the run_erc preflight that needs KiCad 8 or newer.Valid keys:
output : [string=’%f-%i%I%v.%x’] Name for the generated archive (%i=erc %x=according to format). Affected by global options.
dir: [string=’’] Sub-directory for the report.dont_stop: [boolean=false] Continue even if we detect errors.enabled: [boolean=true] Enable the check. This is the replacement for the boolean value.filters: [list(dict)] Used to manipulate the violations. Avoid using the filters preflight.Valid keys:
change_to: [string=’ignore’] [error,warning,ignore] The action of the filter. Changing to ignore is the default and is used to suppress a violation, but you can also change it to be an error or a warning. Note that violations excluded by KiCad are also analyzed, so you can revert a GUI exclusion.error: [string=’’] Error id we want to exclude.filter: [string=’’] Name for the filter, for documentation purposes.filter_msg : Alias for filter.
regex: [string=’’] Regular expression to match the text for the error we want to exclude.regexp : Alias for regex.
format: [string|list(string)=’HTML’][RPT,HTML,CSV,JSON] Format/s used for the report. You can specify multiple formats.units: [string=’millimeters’] [millimeters,inches,mils] Units used for the positions. Affected by global options.warnings_as_errors: [boolean=false] Warnings are considered errors, they still reported as errors, but consider it an error.
erc_warnings: : [boolean=false] Deprecated, use the warnings_as_errors option from run_erc/erc. 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 when using run_erc/run_drc. Avoid using it with the new erc and drc preflights.
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] Deprecated, use the ignore_unconnected option from run_drc/drc. Option for run_drc. Ignores the unconnected nets. Useful if you didn’t finish the routing.
It will also ignore KiCad 6 warnings when using run_drc.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|dict] 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.
If you use DRC exclusions please consult the drc_exclusions_workaround global option.Valid keys:
dir: [string=’’] Sub-directory for the report.enabled: [boolean=true] Enable the DRC. This is the replacement for the boolean value.ignore_unconnected: [boolean=false] Ignores the unconnected nets. Useful if you didn’t finish the routing. It will also ignore KiCad 6 warnings.
run_erc: : [boolean=false|dict] (Deprecated for KiCad 8, use erc) 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).Valid keys:
dir: [string=’’] Sub-directory for the report.enabled: [boolean=true] Enable the ERC. This is the replacement for the boolean value.warnings_as_errors: [boolean=false] ERC warnings are considered errors.
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.
Warning
don’t use -s all or this preflight will be skipped
update_footprint: : [string|list(string)=’’] Updates footprints from the libs, you must provide one or more references to be updated. This is useful to replace logos using freshly created versions.
update_pcb_characteristics: : [boolean=False] Update the information in the Board Characteristics. Starting with KiCad 7 you can paste a block containing board information using Place -> Add Board Characteristics. But this information is static, so if you modify anything related to it the block will be obsolete.
This preflight tries to refresh the information.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_stackup: : [boolean=False] Update the information in the Stackup Table. Starting with KiCad 7 you can paste a block containing board information using Place -> Stackup Table. But this information is static, so if you modify anything related to it the block will be obsolete.
This preflight tries to refresh the information.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. Not available for KiCad 5. Important: when using KiCad 6 and the Exclude from BoM attribute these components won’t be included in the generated XML, so we can’t check its parity.
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.