Mark down your BOM

KiCad’s pretty powerful and it’s my EDA of choice, but there are weaknesses. One of them is bill of materials (BOM) export. In KiCad’s schematic editor, Eeschema, you can click on the BOM icon

and up comes a window

where you can select one of several BOM plugins and click the “Generate” button, and it’ll generate a BOM for you. Except as you can see the plugin names are pretty cryptic. The description’s a little better sometimes, but for many plugins the description’s blank. And to my mind, most of the options are pretty awful.

Most of them give you an HTML or CSV file. A CSV you can import into a spreadsheet, which can be useful, but isn’t particularly readable at least without some massaging. There’s one plugin that’s billed as creating a text file but it’s really TSV, again only useful for pulling into a spreadsheet. HTML might seem the way to go if you want a readable BOM, but the formatting’s pretty crude:

This is the sort of thing Markdown is good for. It’ll generate something more readable than the above HTML, and it’s the big winner for a project shared on GitHub: an HTML file in a GitHub repository doesn’t get displayed in readable form, but Markdown files do:

So I wrote a BOM plugin script to generate a Markdown file. Here it is. It’s a Python script but you don’t need to know Python to use it. Download the file and install it… where? How?

There’s a rather tedious installation procedure. Fortunately you only have to go through it once.

In principle it should go in your plugins folder, but where’s that? Good question; seems to depend on what OS you’re using and other factors. For me, using Linux Mint, it’s ~/.kicad/scripting/plugins. But in fact you can put it anywhere, plugins folder or not, as long as you tell KiCad where it is. Let’s just say it’s in ~/.kicad/scripting/plugins, but modify the following accordingly if you’re using a different location.

Also needed in the same folder is a copy of If it’s not there already, you need to copy it out of the system plugins folder. Which again might be in various places depending on your OS. If you go into the BOM dialog and click on (for instance) bom_html_grouped_by_value, then at the bottom is a command line that on my installation looks like

python "/usr/share/kicad/plugins/" "%I" "%O.html"

That says the system plugin folder is /usr/share/kicad/plugins and there should be a copy of there. (For Windows it might be C:\Program Files\KiCad\bin\scripting\plugins.) Copy it into wherever you’re installing For instance, in terminal (all on one line):

$ cp /usr/share/kicad/plugins/ ~/.kicad/scripting/plugins

Now to tell KiCad where to find this plugin. Look again at that Bill of Materials dialog. There’s a “+” button on the lower left. Click that. Up comes a file selection dialog. Navigate to wherever you put and open it.

(In Linux, .kicad is a hidden directory and you have to use the left click contextual menu in the file selection dialog to “show hidden files” before you can navigate to ~/.kicad/scripting/plugins.)

Eeschema then asks for a plugin nickname. It defaults to bom_group_md but you can change it to whatever you like.

Now the BOM dialog looks like this:

Select bom_group_md on the left. At the bottom, in the box under “Command line”, I suggest changing “%O” to “”.

There. That should be it. Now you can click “Generate” and hopefully it all works:

In your KiCad project’s directory there’s now a file whose name ends with “”. If you look at it in a text editor it looks something like this:

which doesn’t seem very promising. You need a Markdown reader. Look online to see what’s available for your OS. In Linux, I use Okular. It looks like this:

And, as said before, if you put the md file in your project’s GitHub repository, it gets displayed nicely when it’s opened in GitHub.

The next time you want to generate a Markdown BOM, it’s much easier: Just click the BOM icon, select bom_group_md, click “Generate”, and you’re done.

Hope this is useful. I like this script a lot better than any of the ones that ship with KiCad.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s