Publishing your boards on GitHub or GitLab is a must, and leads to wonderful outcomes in the hacker world. On their own, however, your board files might have the repo look a bit barren; having a picture or two in the README is the best. Making them yourself takes time – what if you could have it happen automatically? Enter kicad-render, a GitHub and GitLab integration for rendering your KiCad projects by [linalinn].
This integration makes your board pictures, top and bottom view, generated on every push into the repo – just embed two image links into your README.md. This integration is made possible thanks to the new option in KiCad 8’s kicad-cli – board image generation, and [linalinn]’s code makes KiCad run on GitHub/GitLab servers.
For even more bling, you can enable an option to generate a GIF that rotates your board, in the style of that one [arturo182] demo – in fact, this integration’s GIF code was borrowed from that script! Got a repository with many boards in one? There’s an option you could make work for yourself, too.
All you need to do is to follow a couple of simple steps; [linalinn] has documented both the GitHub and GitLab integration. We’ve recently talked about KiCad integrations in more detail, if you’re wondering what else your repository could be doing!
But before you can show a project, you have to find it…
The “KiCad Project Explorer” is a little search engine to find KiCad projects (and more)
https://forum.kicad.info/t/kicad-project-explorer/44440
https://devbisme.github.io/RepoRecon/?topic=kicad&filter=&sort=pushed:desc
Sadly, no, KiCad 8’s kicad-cli does not support rendering, this feature was only recently merged, so you either have to use 8.99 or wait until 9.0 releases next year.
I recently did something similar, although in my case the schematics and PCB visualizations, in both 2D and 3D, are interactively usable in the browser.
I just wrote about it here on my blog: https://www.xythobuz.de/2024_05_05_auto_project_docs.html
When I see Github “Marketplace” and “Actions” I immediately see my account suspended and emails demanding money.
“If you want to use GitHub Actions beyond the storage or minutes included in your account, you will be billed for additional usage.”
I dont see a way of blocking charges beyond free tier, ergo wont touch it.
You don’t need more than free tier for this integration – I have it running for a 150-board repo and it’s fine.
Things like this are always fine until they are not, aka AWS bill shock :(
I rather not risk it in the first place if there is no way of blocking potential costs.
Ill live with manually taking two crappy screenshots (https://github.com/raszpl/FIC-486-GAC-2-Cache-Module), I need to crop and resize anyway :)
It can definitely make more sense in large multi developer projects with multiple people pushing changes, but for a single hacker project why rely on github action instead of running render-pcb.sh locally as part of your git push script?
With all due respect, you are missing the part where you don’t even have to link a credit card to use either GitHub or GitLab Actions, and you don’t have to choose the non-free tiers either. If you’re on a free tier and you somehow exceed the runtime, you can upgrade, but you don’t have to. This is the kind of thing you can set up and then have Just Work, without local generation and resulting “new images” binary (jpg) commits, uncluttering your git history a fair bit – that’s a big part of what makes Actions-driven generation so valuable.
You are most likely right and Im just overthinking this based on my past (very bad) experience with AWS. After all they do state:
“GitHub Actions usage is free for public repositories”
Yeah I get the AWS shock, I have read dozens upon dozens of horror stories. That said, it’s not every company that does this, and GitHub/GitLab aren’t pushing you into it, as far as I’m aware. Also, didn’t even know about “free for public” part, thought it was the same limits for everyone – that’s nice!
soo just tried it, and … its not zoomed in, half the image is empty background, so in the end resulting images need to be manually cropped anyway :(
oh weh! Interesting, don’t recall that on my own PCBs… got any silkscreen outside of the board area or such? kicad_cli is a bit automagic in this way.
Zooming issue is an old one https://gitlab.com/kicad/code/kicad/-/issues/6144 bug was marked as fixed with no fix :(
gitlab wants my phone to register so not gonna bother contributing.
Transparency also doesnt work https://gitlab.com/kicad/code/kicad/-/issues/17865
I don’t know about having github generate. Hopefully this doesn’t strain the resources. Would be nice to keep it a simple free service. Maybe let it generate on your side. Sounds small, until it ballons.
It very much doesn’t strain the resources – the runtime is negligible! Also, yes, you can run this code locally, as it is with any action. The benefit here is that you don’t have to do .jpg (binary) file commit into your repo, and you can’t just forget to regenerate it or get tired of it, either.
I’d be thrilled if board repos had .pdfs of schematics and board layouts, instead of just project files from whatever editor created them.
In my experience, the main problems with doing that are a) having to regenerate them after every commit, which takes time and you can easily forget about, and b) them being essentially binary files, which starts to bloat your repo real quick. I’d guess, these are the reasons why you won’t see most people storing them.
Sure, then SVG instead of PDF to avoid binaries.
Some common graphical format to make the content accessible, to avoid the necessity of installing every EDA tool just to peek at their project files.
If generation were automatable, like this article emphasizes, that’s even better.
only really applies to schematics, even then kinda – because svgs are large enough and non-reproducible enough (ala reproducible builds), you might as well consider them a binary file. also, doesn’t fix the gerber problem =( Having these generated and stored at the point of viewing, as opposed to the repo itself, seems to be ideal to me.
linalinn kicad-render render-pcb.sh generates same file one gets when entering Kicad 3D Viewer. There is no control over Layers (turning off SMD Models), Raytracing, Zoom (broken default zoom-to-fit https://gitlab.com/kicad/code/kicad/-/issues/6144 means 2/3 empty space) :( First two are not supported by kicad-cli so pass on that, but Zoom is. I tried to sneak zoom parameter inside pcb filename option “pcb_file: sram.kicad_pcb –zoom 2” but that didnt work, its not 2005 anymore :)
It takes Github ~_2 minutes_ to render two measly screenshots, but surprisingly its not due to spinning huge heavy VM every time. Its much worse. Over 1 minute is spend in :
“Pull down action image ‘ghcr.io/linalinn/kicad-render:nightly-2024-04-09-14-29’
/usr/bin/docker pull ghcr.io/linalinn/kicad-render:nightly-2024-04-09-14-29
nightly-2024-04-09-14-29: Pulling from linalinn/kicad-render
….
bf4dc1c06610: Verifying Checksum
bf4dc1c06610: Download complete
4f4fb700ef54: Verifying Checksum
4f4fb700ef54: Download complete
b854ba985a25: Verifying Checksum
b854ba985a25: Download complete
Status: Downloaded newer image for ghcr.io/linalinn/kicad-render:nightly-2024-04-09-14-29”
Yes, Github is pulling that huge heavy VM from linalinn repo every time Action is triggered. Its downloading and verifying same 2024-04-09 one month old build every time :o This is what corporate users are paying for, and this is what I was afraid of being charged for in my first comment. AWS bill shock due to Cloud being a fat joke :) You arent paying for actual Action, you are paying for inefficiencies and traps inherent in the system.
All in all trying this made me hate cloud even more :)
I downloaded kicad-nightly-8.99.0.984 to play with kicad-cli ‘pcb render’ locally. Its very new and immature :( Kicad blog suggests it was added just two months ago March 8. Cant even control layers right now (turn off SMD Models) :( Definitely not a substitute for manually exporting images from 3D Viewer precisely the way I like them (zoom, opengl, no smd components).
That’s just how any action works – you have a Docker container with the environment set up for your work, and you run a pre-prepared script in that; this is not even going from linalinn repo, it’s going from ghcr.io, which is a general place you can publish your Docker images, so idk why it’s not cached. It’s up to GitHub/GitLab to cache them, is my understanding! But yeah, it does make for an inefficiency for sure. Also yeah, kicad_cli pcb render is new and not fully mature – it’s up for us to file bug reports/feature requests or contribute for anything that’s missing, I gather. That said, it’s the fastest way to render PCBs as-seen-in-KiCad, way faster than the pcbdraw method I’ve featured!
I send linalinn patch adding controllable Zoom few days ago. I would do the same for controlling layers (turn off SMD Models) in kicad_cli, but gitlab wants my phone number (hilarious) to register :(
yeah it’s a weird thing, I’ve registered some time ago and no question like that, but a friend of mine did get it recently!
btw, took a look at your changes, seems like there’s a copy-paste typo; also, does the changed script still work without the zoom parameter added?
“background” is optional and I copied that so I guess yes. It has some cleverness buildin for sure to reject my attempts at sneaking zoom inside filename. But Im not going to learn about building docker images for github actions just to check :-) Im sure linalinn will figure out how to fix it.
ah you can run the script you’re editing in bash as you normally would; the action .yaml looked fine to me!