Updated the README.md and added a brief YAML explanation.
This commit is contained in:
Salvador E. Tropea
parent
d5168c37cd
commit
a1d5f62fcd
35
README.md
35
README.md
|
|
@ -2,15 +2,16 @@
|
|||
|
||||
 [](https://coveralls.io/github/INTI-CMNB/kiplot?branch=master)
|
||||
|
||||
KiPlot is a program which helps you to plot your KiCad PCBs to output
|
||||
formats easily, repeatable, and most of all, scriptably. This means you
|
||||
can use a Makefile to export your KiCad PCBs just as needed.
|
||||
KiPlot 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
|
||||
* Fab docs for the assembler, including the BoM (Bill of Materials)
|
||||
* Pick and place files
|
||||
* PCB 3D model in STEP format
|
||||
|
||||
|
|
@ -20,20 +21,20 @@ datasheet.
|
|||
|
||||
KiPlot lets you do this.
|
||||
|
||||
As a side effect of providing a scriptable plot driver for KiCad, KiPlot also
|
||||
allows functional testing of KiCad plot functions, which would otherwise be
|
||||
somewhat unwieldy to write.
|
||||
|
||||
## The configuration file
|
||||
|
||||
Kiplot 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 **.kiplot.yaml**. The format used is
|
||||
[YAML](https://yaml.org/). This is basically a text file with some structure.
|
||||
The configuration file should be named using the **.kiplot.yaml** suffix,
|
||||
i.e. *my_project.kiplot.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](docs/KiPlotYAML.md).
|
||||
Note that the explanation could be useful even if you know YAML.
|
||||
|
||||
### The header
|
||||
|
||||
All configuration files must start with:
|
||||
|
|
@ -79,9 +80,13 @@ preflight:
|
|||
|
||||
### 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.
|
||||
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:
|
||||
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:
|
||||
|
|
@ -833,8 +838,9 @@ Options:
|
|||
### Dependencies
|
||||
|
||||
- For ERC, DRC, BoM XML update and PCB/SCH print install [KiCad Automation Scripts](https://github.com/INTI-CMNB/kicad-automation-scripts/)
|
||||
- For HTML/CSV BoM install [KiBoM](https://github.com/INTI-CMNB/KiBoM)
|
||||
- For HTML/CSV/XML/XLSX BoM install [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:
|
||||
|
||||
|
|
@ -843,6 +849,9 @@ Get the Debian package from the [releases section](https://github.com/INTI-CMNB/
|
|||
sudo apt install ./kiplot.inti-cmnb_*_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.
|
||||
|
||||
### Installation on other targets
|
||||
|
||||
- Install KiCad 5.x
|
||||
|
|
|
|||
|
|
@ -0,0 +1,265 @@
|
|||
# KiPlot YAML
|
||||
|
||||
You can find a lot of information about YAML format on internet. This document doesn't pretend to be a complete YAML
|
||||
reference, just a complement to understand how to use it for the configuration files.
|
||||
|
||||
YAML files are structured data arranged in a way that's easy to understand.
|
||||
|
||||
## The basic idea
|
||||
|
||||
You associate data with labels. After a label you put a colon (**:**) and then the data:
|
||||
|
||||
```.{yaml}
|
||||
version: 1
|
||||
```
|
||||
|
||||
Here so associate the label **version** with the data value **1**.
|
||||
|
||||
## Basic data types
|
||||
|
||||
We use three basic data types:
|
||||
|
||||
- **number**: can be integer, floating point, positive and negative.
|
||||
- **boolean**: can take only two values *true* and *false*.
|
||||
- **string**: almost anything else.
|
||||
|
||||
Here are some examples for numbers:
|
||||
|
||||
```.{yaml}
|
||||
v1: 1
|
||||
v2: 5.3
|
||||
v3: -3
|
||||
```
|
||||
|
||||
Note that the decimal point is always a point, no matters what your locale settings indicate.
|
||||
|
||||
Here are some examples for booleans:
|
||||
|
||||
```.{yaml}
|
||||
v1: true
|
||||
v2: false
|
||||
```
|
||||
|
||||
And here are some examples for strings:
|
||||
|
||||
```.{yaml}
|
||||
v1: Hi!
|
||||
v2: '3'
|
||||
v3: "true"
|
||||
v4: " I have spaces "
|
||||
```
|
||||
|
||||
Note that quotes are optional and can be used to disambiguate.
|
||||
|
||||
## Compound data types
|
||||
|
||||
We use two types:
|
||||
|
||||
- **list**: just a list of data elements. Each element start with a hyphen (**-**).
|
||||
- **dict**: dictionaries or maps. Just a bunch of label with associated data.
|
||||
|
||||
Here is an example for a list of strings (**list(string)** in our case):
|
||||
|
||||
```.{yaml}
|
||||
- abc
|
||||
- '3'
|
||||
- "true"
|
||||
- " I have spaces "
|
||||
```
|
||||
|
||||
And here an example for a dict:
|
||||
|
||||
```.{yaml}
|
||||
v1: Hi!
|
||||
v2: '3'
|
||||
v3: "true"
|
||||
v4: " I have spaces "
|
||||
```
|
||||
|
||||
The list and dict elements can also be other lists and/or dicts.
|
||||
To understand how this is achieved we need one more thing.
|
||||
|
||||
## Indentation
|
||||
|
||||
YAML uses the indentation to group data that belongs to a label.
|
||||
|
||||
Here is an example of a list associated to a label:
|
||||
|
||||
```.{yaml}
|
||||
people:
|
||||
- John
|
||||
- Cindy
|
||||
- Luca
|
||||
- Laura
|
||||
```
|
||||
|
||||
We use two spaces, other values are possible, but you must keep coherence in the indentation.
|
||||
And here we have a dict:
|
||||
|
||||
```.{yaml}
|
||||
John:
|
||||
age: 25
|
||||
gender: male
|
||||
```
|
||||
|
||||
And here is a mix of both:
|
||||
|
||||
```.{yaml}
|
||||
people:
|
||||
- John:
|
||||
age: 25
|
||||
gender: male
|
||||
- Cindy
|
||||
- Luca
|
||||
- Laura
|
||||
```
|
||||
|
||||
The indentation shows that `age` and `gender` are attached to `John`, not directly applied to `people`.
|
||||
|
||||
Note that lists can be nested, here is a list of lists (**list(list(string))**):
|
||||
|
||||
```.{yaml}
|
||||
list_of_lists:
|
||||
- - a
|
||||
- b
|
||||
- c
|
||||
- - 1
|
||||
- 2
|
||||
- 3
|
||||
- 4
|
||||
```
|
||||
|
||||
In this example we have a list with two elements, the first is a list with three elements and the second a list with four
|
||||
elements.
|
||||
|
||||
## Compact notation
|
||||
|
||||
You can use a more compat notation for small lists and dicts.
|
||||
The following list:
|
||||
|
||||
```.{yaml}
|
||||
list_of_lists:
|
||||
- - a
|
||||
- b
|
||||
- c
|
||||
- - 1
|
||||
- 2
|
||||
- 3
|
||||
- 4
|
||||
```
|
||||
|
||||
Can be defined in the following way:
|
||||
|
||||
```.{yaml}
|
||||
list_of_lists:
|
||||
- [ a, b, c ]
|
||||
- [ 1, 2, 3, 4 ]
|
||||
```
|
||||
|
||||
And this example:
|
||||
|
||||
```.{yaml}
|
||||
people:
|
||||
- John:
|
||||
age: 25
|
||||
gender: male
|
||||
- Cindy
|
||||
- Luca
|
||||
- Laura
|
||||
```
|
||||
|
||||
Can be defined as:
|
||||
|
||||
```.{yaml}
|
||||
people:
|
||||
- John: { age: 25, gender: male }
|
||||
- Cindy
|
||||
- Luca
|
||||
- Laura
|
||||
```
|
||||
|
||||
## Putting all together
|
||||
|
||||
So a **.kiplot.yaml** file is basically a dict containing the following labels:
|
||||
|
||||
- `kiplot`: contains a dict with special global options. Currently the format version used.
|
||||
- `preflight`: contains a dict with pre-flight (or pre-run) actions.
|
||||
- `outputs`: contains a list of outputs (or targets).
|
||||
|
||||
## Advanced tricks
|
||||
|
||||
If you have various similar outputs with repeating options you can use *anchors*.
|
||||
This a nice YAML feature that allows to memorize a value and reuse it.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```.{yaml}
|
||||
kiplot:
|
||||
version: 1
|
||||
|
||||
outputs:
|
||||
- name: PcbDraw 1
|
||||
comment: "PcbDraw test top"
|
||||
type: pcbdraw
|
||||
dir: PcbDraw
|
||||
options: &pcb_draw_ops
|
||||
format: svg
|
||||
style:
|
||||
board: "#1b1f44"
|
||||
copper: "#00406a"
|
||||
silk: "#d5dce4"
|
||||
pads: "#cfb96e"
|
||||
clad: "#72786c"
|
||||
outline: "#000000"
|
||||
vcut: "#bf2600"
|
||||
highlight_on_top: false
|
||||
highlight_style: "stroke:none;fill:#ff0000;opacity:0.5;"
|
||||
highlight_padding: 1.5
|
||||
libs:
|
||||
- default
|
||||
- eagle-default
|
||||
remap:
|
||||
L_G1: "LEDs:LED-5MM_green"
|
||||
L_B1: "LEDs:LED-5MM_blue"
|
||||
L_Y1: "LEDs:LED-5MM_yellow"
|
||||
PHOTO1: "yaqwsx:R_PHOTO_7mm"
|
||||
J8: "yaqwsx:Pin_Header_Straight_1x02_circle"
|
||||
'REF**': "dummy:dummy"
|
||||
G***: "dummy:dummy"
|
||||
svg2mod: "dummy:dummy"
|
||||
JP1: "dummy:dummy"
|
||||
JP2: "dummy:dummy"
|
||||
JP3: "dummy:dummy"
|
||||
JP4: "dummy:dummy"
|
||||
no_drillholes: False
|
||||
mirror: False
|
||||
highlight:
|
||||
- L_G1
|
||||
- L_B1
|
||||
- R10
|
||||
- RV1
|
||||
show_components: all
|
||||
vcuts: True
|
||||
warnings: visible
|
||||
dpi: 600
|
||||
|
||||
- name: PcbDraw 2
|
||||
comment: "PcbDraw test bottom"
|
||||
type: pcbdraw
|
||||
dir: PcbDraw
|
||||
options:
|
||||
<<: *pcb_draw_ops
|
||||
style: set-red-enig
|
||||
bottom: True
|
||||
show_components:
|
||||
- L_G1
|
||||
- L_B1
|
||||
remap:
|
||||
```
|
||||
|
||||
Here we have two outputs: 'PcbDraw 1' and 'PcbDraw 2'. The options for are big because we are including a custom color style
|
||||
and a list of component remappings. In this case 'PcbDraw 2' wants to use the same options, but with some changes.
|
||||
So we use an anchor in the first options list (`&pcb_draw_ops`) and then we copy the data with `<<: *pcb_draw_ops`.
|
||||
The good thing is that we can overwrite options. Here we choose another `style` (ridiculous example), the bottom side
|
||||
(good example), a different list of components to show and we eliminate the `remap` dict.
|
||||
|
||||
Loading…
Reference in New Issue