5. Setup - zykrah/pcb-guide GitHub Wiki

UPDATE: I WILL CONTINUE THIS GUIDE HERE. THIS GUIDE MAY NOW BE OUTDATED.

This section will mostly be a repeat of the first few sections of Ai03’s/Masterzen's guides, just with updated KiCad and different libraries.

Download KiCad 6.0.1 (the latest stable version as of writing). The installer file is about 1 GB (make sure you aren’t installing a lite version), and KiCad itself takes about 6 GB of storage.

Also download GitHub Desktop. We’ll be using it to set up a git repository which is useful for tracking version history.

Git is a powerful tool for software related projects, so learning to use it correctly is definitely something I would advise if you tackle these sorts of projects often.

NOTE: If you want to learn more about Git/GitHub, I recommend the following video: Git Tutorial for Beginners - Git & GitHub Fundamentals In Depth. The written guide by w3schools is also useful.

If you’re familiar with Git/GitHub, feel free to set up a repo however you’d like.

Create an account on GitHub if you haven't already.

Now run the installer for GitHub Desktop.

Once GitHub Desktop opens, log in and create a new repository (File > New repository…):

Give your repository a name and description (I recommend a name in lowercase separated by dashes). For the path, you can choose whatever you like. It will create a folder in the path that you choose with your repository name (in this case C:/Users/.../Keyboards/pcb-guide).

Once it is set up, publish the repository as below:

If you want, you can untick Keep this code private:

If you go to where you created your git repo, you should see the following files:

Note: if you can’t see the .git folder or the extension names (e.g. .md), you should check the following boxes in File Explorer:

If you go to your repo on the GitHub website, it should look something like this:

Feel free to adjust it how you would like, by modifying the README.md or otherwise. For the purposes of this guide, I won’t be bothering.

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. WIP: add example here

Run the installer for KiCad and go through the install process.

Make sure these options are enabled when installing:

Now open KiCad. It should look like this:

Create a new project (File > New Project...):

Save the project file in the repository folder created earlier. Make sure to uncheck Create a new folder for the project. Name the project whatever you want, but generally it’s easiest to just name it the same thing as the repository:

Just press Yes if you see this pop-up:

Now, you should commit to the git repository. Here's how you commit in GitHub Desktop:

Note how it shows the changes made on the left. You should commit after every important change, in case you ever need to revert.

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.

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)

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:

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:

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 = untested

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

This will install the marbastlib with the included untested footprints (in case you need them).

I also recommend installing the MX_Alps_Hybrid library for the MX symbols it comes with. EDIT: marbastlib actually contains switch symbols now so technically this library is no longer necessary.

To install, git bash into your project folder and just run git submodule add https://github.com/ai03-2725/MX_Alps_Hybrid. We don't need to switch to a different branch for this library so no editing of files/extra commands are necessary.

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

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

'Pushing to origin' will sync your changes with the remote github repository.

Once you are done installing submodules, I recommend once again committing, then pushing to origin:

At this stage, your project folder should look something like this:

Next -> (WIP)