Default global options

The section global contains default global options that affects all the outputs. Currently only a few option are supported.

Default output option

This option controls the default file name pattern used by all the outputs. This makes all the file names coherent. You can always choose the file name for a particular output.

The pattern uses the following expansions:

%c company from pcb/sch metadata.
%C``n`` comments line n from pcb/sch metadata.
%d pcb/sch date from metadata if available, file modification date otherwise.
%D date the script was started.
%f original pcb/sch file name without extension.
%F original pcb/sch file name without extension. Including the directory part of the name.
%g the file_id of the global variant.
%G the name of the global variant.
%i a contextual ID, depends on the output type.
%I an ID defined by the user for this output.
%M directory where the pcb/sch resides. Only the last component i.e. /a/b/c/name.kicad_pcb -> c
%p title from pcb/sch metadata.
%r revision from pcb/sch metadata.
%S sub-PCB name (related to multiboards).
%T time the script was started.
%x a suitable extension for the output type.
%v the file_id of the current variant, or the global variant if outside a variant scope.
%V the name of the current variant, or the global variant if outside a variant scope.

They are compatible with the ones used by IBoM. The default value for global.output is %f-%i%I%v.%x. If you want to include the revision you could add the following definition:

global:
  output: '%f_rev_%r-%i.%x'

Note that the following patterns: %c, %C``n``, %d, %f, %F, %p and %r depends on the context. If you use them for an output related to the PCB these values will be obtained from the PCB. If you need to force the origin of the data you can use %bX for the PCB and %sX for the schematic, where X is the pattern to expand.

You can also use text variables (introduced in KiCad 6). To expand a text variable use ${VARIABLE}. In addition you can also use environment variables, defined in your OS shell or defined in the global section.

Default dir option

The default dir value for any output is .. You can change it here.

Expansion patterns are allowed.

Note that you can use this value as a base for output’s dir options. In this case the value defined in the output must start with +. In this case the + is replaced by the default dir value defined here.

Default variant option

This option controls the default variant applied to all the outputs. Example:

global:
  variant: 'production'

Default units option

This option controls the default value for the position and bom outputs. If you don’t define it then the internal defaults of each output are applied. But when you define it the default is the defined value.

On KiCad 6 the dimensions has units. When you create a new dimension it uses automatic units. This means that KiCad uses the units currently selected. This selection isn’t stored in the PCB file. The global units value is used by KiBot instead.

Output directory option

The out_dir option can define the base output directory. This is the same as the -d/--out-dir command line option. Note that the command line option has precedence over it.

Expansion patterns are applied to this value, but you should avoid using patterns that expand according to the context, i.e. %c, %d, %f, %F, %p and %r. The behavior of these patterns isn’t fully defined in this case and the results may change in the future.

You can also use text variables (introduced in KiCad 6). To expand a text variable use ${VARIABLE}. In addition you can also use environment variables, defined in your OS shell or defined in the global section.

Date format option

The %d, %sd and %bd patterns use the date and time from the PCB and schematic. When abscent they use the file timestamp, and the date_time_format global option controls the format used. When available, and in ISO format, the date_format controls the format used. You can disable this reformatting assigning false to the date_reformat option.
The %D format is controlled by the date_format global option.
The %T format is controlled by the time_format global option.

In all cases the format is the one used by the strftime POSIX function, for more information visit this site.

PCB details options

The following variables control the default colors and they are used for documentation purposes:

pcb_material [FR4] PCB core material. Currently known are FR1 to FR5
solder_mask_color [green] Color for the solder mask. Currently known are green, black, white, yellow, purple, blue and red.
silk_screen_color [white] Color for the markings. Currently known are black and white.
pcb_finish [HAL] Finishing used to protect pads. Currently known are None, HAL, HASL, ENIG and ImAg.

Filtering KiBot warnings

KiBot warnings are marked with (Wn) where n is the warning id.

Some warnings are just recommendations and you could want to avoid them to focus on details that are more relevant to your project. In this case you can define filters in a similar way used to filter DRC/ERC errors.

As an example, if you have the following warning:

WARNING:(W43) Missing component `l1:FooBar`

You can create the following filter to remove it:

global:
  filters:
    - number: 43
      regex:  'FooBar'

All available global options

