Step 4: Installing KiCad libraries

A KiCad library generally contains symbols, footprints and/or 3d models for use in KiCad. KiCad comes with many common symbols and footprints in the libraries installed by default (which I recommend using wherever possible), however footprints/symbols for things such as MX switches require a third-party library.

Library options

There are a few popular options for third-party keyboard libaries:

  • Ai03’s MX/Alps lib (recommended)
    • Contains footprints for MX, MX basic hotswap (+ anti-shear hotswap), Alps, Kailh choc, and MX/Alps combo.
    • Has dedicated MX-NoLED and MX-LED symbols
  • Ebastler’s marbastlib (recommended)
    • Contains footprints for MX, MX hotswap (plated holes), choc, LEDs (e.g. WS2812B)
    • Unlike the Ai03 lib, stabs are separate footprints, meaning to add a stabilized key, you combine a 1u footprint and stab footprint of apprpriate size, then align the two in the pcb editor (I’ll be showing how in this guide).
    • Has symbol for stabililzers
    • Has many 3D models
  • Perigoso’s keyswitch lib
    • Contains MX, basic MX hotswap, Alps, choc and MX/Alps switches (footprints only), however stabs are separate.
    • Has some 3D models
  • Keebio’s libs (footprints/symbols)

Installing Marbastlib

I recommend marbastlib. It has a large range of footprints for all types of keyboards, however, note that some of the footprints are untested (they haven’t been put on a production board for physical testing, but should theoretically be correct). We’ll only be using confirmed working footprints in this guide, but if you’re concerned just read over the git repo.

As of recently, marbastlib has also added symbols for switches, so mostly everything (footprints, symbols, etc) needed for keyboards can be found in this library alone.

Now let’s install the marbastlib library as a git submodule. Open the git bash as shown:

image

You can also just open Git Bash from your windows menu (or otherwise) and run the command cd <filepath>. E.g. cd /c/Users/.../Documents/Keyboards/pcb-guide.

This should open a bash terminal:

image

Note: The shortcut to paste in Git Bash is Shift+Insert, if you don’t have insert binded, just right-click and press paste.

From here, just type git submodule add https://github.com/ebastler/marbastlib.

Then open the .gitmodules file and edit it as following:

[submodule "marbastlib"]
    path = marbastlib
    url = https://github.com/ebastler/marbastlib
    branch = v6-untested

Then run git submodule update --init --remote.

This will add the marbastlib submodule with the included untested footprints (in case you need them) to your git repo.

Adding Footprint libs to the KiCad PCB Editor

Now open your pcb editor in your KiCad project:

image

Go to Preferences > Manage Footprint Libraries... and add the footprint libaries as follows:

image

image

image

The libraries should be added. Click Ok.

Adding Symbol libs to the KiCad Schematic Editor

Now open your schematic editor:

image

Go to Preferences > Manage Symbol Libraries... and add the symbol libaries as follows:

image image image

The libraries should be added. Click Ok.

That should succesfully install the marbastlib librar(ies) into your KiCad project.

Installing other libaries

To install, git bash into your project folder and just run git submodule add <url>.

Then follow the same instructions in KiCad as was done for marbastlib above.

Tips Regarding submodules/kicad libaries

If you need to update your submodules, run git submodule update --remote.

If you need to remove a submodule, see this link.

Gitignore

You can also add a .gitignore file. Read about what a gitignore file does here. Kicad generates certain folders/files that you don’t really want in your public remote git repository.

Example of a .gitignore I usually use:

*-backups/
_autosave-*
*.kicad_sch-bak
*.kicad_pcb-bak
#auto_saved_files#
\#auto_saved_files\#

Continue to Step 4.5:
Syncing Changes