Share Your Projects: KiCad Automations And Pretty Renders [Hackaday]

View Article on Hackaday

I have a pretty large GitHub repository, with all of my boards open-sourced there. Now, I’m finally facing the major problem it has – it can be uncomfortable for others to work with. I don’t store Gerber files in the repository because that will interfere with how Git functions – you’re supposed to only have source files in the repo. Yet, when someone needs Gerbers for my PCB, or a schematic PDF, or just to see how the board looks before they clone the entire repository, I often don’t have a good option for them.

In my experience as a hacker, being able to find others’ PCBs on GitHub is simply wonderful, but a PCB repository without a README feels barren, and a PCB README without pictures makes me sad. On the other hand, not having these files autogenerate is uncomfortable – updating a picture every time is a major drawback in particular.

Let’s take a look at some KiCad Git integrations, and see what they have to offer.

kicad_cli

We’ve mentioned kicad_cli back when Kicad 7 got released, and in the recently released KiCad 8, it’s only become more powerful. Before, it could do gerbers and schematic PDFs, but now, it can even do DRC checks – which is ideal if you want to add a hook for any pull requests you might encounter.

The benefit of kicad_cli is that it’s extremely simple to add – all you need to do is to install KiCad from a PPA in your workflow, then run kicad_cli on your files. How quick? Well, here’s a KiCad makefile that lets you run make pcb in your commandline – you don’t even have to open KiCad anymore if all you want is Gerbers! It’s also reasonably quick.

However, there are limitations. For one, it cannot generate images – in KiCAD v8, it has gained the ability to export 3D models, but those have neither copper nor silkscreen. Plus, kicad_cli is quite limited in which options it supports – if you want to tweak 3D model export settings, you might just find that the necessary checkbox isn’t exported as commandline option.

So, for my own purposes, pure kicad_cli won’t do – I want people to have board images, preferably, the same way they’d get one if they were to open a 3D viewer. Also, I want to be able to customize the output. Thankfully, there’s a KiCad integration juggernaut we can use, that you might even have already seen

KiKit

You might have seen KiKit be used for panelization as PCB editor plugin with a nice toolbar button, but did you know it can also generate manufacturer-tailored files for you? Or that you can run it from commandline? Or that it can even help you generate board images, either SVG, or exported 3D viewer screenshots?

I first realized that KiKit could be used for integration when I stumbled upon a tweet showing how the epdiy project makes its KiCad outputs accessible on an autogenerated webpage – generating gerber files, and even exporting the STEP model. This looked ideal, and I started looking into what’s up. I’ve found great things, and horrible things, let’s start with the great ones.

This is how simple it is to generate things automatically for your repository – it’s a ready-to-go GitHub workflow. You can likely get the relevant workflow files from this repo into your repo right now and have nice exports automatically generated with every commit within an hour’s time. Gerbers are wonderful, so are PDFs and STEPs, but in particular, again, I’m interested in images – those must be present, and they’re the most pain to regenerate.

Pcbdraw

There are two ways to generate images, both of them are through a Pcbdraw tool written by KiKit’s creator. One of them is more diagram-ish but requires some effort on your part, and another way creates a perfect 3D viewer render jpeg but requires a blood sacrifice. Let’s start with the first one, the pcbdraw plot method.

This rendering method creates an SVG file for your board, complete with silkscreen, traces and pads – way nicer than digitizing a 3D model from kicad_cli output. However, any components you might expect, will be missing – you need to have SVGs for your components too, they won’t just be present. There are SVG libraries, but in general, expect yourself to have to work in Inkscape if you want the diagram to look anything like the most bare board you get from the factory.

However, I have to say that you must not sway from the path of light and you really should consider investing effort into pcbdraw plot generation. For one, it’s very nice – SVGs are low-footprint, they’re easy to embed, render, modify and convert. The pcbdraw plot even has a command to generate an assembly manual for you, how cool is that? And surely, you could also add pinout diagram nice arrows to it with a bit of SVG modification?

The most important thing, however, is that your other option is pcbdraw render, and it’s not quite easy. It’s the one that creates 3D viewer 1:1 images, and given that kicad_cli has no such export option, you might guess that this involves black magic – your main hint being that the images take anywhere from 30 to 150 seconds to generate.

There’s no good way to say this – pcbdraw render opens the KiCad PCB editor in a virtual display window, analyzes open window headers to figure out whether the PCB Editor has loaded the PCB yet, blindly sends keyboard/mouse movements with xdotool, then exports the picture of the 3D viewer window, cropped used Pillow magic.

If you encounter a problem, I hope you are of strong enough spirit to debug it. For me, this is the only viable way, because my repository has about 200 boards and counting, and sitting in front of Inkscape is time I don’t have.

Me and my friend, who is a Docker witch, are currently hacking at creating a monorepo-viable integration for generating PCB output files, and we hope to release it soon – whenever we do, you too will be able to push all your boards into a single repository and have pretty pictures magically appear in your READMEs.

In the meantime, I hope that this summary and the integration and script links can help you in your own board publishing. You now know what it takes to auto-generate a board image or a Gerber .zip each time you make a commit into your repository, and now is possibly the best time to take a look at making your PCB repository more approachable.