global
- Valid keys:
  - aliases_for_3d_models : [list(dict)] List of aliases for the 3D models (KiCad 6). KiCad stores 3D aliases with the user settings, not locally. This makes impossible to create self contained projects. You can define aliases here to workaround this problem. The values defined here has precedence over the KiCad configuration. Related to https://gitlab.com/kicad/code/kicad/-/issues/3792.
    - Valid keys:
      - alias : Alias for name.
      - name : [string=’’] Name of the alias.
      - text : Alias for value.
      - value : [string=’’] Path to the 3D model.
      - variable : Alias for name.
  - allow_blind_buried_vias : [boolean=true] Allow the use of buried vias. This value is only used for KiCad 7+. For KiCad 5 and 6 use the design rules settings, stored in the project.
  - allow_component_ranges : [boolean=true] Allow using ranges like R5-R20 in the show_components and highlight options. If you have references that looks like a range you should disable this option.
  - allow_microvias : [boolean=true] Allow the use of micro vias. This value is only used for KiCad 7+. For KiCad 5 and 6 use the design rules settings, stored in the project.
  - always_warn_about_paste_pads : [boolean=false] Used to detect the use of pads just for paste.
  - cache_3d_resistors : [boolean=false] Use a cache for the generated 3D models of colored resistors. Will save time, but you could need to remove the cache if you need to regenerate them.
  - castellated_pads : [boolean=false] Has the PCB castellated pads? KiCad 6: you should set this in the Board Setup -> Board Finish -> Has castellated pads.
  - colored_tht_resistors : [boolean=true] Try to add color bands to the 3D models of KiCad THT resistors.
  - copper_finish : Alias for pcb_finish.
  - copper_thickness : [number|string] Copper thickness in micrometers (1 Oz is 35 micrometers). KiCad 6: you should set this in the Board Setup -> Physical Stackup.
  - cross_footprints_for_dnp : [boolean=true] Draw a cross for excluded components in the Fab layer.
  - cross_no_body : [boolean=false] Cross components even when they don’t have a body. Only for KiCad 6 and internal cross.
  - cross_using_kicad : [boolean=true] When using KiCad 7+ let KiCad cross the components.
  - csv_accept_no_ref : [boolean=false] Accept aggregating CSV files without references (Experimental).
  - date_format : [string=’%Y-%m-%d’] Format used for the day we started the script. Is also used for the PCB/SCH date formatting when time_reformat is enabled (default behavior). Uses the strftime format.
  - date_time_format : [string=’%Y-%m-%d_%H-%M-%S’] Format used for the PCB and schematic date when using the file timestamp. Uses the strftime format.
  - default_resistor_tolerance : [number=20] When no tolerance is specified we use this value. Note that I know 5% is a common default, but technically speaking 20% is the default. Used while creating colored resistors.
  - dir : [string=’’] Default pattern for the output directories. It also applies to the preflights, unless use_dir_for_preflights is disabled.
  - disable_3d_alias_as_env : [boolean=false] Disable the use of environment and text variables as 3D models aliases.
  - drc_exclusions_workaround : [boolean=false] KiCad 6 introduced DRC exclusions. They are stored in the project but ignored by the Python API. This is reported as bug number 11562 (https://gitlab.com/kicad/code/kicad/-/issues/11562). If you really need exclusions enable this option, this will use the GUI version of the DRC (slower). Current KiCad version is 6.0.7 and the bug is still there.
  - drill_size_increment : [number=0.05] This is the difference between drill tools in millimeters. A manufacturer with 0.05 of increment has drills for 0.1, 0.15, 0.2, 0.25, etc..
  - edge_connector : [string=’no’] [yes,no,bevelled] Has the PCB edge connectors? KiCad 6: you should set this in the Board Setup -> Board Finish -> Edge card connectors.
  - edge_plating : [boolean=false] Has the PCB a plated board edge? KiCad 6: you should set this in the Board Setup -> Board Finish -> Plated board edge.
  - environment : [dict] Used to define environment variables used by KiCad. The values defined here are exported as environment variables and has more precedence than KiCad paths defined in the GUI. You can make reference to any OS environment variable using ${VARIABLE}. The KIPRJMOD is also available for expansion.
    - Valid keys:
      - define_old : [boolean=false] Also define legacy versions of the variables. Useful when using KiCad 6+ and some libs uses old KiCad 5 names.
      - extra_os : [list(dict)] Extra variables to export as OS environment variables. Note that you can also define them using - NAME: VALUE.
        
        Valid keys:
        
        name : [string=’’] Name of the variable.
        
        value : [string=’’] Value for the variable.
      - footprints : [string=’’] System level footprints (aka modules) dir. KiCad 5: KICAD_FOOTPRINT_DIR and KISYSMOD. KiCad 6: KICAD6_FOOTPRINT_DIR.
      - models_3d : [string=’’] System level 3D models dir. KiCad 5: KISYS3DMOD. KiCad 6: KICAD6_3DMODEL_DIR.
      - symbols : [string=’’] System level symbols dir. KiCad 5: KICAD_SYMBOL_DIR. KiCad 6: KICAD6_SYMBOL_DIR.
      - templates : [string=’’] System level templates dir. KiCad 5: KICAD_TEMPLATE_DIR. KiCad 6: KICAD6_TEMPLATE_DIR.
      - third_party : [string=’’] 3rd party dir. KiCad 6: KICAD6_3RD_PARTY.
      - user_templates : [string=’’] User level templates dir. KiCad 5/6: KICAD_USER_TEMPLATE_DIR.
  - erc_grid : [number=50] Grid size used for the ERC. This value must be in mils. This is needed for KiCad 7 in order to run the off grid check. This value is stored in the project for KiCad 8, no need to specify it.
  - extra_pth_drill : [number=0.1] How many millimeters the manufacturer will add to plated holes. This is because the plating reduces the hole, so you need to use a bigger drill. For more information consult: https://www.eurocircuits.com/pcb-design-guidelines/drilled-holes/.
  - field_3D_model : [string=’_3D_model’] Name for the field controlling the 3D models used for a component.
  - field_lcsc_part : [string=’’] The name of the schematic field that contains the part number for the LCSC/JLCPCB distributor. When empty KiBot will try to discover it.
  - field_package : [string|list(string)] Name/s of the field/s used for the package, not footprint. I.e. 0805, SOT-23, etc. Used for the value split filter. The default is [‘package’, ‘pkg’].
  - field_power : [string|list(string)] Name/s of the field/s used for the power raiting. Used for the value split filter. The default is [‘power’, ‘pow’].
  - field_temp_coef : [string|list(string)] Name/s of the field/s used for the temperature coefficient. I.e. X7R, NP0, etc. Used for the value split filter. The default is [‘temp_coef’, ‘tmp_coef’].
  - field_tolerance : [string|list(string)] Name/s of the field/s used for the tolerance. Used while creating colored resistors and for the value split filter. The default is [‘tolerance’, ‘tol’].
  - field_voltage : [string|list(string)] Name/s of the field/s used for the voltage raiting. Used for the value split filter. The default is [‘voltage’, ‘v’].
  - filters : [list(dict)] KiBot warnings to be ignored.
    - Valid keys:
      - error : [string=’’] Error id we want to exclude.
      - 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.
      - regex : [string=’’] Regular expression to match the text for the error we want to exclude.
      - regexp : Alias for regex.
  - git_diff_strategy : [string=’worktree’] [worktree,stash] When computing a PCB/SCH diff it configures how do we preserve the current working state. The worktree mechanism creates a separated worktree, that then is just removed. The stash mechanism uses git stash push/pop to save the current changes. Using worktree is the preferred mechanism.
  - hide_excluded : [boolean=false] Default value for the hide_excluded option of various PCB outputs.
  - impedance_controlled : [boolean=false] The PCB needs specific dielectric characteristics. KiCad 6: you should set this in the Board Setup -> Physical Stackup.
  - include_components_from_pcb : [boolean=true] Include components that are only in the PCB, not in the schematic, for filter and variants processing. Note that version 1.6.3 and older ignored them.
  - invalidate_pcb_text_cache : [string=’auto’] [auto,yes,no] Remove any cached text variable in the PCB. This is needed in order to force a text variables update when using set_text_variables. You might want to disable it when applying some changes to the PCB and create a new copy to send to somebody without changing the cached values. The auto value will remove the cached values only when using set_text_variables.
  - kiauto_time_out_scale : [number=0.0] Time-out multiplier for KiAuto operations.
  - kiauto_wait_start : [number=0] Time to wait for KiCad in KiAuto operations.
  - kicad_dnp_applied : [boolean=true] The KiCad v7 PCB flag Do Not Populate is applied to our fitted flag before running any filter.
  - kicad_dnp_applies_to_3D : [boolean=true] The KiCad v7 PCB flag Do Not Populate is applied to our fitted flag for 3D models, even when no filter/variant is specified. Disabling kicad_dnp_applied also disables this flag.
  - layer_defaults : [list(dict)] Used to indicate the default suffix and description for the layers. Note that the name for the layer must match exactly, no aliases.
    - Valid keys:
      - description : [string=’’] A description for the layer, for documentation purposes. A default can be specified using the layer_defaults global option.
      - layer : [string=’’] Name of the layer. As you see it in KiCad.
      - suffix : [string=’’] Suffix used in file names related to this layer. Derived from the name if not specified. A default can be specified using the layer_defaults global option.
  - out_dir : [string=’’] Base output dir, same as command line –out-dir.
  - output : [string=’%f-%i%I%v.%x’] Default pattern for output file names. Affected by global options.
  - pcb_finish : [string=’HAL’] Finishing used to protect pads. Currently used for documentation and to choose default colors. KiCad 6: you should set this in the Board Setup -> Board Finish -> Copper Finish option. Currently known are None, HAL, HASL, HAL SnPb, HAL lead-free, ENIG, ENEPIG, Hard gold, ImAg, Immersion Silver, Immersion Ag, ImAu, Immersion Gold, Immersion Au, Immersion Tin, Immersion Nickel, OSP and HT_OSP.
  - pcb_material : [string=’FR4’] PCB core material. Currently used for documentation and to choose default colors. Currently known are FR1 to FR5.
  - remove_adhesive_for_dnp : [boolean=true] When applying filters and variants remove the adhesive (glue) for components that won’t be included.
  - remove_solder_mask_for_dnp : [boolean=false] When applying filters and variants remove the solder mask apertures for components that won’t be included.
  - remove_solder_paste_for_dnp : [boolean=true] When applying filters and variants remove the solder paste for components that won’t be included.
  - resources_dir : [string=’kibot_resources’] Directory where various resources are stored. Currently we support colors and fonts. They must be stored in sub-dirs. I.e. kibot_resources/fonts/MyFont.ttf Note this is mainly useful for CI/CD, so you can store fonts and colors in your repo. Also note that the fonts are installed using a mechanism known to work on Debian, which is used by the KiBot docker images, on other OSs your mileage may vary.
  - restore_project : [boolean=false] Restore the KiCad project after execution. Note that this option will undo operations like set_text_variables. Starting with 1.6.4 it also restores the PRL (Project Local Settings) and DRU (Design RUles) files.
  - set_text_variables_before_output : [boolean=false] Run the set_text_variables preflight before running each output that involves variants. This can be used when a text variable uses the variant and you want to create more than one variant in the same run. Note that this could be slow because it forces a board reload each time you run an output that uses variants.
  - silk_screen_color : [string=’white’] Color for the markings. Currently used for documentation and to choose default colors. KiCad 6: you should set this in the Board Setup -> Physical Stackup. Currently known are black and white.
  - silk_screen_color_bottom : [string=’’] Color for the bottom silk screen. When not defined silk_screen_color is used. Read silk_screen_color help.
  - silk_screen_color_top : [string=’’] Color for the top silk screen. When not defined silk_screen_color is used. Read silk_screen_color help.
  - solder_mask_color : [string=’green’] Color for the solder mask. Currently used for documentation and to choose default colors. KiCad 6: you should set this in the Board Setup -> Physical Stackup. Currently known are green, black, white, yellow, purple, blue and red.
  - solder_mask_color_bottom : [string=’’] Color for the bottom solder mask. When not defined solder_mask_color is used. Read solder_mask_color help.
  - solder_mask_color_top : [string=’’] Color for the top solder mask. When not defined solder_mask_color is used. Read solder_mask_color help.
  - str_no : [string=’no’] String used for no. Currently used by the update_pcb_characteristics preflight.
  - str_yes : [string=’yes’] String used for yes. Currently used by the update_pcb_characteristics preflight.
  - time_format : [string=’%H-%M-%S’] Format used for the time we started the script. Uses the strftime format.
  - time_reformat : [boolean=true] Tries to reformat the PCB/SCH date using the date_format. This assumes you let KiCad fill this value and hence the time is in ISO format (YY-MM-DD).
  - units : [string=’’] [millimeters,inches,mils] Default units. Affects position, bom and panelize outputs and the erc and drc preflights. Also KiCad 6 dimensions.
  - use_dir_for_preflights : [boolean=true] Use the global dir as subdir for the preflights.
  - use_os_env_for_expand : [boolean=true] In addition to KiCad text variables also use the OS environment variables when expanding ${VARIABLE}.
  - variant : [string=’’] Default variant to apply to all outputs.