KiCad plugin for mechanical keyboard design. It features automatic key placement based on popular layout descriptions from keyboard-layout-editor and ergogen.

Table of Contents

• Motivation
• Features
• Installation
  • As KiCad plugin
  • As python package
• Use from KiCad
  • Options overview
  • Diode placement and routing
  • Additional elements placement
  • Track templating
  • Run without layout
• Use from CLI or from another tools
  • Run as a script
  • Use in python projects
• Demo keyboard project
• Troubleshooting
  • Plugin does not load
  • Plugin misbehaves or crashes

All PCB's for mechanical keyboards shares common properties which creates great opportunity for scripting. Although this project does not aim to provide complete automatic PCB generation tool it speeds up development process by reducing tedious element placement and routing tasks.

• Automatic keys and diodes placement
• Key rotation support
• Basic track routing
• User selectable diode position in relation to key position
• Configurable additional elements placement

Some examples can be found in examples directory.

To install release version of this plugin, use KiCad's Plugin and Content Manager and select Keyboard footprints placer from official plugin repository.

To install development version, see how to use custom plugin repository. Custom repository is automatically updated with latest master branch builds and it is available here.

For development activities, it is recommended to checkout this repository and copy (or link) content of kbplacer directory to one of the KiCad's plugin search paths. For more details see this guide.

After installation, plugin can be started by clicking plugin icon on the toolbar:

or selecting it from Tools -> External Plugins menu. For more details about plugin usage see Use from KiCad section.

The kbplacer can be installed with pip:

pip install kbplacer

When installed this way, it can't be launched from KiCad as KiCad plugin. This option exist for usage via command line interface or for integrating with another tools.

Command line interface provides more options but generally it is recommended for more advanced users. For example it allows to create PCBs without schematic, which is non-typical KiCad workflow. For details see Use from CLI or from another tools section.

This is traditional way of using this tool. Before it can be used on kicad_pcb project file, user needs to create it and populate with footprints. In typical KiCad workflow this is started by creating schematic. When PCB file is ready, user can start kbplacer plugin in GUI mode from KiCad and run it with selected options. To use this tool in this way, it needs to be installed following plugin installation guide.

• Create switch matrix schematic which meets following requirements:

  • Each switch has dedicated diode with same annotation number
  • Symbols are ordered by Y position
  • Diodes are column-to-row configuration (COL = Anode, ROW = Cathode)

  

  [!NOTE] Other matrix configurations are also supported. Track router will attempt to connect closest (to each other) pads of switch and diode as long as both have same netname, i.e. are connected on the schematic

• Create new PCB and load netlist

• Obtain json layout file from keyboard-layout-editor or convert ergogen points file to json

  keyboard-layout-editor details

  

  Plugin supports internal kle-serial layout files and via files. Detection of layout format will be done automatically. Conversion between layout downloaded from keyboard-layout-editor and its internal form can be done with https://adamws.github.io/kle-serial or keyboard-tools.xyz/kle-converter

  [!NOTE] When using via layouts, switch matrix must be annotated according to via rules. If layout supports multiple layout of keys only the default one will be used by kicad-kbplacer.

  ergogen details

  • open your design in https://ergogen.cache.works/ and download points.yaml

    

  • convert yaml to json (this operation is not integrated with kicad-kbplacer source because it would require installation of third-party pyyaml package and there is no good way to manage plugin dependencies yet)

    • you can use online converter, for example https://jsonformatter.org/yaml-to-json

  • converted file should be automatically recognized in next steps

• Run kicad-kbplacer plugin

• Select json layout file and plugin options and click OK.

  

It is possible to run this plugin from command line. Everything which can be done via GUI can be also achieved using command line. Execute following command (in the directory where plugin is installed) to get more details:

python -m com_github_adamws_kicad-kbplacer --help

By default diodes are placed like shown below. This placement may not work for all switch and diode footprints combinations.

Before	After

To use custom diode position there are two available options. Either select Custom in Position dropdown and define X/Y offset, Orientation and Front or Back side:

or manually place D1 diode to desired position in relation to first switch and run plugin with Relative Position option selected.

Remaining switch-diode pairs will be placed same as the first one. To save current template, set Save to path. This can be later re-used with Preset Position option.

Before	After

Some custom diodes positions may be to difficult for router algorithm. In the above example it managed to connect diodes to switches but failed to connect diodes together.

Switch-to-diode routing is not done with proper auto-routing algorithm and it is very limited. It attempts to create track in the shortest way (using 45° angles) and doesn't look for other options if there is a collision, leaving elements unconnected.

If first switch-diode pair is routed before plugin execution, as shown below, kicad-kbplacer instead of using it's built in routing algorithm, will copy user's track. This allow to circumvent plugin's router limitations. This is applicable only for Relative Position option. When Save to path defined, tracks will be stored in template. Then it can be re-used when using Preset Position option.

Before	After

Below example shows more complicated custom diode position with track template pre-routed by the user. Manual work needs to be done only for first switch-diode pair, plugin will replicate layout for the remaining pairs:

In case additional elements need to be automatically placed next to corresponding switches (for example stabilizer footprints if not integral part of switch footprint, or RGB LEDs), define entries in Additional elements settings section. It behaves very similarly to switch diodes options with few exceptions:

• there is no default position defined
• there is no track routing

Creating tracks or placing switch associated elements (like diodes) does not require layout file. With empty Keyboard layout file field, switch placement is simply skipped. Placing and routing of other elements will use already placed switches as reference points and won't move them. This might be useful for PCB files generated by other tools, for example ergogen.

This works with custom diode positions and track templating.

The kbplacer module might be executed as a script using python's -m command line option.

python -m kbplacer

This is command line equivalent of running this tool as KiCad plugin but without GUI interface. Run it with --help option to get more details about options and CLI usage.

Some kbplacer functionality might be reused in another projects. For example, to parse raw KLE data to it's internal form run:

from kbplacer.kle_serial import parse_kle
keyboard = parse_kle([["", ""]])
print(f"This keyboard has only {len(keyboard.keys)} keys")

It can also create and manipulate kicad_pcb files. This enables non traditional KiCad workflows where schematic preparation can be completely skipped. For example see keyboard-pcbs repository. It demonstrates how to create .kicad_pcb file with switch matrix from scratch.

This package is also key component of keyboard-tools project.

For example keyboard project see demo directory. This project contains 4x4 switch matrix with layout json files in raw (kle.json) and internal (kle_internal.json) formats. It requires keyswitch-kicad-library to be installed. Use this project to validate plugin installation.

If plugin does not appear on the Tools -> External Plugins menu and its icon is missing on toolbar, launch python scripting console Tools -> Scripting Console and type:

import pcbnew; pcbnew.GetWizardsBackTrace()

This should return backtrace with an information about the fault. Include this information in bug report.

• Read stacktrace in error pop-up
• See kbplacer.log file, created in PCB directory

For bug reports please use this template.