482 lines
15 KiB
Plaintext
482 lines
15 KiB
Plaintext
# KiBot (formerly KiPlot)
|
|
|
|
|
|
|
|
[](https://github.com/INTI-CMNB/KiBot/actions)
|
|
[](https://coveralls.io/github/INTI-CMNB/KiBot?branch=master)
|
|
[](https://pypi.org/project/kibot/)
|
|
|
|
## 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:
|
|
|
|
|
|
|
|
|
|
## 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)
|