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 filesdir
is the directory where this output will be stored.extends
used to use another output’soptions
as base.run_by_default
indicates this output will be created when no specific outputs are requested.disable_run_by_default
can be used to disable therun_by_default
status of other output.output_id
text to use for the %I expansion content.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 (from John Beard) 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 plothpgl
format for laser printerssvg
scalable vector graphicspdf
portable document formatdxf
mechanical CAD format
Drill formats:
excellon
data for the drilling machinegerb_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 formatsvg_sch_print
schematic in SVG formatps_sch_print
schematic in PS formatdxf_sch_print
schematic in DXF formathpgl_sch_print
schematic in HPGL formatpdf_pcb_print
PDF file containing one or more layer and the page framesvg_pcb_print
SVG file containing one or more layer and the page framepcb_print
PDF/SVG/PNG/EPS/PS, similar topdf_pcb_print
andsvg_pcb_print
, with more flexibilityreport
generates a report about the PDF. Can include images from the above outputs.diff
creates PDF files showing schematic or PCB changes.kiri
creates an interactive web page showing schematic or PCB changes.
Bill of Materials
bom
The internal BoM generator.kibom
BoM in HTML or CSV format generated by KiBoMibom
Interactive HTML BoM generated by InteractiveHtmlBomkicost
BoM in XLSX format with costs generated by KiCost
3D model:
step
Standard for the Exchange of Product Data for the PCBvrml
Virtual Reality Modeling Language for the PCBrender_3d
PCB render, from the KiCad’s 3D Viewerblender_export
PCB export to Blender and high quality 3D render. Including export to:fbx
(Kaydara’s Filmbox), ‘obj’ (Wavefront), ‘x3d’ (ISO/IEC standard),gltf
(GL format),stl
(3D printing) and ‘ply’ (Stanford).
Web pages:
populate
To create step-by-step assembly instructions.kikit_present
To create a project presentation web page.navigate_results
generates web pages to navigate the generated outputs.kicanvas
creates a web page to display the schematic and/or PCB
Fabrication helpers:
panelize
creates a PCB panel containing N copies of the PCB.stencil_3d
creates a 3D self-registering printable stencil.stencil_for_jig
creates steel stencils and 3D register.
Others:
boardview
creates a file useful to repair the board, but without disclosing the full layout.gencad
exports the PCB in GENCAD format.compress
creates an archive containing generated data.download_datasheets
downloads the datasheets for all the components.pcbdraw
nice images of the PCB in customized colors.pdfunite
joins various PDF files into one.qr_lib
generates symbol and footprints for QR codes.sch_variant
the schematic after applying all filters and variants, including crossed components.pcb_variant
the PCB after applying all filters and variants, including modified 3D models.copy_files
used to copy generated files and source material.info
creates a report about the tools used during the KiBot run.netlist
generates the list of connections for the project (classic and IPC-D-356 formats).
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.
Outputs are generated in the order they are declared in the YAML file.
To create them in an arbitrary order use the --cli-order
command
line option and they will be created in the order specified in the
command line.
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.)
inners all the inner copper layers
outers all the outer copper layers
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 anchor, 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
Supported outputs
Notes:
Most relevant options are listed first and in bold. Which ones are more relevant is quite arbitrary, comments are welcome.
Aliases are listed in italics.
- Blender Export
- BoardView
- BoM (Bill of Materials)
- Archiver (files compressor)
- Files copier
- Diff
- Datasheets downloader
- DXF (Drawing Exchange Format)
- DXF Schematic Print (Drawing Exchange Format)
- Excellon drill format
- GenCAD
- Gerber drill format
- Gerber format
- HPGL (Hewlett & Packard Graphics Language)
- HPGL Schematic Print (Hewlett & Packard Graphics Language)
- IBoM (Interactive HTML BoM)
- Info
- KiBoM (KiCad Bill of Materials)
- KiCanvas
- KiCost (KiCad Cost calculator)
- KiKit’s Present - Project Presentation
- KiRi
- Navigate Results
- Netlist
- Panelize
- PCB2Blender Tools
- PCB Print
- PCB with variant generator
- PcbDraw - Beautiful 2D PCB render
- PDF (Portable Document Format)
- PDF PCB Print (Portable Document Format) Deprecated
- PDF Schematic Print (Portable Document Format)
- PDF joiner
- Populate - Assembly instructions builder
- Pick & place
- PS (Postscript)
- PS Schematic Print (Postscript)
- QR_Lib
- 3D render of the PCB
- Design report
- Schematic with variant generator
- 3D Printed Stencils
- Steel Stencils for Alignment Jig
- STEP (ISO 10303-21 Clear Text Encoding of the Exchange Structure)
- SVG (Scalable Vector Graphics)
- SVG PCB Print (Scalable Vector Graphics) Deprecated
- SVG Schematic Print
- VRML (Virtual Reality Modeling Language)
Consolidating BoMs
Some times your project is composed by various boards, other times you are producing various products at the same time. In both cases you would want to consolidate the components acquisition in one operation. Of course you can create individual BoMs for each project in CSV format and then consolidate them using a spreadsheet editor. But KiBot offers another option: you create a BoM for your main project and then aggregate the components from the other projects.
Here is a simple example. Suppose you have three projects: merge_1, merge_2 and merge_3. For the merge_1 project you could use the following output:
kibot:
version: 1
outputs:
- name: 'bom_csv'
comment: "Bill of Materials in CSV format"
type: bom
dir: BoM
options:
use_alt: true
Using the tests/board_samples/kicad_5/merge_1.sch
from the git repo
and storing the above example in m1.kibot.yaml
you could run:
src/kibot -c m1.kibot.yaml -e tests/board_samples/kicad_5/merge_1.sch -d test_merge
And get test_merge/BoM/merge_1-bom.csv
:
Row |
Description |
Part |
References |
Value |
Footprint |
Quantity Per PCB |
Status |
Datasheet |
---|---|---|---|---|---|---|---|---|
1 |
Unpolarized capacitor |
C |
C1 |
1nF |
1 |
~ |
||
2 |
Unpolarized capacitor |
C |
C2 |
10nF |
1 |
~ |
||
3 |
Resistor |
R |
R1-R3 |
1k |
3 |
~ |
Project info: |
|
---|---|
Schematic: |
merge_1 |
Variant: |
default |
Revision: |
|
Date: |
2021-02-02_12-12-27 |
KiCad Version: |
5.1.9-73d0e3b20d~88~ubuntu21.04.1 |
Statistics: |
|
Component Groups: |
3 |
Component Count: |
5 |
Fitted Components: |
5 |
Number of PCBs: |
1 |
Total Components: |
5 |
This CSV says you have five components groped in three different types. They are one 1 nF capacitor, one 10 nF capacitor and three 1 k resistors. Now lets generate BoMs for the merge_2 example:
src/kibot -c m1.kibot.yaml -e tests/board_samples/kicad_5/merge_2.sch -d test_merge
We’ll get test_merge/BoM/merge_2-bom.csv
:
Row |
Description |
Part |
References |
Value |
Footprint |
Quantity Per PCB |
Status |
Datasheet |
---|---|---|---|---|---|---|---|---|
1 |
Unpolarized capacitor |
C |
C2 |
1nF |
1 |
~ |
||
2 |
Unpolarized capacitor |
C |
C1 |
10nF |
1 |
~ |
||
3 |
Resistor |
R |
R2-R4 |
1000 |
3 |
~ |
||
4 |
Resistor |
R |
R1 |
10k |
1 |
~ |
Project info: |
|
---|---|
Schematic: |
merge_2 |
Variant: |
default |
Revision: |
|
Date: |
2021-01-27_10-19-46 |
KiCad Version: |
5.1.9-73d0e3b20d~88~ubuntu21.04.1 |
Statistics: |
|
Component Groups: |
4 |
Component Count: |
6 |
Fitted Components: |
6 |
Number of PCBs: |
1 |
Total Components: |
6 |
In this project we have six components from four different types. They are similar to merge_1 but now we also have a 10 k resistor. We don’t need to generate this BoM to consolidate our projects, but is good to know what we have. And now lets generate BoMs for the merge_3 example:
src/kibot -c m1.kibot.yaml -e tests/board_samples/kicad_5/merge_3.sch -d test_merge
We’ll get test_merge/BoM/merge_3-bom.csv
:
Row |
Description |
Part |
References |
Value |
Footprint |
Quantity Per PCB |
Status |
Datasheet |
---|---|---|---|---|---|---|---|---|
1 |
Resistor |
R |
R5 |
1k |
1 |
~ |
||
2 |
Resistor |
R |
R1-R4 |
10k |
4 |
~ |
Project info: |
|
---|---|
Schematic: |
merge_3 |
Variant: |
default |
Revision: |
|
Date: |
2021-01-27_10-21-29 |
KiCad Version: |
5.1.9-73d0e3b20d~88~ubuntu21.04.1 |
Statistics: |
|
Component Groups: |
2 |
Component Count: |
5 |
Fitted Components: |
5 |
Number of PCBs: |
1 |
Total Components: |
5 |
This time we also have five components, but from two different types. They are one 1 k resistor and four 10 k resistors. Now suppose we want to create 10 boards for merge_1, 20 for merge_2 and 30 for merge_3. We could use the following configuration:
kibot:
version: 1
outputs:
- name: 'bom_csv'
comment: "Bill of Materials in CSV format"
type: bom
dir: BoM
options:
use_alt: true
number: 10
aggregate:
- file: tests/board_samples/kicad_5/merge_2.sch
number: 20
- file: tests/board_samples/kicad_5/merge_3.sch
number: 30
Save it as m2.kibot.yaml
and run:
src/kibot -c m2.kibot.yaml -e tests/board_samples/kicad_5/merge_1.sch -d test_merge_consolidate
The test_merge_consolidate/BoM/merge_1-bom.csv
file will be
generated containing:
Row |
Description |
Part |
References |
Value |
Footprint |
Quantity Per PCB |
Build quantity |
Status |
Datasheet |
Source BoM |
---|---|---|---|---|---|---|---|---|---|---|
1 |
Unpolarized capacitor |
C |
C1 C2 |
1nF |
2 |
30 |
~ |
merge_1(1) merge_2(1) |
||
2 |
Unpolarized capacitor |
C |
C2 C1 |
10nF |
2 |
30 |
~ |
merge_1(1) merge_2(1) |
||
3 |
Resistor |
R |
R1-R3 R2-R4 R5 |
1k |
7 |
120 |
~ |
merge_1(3) merge_2(3) merge_3(1) |
||
4 |
Resistor |
R |
R1 R1-R4 |
10k |
5 |
140 |
~ |
merge_2(1) merge_3(4) |
Project info: |
|
---|---|
Variant: |
default |
KiCad Version: |
5.1.9-73d0e3b20d~88~ubuntu21.04.1 |
Global statistics: |
|
Component Groups: |
4 |
Component Count: |
16 |
Fitted Components: |
16 |
Number of PCBs: |
60 |
Total Components: |
320 |
Project info: |
merge_1 |
Schematic: |
merge_1 |
Revision: |
|
Date: |
2021-02-02_12-12-27 |
Company: |
Test company |
Statistics: |
merge_1 |
Component Groups: |
3 |
Component Count: |
5 |
Fitted Components: |
5 |
Number of PCBs: |
10 |
Total Components: |
50 |
Project info: |
merge_2 |
Schematic: |
merge_2 |
Revision: |
|
Date: |
2021-01-27_10-19-46 |
Statistics: |
merge_2 |
Component Groups: |
4 |
Component Count: |
6 |
Fitted Components: |
6 |
Number of PCBs: |
20 |
Total Components: |
120 |
Project info: |
merge_3 |
Schematic: |
merge_3 |
Revision: |
|
Date: |
2021-01-27_10-21-29 |
Statistics: |
merge_3 |
Component Groups: |
2 |
Component Count: |
5 |
Fitted Components: |
5 |
Number of PCBs: |
30 |
Total Components: |
150 |
You can see that now we have much more stats. They say we have four different types, thirteen for board sets, a total of 60 boards and 250 components. Then we have individual stats for each project. The capacitors are easy to interpret, we have 30 1 nF capacitors merge_1 project has one and merge_2 another. As we have 10 merge_1 and 20 merge_2 boards this is clear. But looking at the 1 k resistors is harder. We have 80, three from merge_1, one from merge_2 and another from merge_3. So we have 103+203+30=120, this is clear, but the BoM says they are R1-R3 R2-R4 R5, which is a little bit confusing. In this simple example is easy to correlate R1-R3 to merge_1, R2-R4 to merge_2 and R5 to merge_1. For bigger projects this gets harder. Lets assign an id to each project, we’ll use ‘A’ for merge_1, ‘B’ for merge_2 and ‘C’ for merge_3:
kibot:
version: 1
outputs:
- name: 'bom_csv'
comment: "Bill of Materials in CSV format"
type: bom
dir: BoM
options:
use_alt: true
number: 10
ref_id: 'A:'
aggregate:
- file: tests/board_samples/kicad_5/merge_2.sch
number: 20
ref_id: 'B:'
- file: tests/board_samples/kicad_5/merge_3.sch
number: 30
ref_id: 'C:'
Now test_merge_consolidate/BoM/merge_1-bom.csv
will have the
following information:
Row |
Description |
Part |
References |
Value |
Footprint |
Quantity Per PCB |
Build quantity |
Status |
Datasheet |
Source BoM |
---|---|---|---|---|---|---|---|---|---|---|
1 |
Unpolarized capacitor |
C |
A:C1 B:C2 |
1nF |
2 |
30 |
~ |
merge_1(1) merge_2(1) |
||
2 |
Unpolarized capacitor |
C |
A:C2 B:C1 |
10nF |
2 |
30 |
~ |
merge_1(1) merge_2(1) |
||
3 |
Resistor |
R |
A:R1-A:R3 B:R2-B:R4 C:R5 |
1k |
7 |
120 |
~ |
merge_1(3) merge_2(3) merge_3(1) |
||
4 |
Resistor |
R |
B:R1 C:R1-C:R4 |
10k |
5 |
140 |
~ |
merge_2(1) merge_3(4) |
As you can see now we know A
has R1-R3, B
R2-R4 and for C
R5
is the 1k resistor. If we want to compact the Source BoM
column we
just need to enable the source_by_id
option:
kibot:
version: 1
outputs:
- name: 'bom_csv'
comment: "Bill of Materials in CSV format"
type: bom
dir: BoM
options:
use_alt: true
number: 10
ref_id: 'A:'
source_by_id: true
aggregate:
- file: tests/board_samples/kicad_5/merge_2.sch
number: 20
ref_id: 'B:'
- file: tests/board_samples/kicad_5/merge_3.sch
number: 30
ref_id: 'C:'
And we’ll get:
Row |
Description |
Part |
References |
Value |
Footprint |
Quantity Per PCB |
Build quantity |
Status |
Datasheet |
Source BoM |
---|---|---|---|---|---|---|---|---|---|---|
1 |
Unpolarized capacitor |
C |
A:C1 B:C2 |
1nF |
2 |
30 |
~ |
A:(1) B:(1) |
||
2 |
Unpolarized capacitor |
C |
A:C2 B:C1 |
10nF |
2 |
30 |
~ |
A:(1) B:(1) |
||
3 |
Resistor |
R |
A:R1-A:R3 B:R2-B:R4 C:R5 |
1k |
7 |
120 |
~ |
A:(3) B:(3) C:(1) |
||
4 |
Resistor |
R |
B:R1 C:R1-C:R4 |
10k |
5 |
140 |
~ |
B:(1) C:(4) |
Columns available for the BoM
In addition to all the user defined fields you also have the following columns:
References: The component references.
Description: The description from the component library (DCM file). Note that a user field with the same name has more precedence.
Value: The value for the component. Affected by the normalize_values option.
Footprint: The name of the footprint, without the library name.
Footprint Lib: The name of the library for the footprint.
Footprint X: The X coordinate for the footprint.
Footprint Y: The Y coordinate for the footprint.
Footprint Rot: The rotation angle for the footprint.
Footprint Side: The side of the footprint, bottom or top.
Footprint Type: The type of the footprint, can be: SMD, THT or VIRTUAL. Affected by the footprint_type_values option.
Footprint Populate: If the footprint is populated (soldered) or not, can be: yes or no. Affected by the footprint_populate_values option.
Footprint X-Size: The footprint width, no rotation computed.
Footprint Y-Size: The footprint height, no rotation computed.
Part: The name of the symbol for the component, without the library name.
Part Lib: The name of the library for the symbol.
Datasheet: The datasheet from the standard field.
Sheetpath: The path in the schematic hierarchy for the component.
Row: The row number in the BoM for this entry.
Status: The DNF (Do Not Fit) and/or DNC (Do Not Change) status for the component.
Quantity Per PCB: How many components we use for this row for each PCB.
Build Quantity: How many components we use for this row for all the PCBs.
Source BoM: From which BoM/s comes this component/s. This is used when consolidating more than one BoM.
Most of the footprint columns are oriented to the creation of position files using the BoM output, for more information consult XYRS files.
Using other output as base for a new one
If you need to define an output that is similar to another, and you want
to avoid copying the options from the former, you can extend an
output. To achieve it just specify the name of the base output in the
extends
value. Note that this will use the options
of the other
output as base, not other data as the comment.
Also note that you can use YAML anchors, but this won’t work if you are importing the base output from other file.
Additionally you must be aware that extending an output doesn’t disable
the base output. If you need to disable the original output use
disable_run_by_default
option.
Grouping outputs
Sometimes you want to generate various outputs together. An example could be the fabrication files, or the documentation for the project.
To explain it we will use an example where you have six outputs. Three
are used for fabrication: gerbers
, excellon_drill
and
position
. Another three are used for documentation: SVG
,
PcbDraw
and PcbDraw2
. The YAML config containing this example
can be found here. If you
need to generate the fabrication outputs you must run:
kibot gerbers excellon_drill position
One mechanism to group the outputs is to create a compress
output
that just includes the outputs you want to group. Here is one example:
- name: compress_fab
comment: "Generates a ZIP file with all the fab outputs"
type: compress
run_by_default: false
options:
files:
- from_output: gerbers
- from_output: excellon_drill
- from_output: position
The compress_fab
output will generate the gerbers
,
excellon_drill
and position
outputs. Then it will create a ZIP
file containing the files generated by these outputs. The command line
invocation for this is:
kibot compress_fab
Using this mechanism you are forced to create a compressed output. To
avoid it you can use groups
. The groups
section is used to
create groups of outputs. Here is the example for fabrication files:
groups:
- name: fab
outputs:
- gerbers
- excellon_drill
- position
So now you can just run:
kibot fab
The gerbers
, excellon_drill
and position
outputs will be
generated without the need to generate an extra file. Groups can be
nested, here is an example:
groups:
- name: fab
outputs:
- gerbers
- excellon_drill
- position
- name: plot
outputs:
- SVG
- PcbDraw
- PcbDraw2
- name: fab_svg
outputs:
- fab
- SVG
Here the fab_svg
group will contain gerbers
, excellon_drill
,
position
and SVG
.
Groups can be imported from another YAML file.
Avoid naming groups using _
as first character. These names are
reserved for KiBot.