Keyboard PCB design with ergogen and kbplacer

Let’s create KiCad project using ergogen and kbplacer. Although ergogen is capable of generating KiCad PCB files, I will be using it only to create key matrix layout. This will result in more traditional KiCad project structure including schematic.

Footprints placement and some initial routing will be handled by kbplacer.

Get ergogen points file

Ergogen configuration is beyond the scope of this tutorial, for simplicity I will be using web-based deployment at ergogen.cache.works.

To learn how this ergogen’s layout description format works see ergogen docs. For demonstration purposes I selected Absolem (simplified) preset to which I added rows and columns nets. This is not required but it will save me some work in next step. Details about matrix annotations can be found in flatfootfox guide.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

 points:
   zones:
     matrix:
       anchor:
         rotate: 5
       columns:
         pinky:
+          key.column_net: C0
         ring:
           key.splay: -5
           key.origin: [-12, -19]
           key.stagger: 12
+          key.column_net: C1
         middle:
           key.stagger: 5
+          key.column_net: C2
         index:
           key.stagger: -6
+          key.column_net: C3
         inner:
           key.stagger: -2
+          key.column_net: C4
       rows:
         bottom:
+          row_net: R2
+          mirror.row_net: R6
         home:
+          row_net: R1
+          mirror.row_net: R5
         top:
+          row_net: R0
+          mirror.row_net: R4
     thumbfan:
       anchor:
         ref: matrix_inner_bottom
         shift: [-7, -19]
       columns:
         near:
+          key.column_net: C2
         home:
           key.spread: 21.25
           key.splay: -28
           key.origin: [-11.75, -9]
+          key.column_net: C3
         far:
           key.spread: 21.25
           key.splay: -28
           key.origin: [-9.5, -9]
+          key.column_net: C4
       rows:
         thumb:
+          row_net: R3
+          mirror.row_net: R7
   rotate: -20
   mirror:
     ref: matrix_pinky_home
     distance: 223.7529778

Now I can run Generate and download points.yml file which will be used by kbplacer.

Convert ergogen points to KLE layout

From now on, I will be using kbplacer which is python package using KiCad’s python API. For installation options see installation guide.

First I will install it in virtual environment in newly created project directory:

1
2
3
4

mkdir absolem-kbplacer && cd absolem-kbplacer
python -m venv --system-site-packages .env
. .env/bin/activate
pip install kbplacer

On Windows use python distributed with KiCad, otherwise kbplacer will not have access to KiCad’s bindings.

Now, to convert ergogen points file to KLE layout run:

1
2

python -m kbplacer.kle_serial -in points.yaml -inform ERGOGEN_INTERNAL \
  -outform KLE_RAW -out absolem-kle.json

The resulting file can be imported by keyboard-layout-editor:

Generate KiCad schematic

To generate KiCad schematic I will use example kbplacer tool which currently is not a part of the package itself. It is just a single script with one dependency so it should be easy to run. Within previously initialized python virtual environment run:

1
2

wget https://raw.githubusercontent.com/adamws/kicad-kbplacer/master/tools/layout2schematic.py
pip install kicad-skip==0.2.5

To generate new schematic file run:

1

 python layout2schematic.py -in absolem-kle.json -out absolem.kicad_sch

The result should be as following:

Generation of MCU circuit is not automatic. It can be added later, for this tutorial I skip it entirely. Remember to assign footprints to symbols. To do it in bulk use Tools->Asign Footprints....

Then create PCB and import changes from schematic.

In order to place and route imported footprints, use kbplacer again. For details how to use it from CLI see python -m kbplacer --help output.

In order to use it with GUI from KiCad, install it as kicad plugin. Plugin icon will appear on the toolbar. Start it to see something like this:

In this instance I’m using previously generated layout file with Relative position diode option and automatic routing enabled. This way the plugin will replicate my first switch-diode pair connection for remaining switches. See options overview to learn more.

After clicking OK I got following result:

And that is all. The process requires some manual steps (i.e. assigning footprints, importing schematic to PCB) but it can be fully automated (see this).