# KiBot (formerly KiPlot)
[](https://github.com/INTI-CMNB/KiBot/actions)
[](https://coveralls.io/github/INTI-CMNB/KiBot?branch=master)
[](https://pypi.org/project/kibot/)
**New on 0.7.0**:
Now KiBot supports *variants*. To my knowledge this is the first tool to implement such a feature, in a transparent way and from schematic to PCB, for KiCad.
To learn more about KiBot variants visit the [example repo](https://inti-cmnb.github.io/kibot_variants_arduprog/).
## Index
* [Introduction](#introduction)
* [Configuration](#configuration)
* [Usage](#usage)
* [Installation](#installation)
* [Usage for CI/CD](#usage-for-cicd)
* [Credits](#credits)
## Introduction
KiBot is a program which helps you to generate the fabrication and
documentation files for your KiCad projects easily, repeatable, and
most of all, scriptably. This means you can use a Makefile to export
your KiCad PCBs just as needed.
For example, it's common that you might want for each board rev:
* Check ERC/DRC one last time (using [KiCad Automation Scripts](https://github.com/INTI-CMNB/kicad-automation-scripts/))
* Gerbers, drills and drill maps for a fab in their favourite format
* Fab docs for the assembler, including the BoM (Bill of Materials)
* Pick and place files
* PCB 3D model in STEP format
You want to do this in a one-touch way, and make sure everything you need to
do so it securely saved in version control, not on the back of an old
datasheet.
KiBot lets you do this. The following picture depicts the data flow:
**New on 0.7.0**:
Now KiBot supports *variants*. To my knowledge this is the first tool to implement such a feature, in a transparent way and from schematic to PCB, for KiCad.
To learn more about KiBot variants visit the [example repo](https://inti-cmnb.github.io/kibot_variants_arduprog/).
## Configuration
KiBot uses a configuration file where you can specify what *outputs* to
generate. By default you'll generate all of them, but you can specify which
ones from the command line.
The configuration file should be named using the **.kibot.yaml** suffix,
i.e. *my_project.kibot.yaml*. The format used is [YAML](https://yaml.org/).
This is basically a text file with some structure.
This file can be compressed using *gzip* file format.
If you never used YAML read the following [explanation](https://github.com/INTI-CMNB/KiBot/blob/master/docs/KiPlotYAML.md).
Note that the explanation could be useful even if you know YAML.
### The header
All configuration files must start with:
```
kibot:
version: 1
```
This tells to KiBot that this file is using version 1 of the format.
### The *preflight* section
This section is used to specify tasks that will be executed before generating any output.
#### @preflight@
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
```
#### Filtering DRC/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 lazzy 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'
number: Numeric_error_type
regex: 'Expression to match'
```
Here is an 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'
number: 4
regex: 'Pad 2 of C3'
- filter: 'Ignore unconnected pad 2 of C4'
number: 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 the scope of this manual. For a complete reference consult the [Python manual](https://docs.python.org/3/library/re.html).
**Important note**: this will create a file named *kibot_errors.filter* in the output directory.
### Default global options
The section `global` contains default global options that affects all the outputs.
Currently only one option is 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:
- **%f** original pcb/sch file name without extension.
- **%p** pcb/sch title from pcb metadata.
- **%c** company from pcb/sch metadata.
- **%r** revision from pcb/sch metadata.
- **%d** pcb/sch date from metadata if available, file modification date otherwise.
- **%D** date the script was started.
- **%T** time the script was started.
- **%i** a contextual ID, depends on the output type.
- **%x** a suitable extension for the output type.
They are compatible with the ones used by IBoM.
The default value for `global.output` is `%f-%i.%x`.
If you want to include the revision you could add the following definition:
```
global:
output: '%f_rev_%r-%i.%x'
```
### The *outputs* section
In this section you put all the things that you want to generate. This section contains one or more **outputs**. Each output contain the following data:
- `name` a name so you can easily identify it.
- `comment` a short description of this output.
- `type` selects which type of output will be generated. Examples are *gerbers*, *drill files* and *pick & place files*
- `dir` is the directory where this output will be stored.
- `options` contains one or more options to configure this output.
- `layers` a list of layers used for this output. Not all outputs needs this subsection.
**Important note about the layers**: In the original [kiplot](https://github.com/johnbeard/kiplot)
(from [John Beard](https://github.com/johnbeard)) the name of the inner layers was *Inner.N* where
*N* is the number of the layer, i.e. *Inner.1* is the first inner layer.
This format is supported for compatibility.
Note that this generated a lot of confusion because the default KiCad name for the first inner layer
is *In1.Cu*.
People filled issues and submitted pull-requests to fix it, thinking that inner layers weren't supported.
Currently KiCad allows renaming these layers, so this version of kiplot supports the name used in
KiCad. Just use the same name you see in the user interface.
The available values for *type* are:
- Plot formats:
- `gerber` the gerbers for fabrication.
- `ps` postscript plot
- `hpgl` format for laser printers
- `svg` scalable vector graphics
- `pdf` portable document format
- `dxf` mechanical CAD format
- Drill formats:
- `excellon` data for the drilling machine
- `gerb_drill` drilling positions in a gerber file
- Pick & place
- `position` of the components for the pick & place machine
- Documentation
- `pdf_sch_print` schematic in PDF format
- `pdf_pcb_print`PDF file containing one or more layer and the page frame
- Bill of Materials
- `kibom` BoM in HTML or CSV format generated by [KiBoM](https://github.com/INTI-CMNB/KiBoM)
- `ibom` Interactive HTML BoM generated by [InteractiveHtmlBom](https://github.com/INTI-CMNB/InteractiveHtmlBom)
- 3D model:
- `step` *Standard for the Exchange of Product Data* for the PCB
Here is an example of a configuration file to generate the gerbers for the top and bottom layers:
```
kibot:
version: 1
preflight:
run_drc: true
outputs:
- name: 'gerbers'
comment: "Gerbers for the board house"
type: gerber
dir: gerberdir
options:
# generic layer options
exclude_edge_layer: false
exclude_pads_from_silkscreen: false
plot_sheet_reference: false
plot_footprint_refs: true
plot_footprint_values: true
force_plot_invisible_refs_vals: false
tent_vias: true
line_width: 0.15
# gerber options
use_aux_axis_as_origin: false
subtract_mask_from_silk: true
use_protel_extensions: false
gerber_precision: 4.5
create_gerber_job_file: true
use_gerber_x2_attributes: true
use_gerber_net_attributes: false
layers:
- 'F.Cu'
- 'B.Cu'
```
Most options are the same you'll find in the KiCad dialogs.
#### Specifying the layers
You have various ways to specify the layers. If you need to specify just one layer you can just use its name:
```
layers: 'F.Cu'
```
If you want to specify all the available layers:
```
layers: 'all'
```
You can also select the layers you want in KiCad (using File, Plot dialog) and save your PCB.
Then you just need to use:
```
layers: 'selected'
```
You can also use any of the following grup of layers:
- **copper** all the copper layers
- **technical** all the technical layers (silk sreen, solder mask, paste, adhesive, etc.)
- **user** all the user layers (draw, comments, eco, margin, edge cuts, etc.)
You can also mix the above definitions using a list:
```
layers:
- 'copper'
- 'Dwgs.User'
```
This will select all the copper layers and the user drawings.
Note that the above mentioned options will use file name suffixes and descriptions selected automatically.
If you want to use a particular suffix and provide better descriptions you can use the following format:
```
layers:
- layer: 'F.Cu'
suffix: 'F_Cu'
description: 'Front copper'
- layer: 'B.Cu'
suffix: 'B_Cu'
description: 'Bottom copper'
```
You can also mix the styles:
```
layers:
- 'copper'
- layer: 'Cmts.User'
suffix: 'Cmts_User'
description: 'User comments'
- 'Dwgs.User'
```
If you need to use the same list of layers for various outputs you can use YAML anchors.
The first time you define the list of layers just assign an ancho, here is an example:
```
layers: &copper_and_cmts
- copper
- 'Cmts.User'
```
Next time you need this list just use an alias, like this:
```
layers: *copper_and_cmts
```
#### @outputs@
## Usage
If you need a template for the configuration file try:
```
kibot --example
```
This will generate a file named `example.kibot.yaml` containing all the available options and comments about them.
You can use it to create your own configuration file.
If you want to use the layers of a particular PCB in the example use:
```
kibot -b PCB_FILE --example
```
And if you want to use the same options selected in the plot dialog use:
```
kibot -b PCB_FILE -p --example
```
If the current directory contains only one PCB file and only one configuration file (named *.kibot.yaml)
you can just call `kibot`. No arguments needed. The tool will figure out which files to use.
If more than one file is found in the current directory `kibot` will use the first found and issue a
warning. If you need to use other file just tell it explicitly:
```
kibot -b PCB_FILE.kicad_pcb -c CONFIG.kibot.yaml
```
A simple target can be added to your `makefile`, so you can just run
`make pcb_files` or integrate into your current build process.
```
pcb_files:
kibot -b $(PCB) -c $(KIBOT_CFG)
```
If you need to supress messages use `--quiet` or `-q` and if you need to get more informatio about
what's going on use `--verbose` or `-v`.
If you want to generate only some of the outputs use:
```
kibot OUTPUT_1 OUTPUT_2
```
If you want to generate all outputs with some exceptions use:
```
kibot --invert-sel OUTPUT_1 OUTPUT_2
```
If you want to skip the DRC and ERC use:
```
kibot --skip-pre run_erc,run_drc
```
If you want to skip all the `preflight` tasks use:
```
kibot --skip-pre all
```
All outputs are generated using the current directory as base. If you want to use another
directory as base use:
```
kibot --out-dir OTHER_PLACE
```
If you want to list the available outputs defined in the configuration file use:
```
kibot --list
```
### Command line help
```
@cmd_help@
```
## Installation
### Dependencies
- For ERC, DRC, BoM XML update and PCB/SCH print install [KiCad Automation Scripts](https://github.com/INTI-CMNB/kicad-automation-scripts/)
- BoM files (HTML/CSV/TSV/TXT/XML/XLSX) can be generated using the internal BoM generator or using [KiBoM](https://github.com/INTI-CMNB/KiBoM).
- For interactive BoM install [InteractiveHtmlBom](https://github.com/INTI-CMNB/InteractiveHtmlBom)
- For SVG/PNG/JPG beauty PCB render [PcbDraw](https://github.com/INTI-CMNB/PcbDraw)
### Installation on Ubuntu/Debian
Get the Debian package from the [releases section](https://github.com/INTI-CMNB/KiBot/releases) and run:
```
sudo apt install ./kibot*_all.deb
```
**Important note**: Sometimes the release needs another packages that aren't part of the stable Debian distribution.
In this case the packages are also included in the release page. As an example version 0.6.0 needs:
```
sudo apt install ./python3-mcpy_2.0.2-1_all.deb ./kibot_0.6.0-1_all.deb
```
### Installation using pip
```
pip install --no-compile kibot
```
Note that `pip` has the dubious idea of compiling everything it downloads.
There is no advantage in doing it and it interferes with the `mcpy` macros.
### Installation on other targets
- Install KiCad 5.x
- Install Python 3.5 or newer
- Install the Python Yaml module
- Run the script *src/kibot*
## Usage for CI/CD
When using a GitHub or GitLab repo you can use KiBot to generate all the needed stuff each time you commit a change to the schematic and/or PCB file.
Examples of how to do it can be found [here for GitHub](https://github.com/INTI-CMNB/kicad_ci_test) and [here for GitLab](https://gitlab.com/set-soft/kicad-ci-test).
In order to run KiBot on these environments you need a lot of software installed. The usual mechanism to achieve this is using [docker](https://www.docker.com/). Docker images containing KiBot, all the supporting scripts and a corresponding KiCad can be found at [Docker Hub](https://hub.docker.com/) as [setsoft/kicad_auto:latest](https://hub.docker.com/repository/docker/setsoft/kicad_auto). This image is based on [setsoft/kicad_debian:latest](https://hub.docker.com/repository/docker/setsoft/kicad_debian), containing KiCad on Debian GNU/Linux.
For more information about the docker images visit [kicad_debian](https://github.com/INTI-CMNB/kicad_debian) and [kicad_auto](https://github.com/INTI-CMNB/kicad_auto).
## Credits
- **KiBot project**: Salvador E. Tropea (@set-soft)
- **Original KiPlot project**: John Beard (@johnbeard)
- **Original KiCad Automation Scripts**: Scott Bezek, Productize SPRL
- **KiBoM**: Oliver Henry Walters (@SchrodingersGat)
- **Interactive HTML BoM**: @qu1ck
- **PcbDraw**: Jan Mrázek (@yaqwsx)
- **Contributors**:
- **Error filters ideas**: Leandro Heck (@leoheck)
- **SVG output**: @nerdyscout
- **Others**:
- **Robot in the logo**: Christian Plaza (from pixabay)
2c98b2b634