pcbnew scripting doesn’t require the GUI

If you just want to process something in the pcbnew data model, you don’t have to bring up the GUI. You can just start a python job directly from the commandline. 1

Why would you do this?

In my previous life working for a large semiconductor company, we had many, many quality checks and progress trackers. Now that experience was in VLSI, but surely there are parallels in the PCB world.

Management needs a way to track the progress of the project. Engineering needs a way to enforce layout standards. An obvious example of this is design rule checking. How many opens, shorts and spacing violations are there currently? There are many other things that one could check. Maybe you have rules about the clock network. Maybe you want to check that the power grid is strong enough to handle the current its being asked to carry. Maybe the sub-design you’re working on has some restrictions on it to ensure it’ll fit into the larger design.

At the beginning of a project, we had many millions of such violations. For a while the number wouldn’t change since we were still deciding on the bigger picture stuff. Eventually, we’d change gears and want to move towards tapeout.

Of course, these quality checks don’t run in a GUI 2. You want something that can be run from the command line every night in some automated fashion.

Coming back to Kicad, there’s already such a check in the scripts directory: ddr3_length_match.py.3

From the script’s header:

Report any length problems pertaining to a SDRAM DDR3 T topology using 4 memory chips: a T into 2 Ts routing strategy from the CPU.

Once you have kicad installed, pcbnew’s python library is available to any python script. 4

python
>>> import pcbnew
>>> print pcbnew.__file__
/usr/lib/python2.7/dist-packages/pcbnew.py
>>> import sys
>>> print sys.path
['', '/usr/lib/python2.7', <a bunch of others deleted>]

What if you compiled kicad yourself?

python
>>> import sys
>>> sys.path.insert(0, "<path to your build>/kicad/install/lib/python2.7/dist-packages")
>>> import pcbnew
>>> print pcbnew.__file__
<path to your build>/kicad/install/lib/python2.7/dist-packages/pcbnew.pyc

In the case of ddr3_length_match, it simply keeps its eye on a file5. Once a second, it looks at the time stamp of the file. If it’s been updated, the script will load it and run the required checks.

Here’s the relevant code for loading the file:

pcb = pcbnew.LoadBoard(filename)
pcb.BuildListOfNets() # required so 'pcb' contains valid netclass data

There are some other interesting APIs used in there as well. For example, to see if two pads are connected only with wires and vias:

try:
  tracks = pcb.TracksInNetBetweenPoints(start_pad.GetPosition(), end_pad.GetPosition(), netcode)
except IOError as ioe:
  return False
return True

Either way, the biggest point I’m trying to make is that when working on a design, there may be some stuff you want to keep an eye on. Timing critical nets, noise safeguards, power rail loading…

Write a script that loads your design and does the checks. Maybe it continually monitors your saves, maybe you have a checkin trigger 6, nightly, or maybe you just run it by hand.


  1. Another popular method is to parse the kicad files directly, bypassing kicad. While that works, part of the point of this blog is to reduce the need for that.

  2. well, maybe they could, but not for tracking purposes

  3. this script was written by and brought to my attention by Dick Hollenbeck. He was also instrumental in making pcbnew’s python interface as useful as it is. He added a bunch of the APIs without which scripting is kinda limited

  4. my experience is limited to linux. I imagine things will be similar for Mac users. Windows always seems to be a mystery.

  5. The file name is an argument to the script

  6. in SVN or GIT, for example

2 thoughts on “pcbnew scripting doesn’t require the GUI”

  1. Very useful site – thanks. I use PyCharm for outside the GUI development – it allows me to configure which interpreter I can use on a per-project basis. I have 4 flavours on my PC – I prefer 3.x for non-KiCad stuff.
    PyCharm can be pointed at python.exe in the c:\Program Files\KiCad\bin folder on a Windows system.

Leave a Reply

Your email address will not be published. Required fields are marked *