status: beta

A stand-alone (python) tool to replace rectangular template areas drawn onto a KiCad PCB with B&W images or QR-Codes.

This was written with the intention to include QR-Codes containing git-commit specific information onto a PCB and later the generated Gerber & Drill files in a CI job.

pseudo code (python):

pcb = parseKicadPcb("some_board.kicad_pcb")
placeholders = scanForPlaceholderRectangles(pcb)
replacements = cli_args.getAsList("replacements")
if len(placeholders) != len(replacements):
    print("Bad!")
    exit(1)
for i in range(0, len(placeholders)):
    p_holder = placeholders[i]
    repl = replacements[i]
    if isSkip(repl):
        continue
    elif isImage(repl):
       pixels = loadImagePixels(p_holder.imagePath)
    elif isQrData(repl):
       pixels = generateQrCode(p_holder.data)
    pcb.replace(p_holder, pixels)
pcb.writeKicadPcb("some_board-REPLACED.kicad_pcb")

1. Design your PCB in KiCad and include rectangular polygons on any silk or copper layer. See below for more detailed instructions.

2. Make sure the images you want to inject are available (e.g. generate them).

3. Run this tool with the appropriate number of arguments (Identifiers can be (1) image paths, (2) qr-code data strings or (3) skip instructions).

   # simplest example
   python3 placeholder2image.py --input foo.kicad_pcb qr_to_inject.png
   
   # In the case of three placeholder rectangles in Kicad, use three identifier arguments:
   python3 placeholder2image.py --input ~/some/path/board.kicad_pcb qr.png skip 'qr:My Data'

   NOTE: Take care of using the correct order of the supplied replacements.

4. Done! Do what you want with the generated PCB: ~/some/path/board-REPLACED.kicad_pcb

Run python3 placeholder2image.py --help for more info.

As the KiCad PCB file format does not allow for much meta-data to be added to elements, we treat all axis-aligned, rectangular polygons as viable placeholders. If you do not want to replace some of those, you have to explicitly tell this tool to skip them.

1. Open your PCB in KiCad (pcbnew),
2. select the menu item Place -> Polygon,
3. draw an axis-aligned rectangle (don't worry if it is not perfect, you can adjust it after creation),
4. right-click on it,
5. select Properties...,
6. select the layer you want (any of: F.Cu, B.Cu, F.SilkS, B.SilkS).

NOTE
If a polygon does not have exactly 4 points, and is not perfectly axis aligned, it will not be recognized!

Take note of how many rectangles you created!

The order of the repalcement pixels sources supplied on the command-line is important, and has to correspond exactly to the order of the placeholders in the PCB.

The order of the placeholders on the PCB is defined as follows (higher up in this list is more important):

1. copper before silk
2. front before back
3. top-left corner up before down
4. top-left corner left before right
5. bottom-right corner up before down
6. bottom-right corner left before right
7. polygon before zone

input:

(generated with: qrencode -s 1 -m 1 -o qr.png "My Data")

output:

Please also see the KiCad text injector.

This project was funded by the European Regional Development Fund (ERDF) in the context of the INTERFACER Project, from July 2021 until March 2023.