PCB Design

The circuitry handbook.

PCB Designer Guide

PCB Designer Guide

PCB Guide Part 1 - Preparations

This guide is intended as a direct replacement for the aging Ruiqi Mao's guide.
Credits go to that guide for serving as a base for this writeup.

If you spot any mistakes, please let me know either through Discord (ai03#2725) or email (ai03.public@gmail.com), and I will fix it to the best of my abilities.

ai03's Keyboard PCB Design Guide

So you want to design keyboard PCBs, or to make sure that you are doing things correctly.
We will build a similar 2x2 macropad in this introduction, but will do so in a more future-proof way compared to the other guides.

Step 1. Grab the requirements

We will be using KiCad for making the PCB.

Grab the program here:
As of the time of writing this guide, the latest update is 5.0.2.

Now comes the download and install process. Grab a cup of coffee, for KiCad 5.0.2 is a whopping 1GB. 
Install as you would any other program.

Also, this guide will be using Git/GitHub to manage progress.
If you are new to this, grab GitHub desktop here:
Install, then sign in or create an account as necessary.
Also, make sure to become familiar with GitHub, as it is very useful for open-source projects.

If you already work with git, use whichever implementation you prefer, and replace all mentions of GitHub in this guide with your preferred methods.

Finally, if you would like community support in case you get stuck, I recommend that you join my Discord server:
It is a designer haven, with references, datasheets, and designer chat channels.

Step 2. Repository Preparations

First, let's create a git repository for the PCB on GitHub
It is always nice to be able to roll things back in case things get out of hand.
Also, it is a simple and reliable way of sharing your work to the world.

Select File -> New repository,

Then create a repository.

Some of the important options:

This will create a blank repository to begin work in.

Publish the repository,

Using whatever settings you prefer.
Uncheck "Keep this code private" if you want to have the data public and open-source to begin with.

Repository preparations are done.
Now, it's time for initializing the KiCad project.

PCB Designer Guide

PCB Guide Part 2 - Beginning the project

By this point, you should have a repository readied for the project.

Step 3. Creating the KiCad project

The previous page's setup should have created a folder in your home/Documents/GitHub folder with the project name.

 We will be doing all work here.

Launch KiCad, and you will be greeted with the main menu.

From the options, select New Project.

Browse to your repository directory.
Make sure to uncheck "Create a new directory for the project". Otherwise, you will have your project in a useless subdirectory.

KiCad will generate the basic project files.

The default project only has two files:

The basic workflow is to create the schematic first so that the electric side is all set, then to lay it out on a physical PCB based on that.


At this point, let's commit our changes.
Give the commit a name, commit, and push the changes.

This guide will occasionally remind you to commit after large milestones; however, it is recommended to do so often. Losing work is not an enjoyable experience.

Step 4. Add local libraries

KiCad is built around libraries - A collection of footprints, and often schematic components bundled with it.
Footprints are the building blocks of PCBs - The sets of copper pads that the components attach to.

KiCad ships by default with support for common electrical components, such as resistors, capacitors, microcontrollers, etc.

It does not ship with exotic things, such as Cherry MX footprints, very specific USB connectors, etc.

Let's take care of that.

KiCad supports two library install types:

We will be using project-specific libraries.

First, we will need to pick which footprint libraries to use.
In this guide, I will be making use of the following repositories:

We will be adding these to our project as Git Submodules - This allows us to pull new changes from them without having to manually download and overwrite the existing files.

Since the GitHub desktop application is fairly awful at managing submodules, we will opt for using the shell instead.

First, navigate to your repository folder, right click in an empty area, and bring up the git shell.

Then, run the following command:
git submodule add URL-OF-REPO

In this case, I will add the two repositories linked earlier.

The GitHub desktop GUI seems to have issues with committing submodules, so let's do it from the command line:

git add *
git commit -m "Add submodules"
git push

The commands adds the new submodules to the commit, creates a commit with the given name, and pushes it to GitHub.

After the push finishes, you can see that the library repositories are linked in your GitHub repository.

Now that the files are there, let's add them to the project.

First, open up your schematic file,

Select Preferences -> Manage Symbol Libraries,

Select the Project Specific Libraries tab, select Browse Libraries,

And select the .lib files in each of the added libraries.

After checking that both are added, confirm the changes by pressing OK.


Close the schematic editor for now. 

Open the PCB file,

Go to Preferences -> Manage Footprint Libraries, switch to Project Specific Libraries, and browse for the added .pretty folders.

Again, click OK to confirm changes, then close the PCB editor.


Commit these changes, and push the commit.
If both the fp- and sym-lib-table files are not showing up, make sure you hit OK when adding the libraries rather than simply closing the dialog.


Now you're all prepared for making your first keyboard!
Time to begin the schematic.

PCB Designer Guide

PCB Guide Part 3 - Creating the MCU schematic

By this point, you should have installed the programs, created the repository, and added the local libraries.

Step 5. Beginning the schematic

The schematic is used to set up the electronics side of things.

For this tutorial, we will be using the typical Atmega32u4 microcontroller, and building a 2x2 macropad with MX and Alps support.

Open up the schematic editor to begin.

One modification used during this guide is seting the grid size to half the default size. 
This allows a bit finer grain control for wiring things.
From Preferences -> General options, set the grid size to 25.


From Ruiqi Mao's PCB guide, here is a nice commands reference:

m: pick the component up and move it
g: drag the component up and move it while keeping wires attached to it
c: copy the component
e: edit the component
r: rotate the component
y: mirror the component
del: delete the component
esc: abort!

Also, these shortcuts are useful to know:

w - Begin drawing a wire connection
k - Cut a wire and stop drawing it without clicking on an endpoint
Ctrl + h - Place a global net


The microcontroller, or MCU for short, is the brain of the PCB.
It cannot function on its own, so we will build the circuit for it.

First, press A to open the "add symbol" menu, and search for atmega32u4.

Select the atmega32u4-au component.

Place it down in the schematic.

To set it up, we will simply follow two resources:

Usually, both a technical datasheet and an existing implementation will exist for most components.
Search for both, and use both as reference.

To begin, let's tie UVCC, VCC, and AVCC to +5V, as specified by the datasheet.
Hit P to open the power symbols menu, and select the +5V symbol.

Place it above the VCC pins. If you misplace, you can move it by hovering over the component and pressing M.

Now, wire it together using the wire tool (hotkey W).

This binds the physical UVCC/VCC/AVCC pins on the component to the +5V net.
Net refers to a set of pads that should all be connected together.

Similarly, bind the GND and UGND pins to Ground by selecting the GND symbol in the power menu and wiring them together.

Protip: It is good practice to have positive power source symbols pointing up, and ground power symbols pointing down.

Now we will place some components.

The HWB pin requires a pull-down resistor, or a resistor connected to ground.
Open the components menu with A, and search for r_small, or the small resistor component (The large one is massive and will burn space on the schematic):

Now, place this parallel to the pin labeled HWB/PE2. You can rotate the component by pressing R.

Also, place a ground symbol.

Now, wire it together.

Congratulations, now the PE2 pin is connected to ground through the resistor.

Let's change the value of the resistor. Press the E key while hovering over the resistor to edit.
A 10k ohm resistor is fit for this task. Select the value field, and type 10k.

The component's value should now be updated.

The USB pins also need resistors. Repeat the previously described commands to place two 22 ohm resistors, and wire them.

In this case, I drew the wire out on the other side as well, and used the K hotkey to end the wire at those points.

Now, let's place needed capacitors.

Through the add components menu, search for c_small (Again, regular capacitor symbol is massive).

First, place a capacitor with value 1uF beside the UCAP pin, and connect the other end to ground.

Next, we want to set up our decoupling capacitors. These are important capacitors that filter out electrical noise coming from the microcontroller.

The official documentation states to have a 0.1uF by each VCC pin (Which would be 4 on a 32u4), and a 10uF overall. 
However, the Teensy schematic uses only three 0.1uF, and a 1uF overall.

I personally combine them - three 0.1uF and one 10uF. This has been confirmed functional by my testing.
Place them in an empty space close to the microcontroller, and bind one end to +5V, one end to Gnd.

Protip: Build one 0.1uF capacitor, and clone it using C to save time.

Since this PCB will get its power from USB no matter, bind VBUS to +5V.

The crystal controls how fast the controller functions.
Search for the Crystal_GND24_Small component...

...and wire the non-gnd pins (1 and 3) to XTAL1 and XTAL2.

The crystal also needs load capacitors of its own.
Place two 22pF capacitors between each crystal pin and Gnd.
Also, wire the Gnd pins on the crystal to Gnd.

The reset button is pressed to make the MCU enter bootloader mode. This is used to write the firmware to the PCB.
Place a sw_push component between reset and ground.

Also, an external pull-up resistor can prevent the reset pin from being read faultily, and accidentally resetting during use.
For this, a 10k ohm resistor can be placed between reset and +5V.

The AREF pin is ignored since we won't be doing analog readings.

Now let's place global nets on the USB lines - These connect wires together by name, removing the need for ugly wires that cut across the entire schematic.

Hit Ctrl+H, type the names, and place them on the other end of the USB positions.

Local nets also work, but I prefer global nets since they are much more visible.


A view of the completed MCU zone.

Now, it's time to complete the rest.


PCB Designer Guide

PCB Guide Part 4 - The rest of the schematic

By this point, you should have the MCU schematic zone complete.

Step 6. The rest of the schematic

The rest of the schematic is not as difficult as the MCU.
Let's power through it.

USB circuitry

Only typical Mini-B USB will be covered here for simplicity reasons?
Type-C setups will be discussed in future sections.

Search for the molex USB connector in my library, along with polyfuse-small.
The polyfuse prevents your computer from exploding in case of a short circuit.

Connect VBUS -> Polyfuse, then Polyfuse -> +5V. Drop a VCC symbol pre-fuse. Change fuse value to 500mA.

The rest are self-explanatory. The data lines are connected using the global labels we set up earlier:

Switch matrix

Now, let's add the switch matrix.
I will use the MX-1U symbol from my own library.

Combine it with a D_Small (small diode). Ignore the LED pads for now; that will be covered later.
Connect the anode of the diode to the ROW pin of the switch.

Now clone this four times as shown:

Then, drag a wire across the diode cathode and COL pins of each row and column, and terminate them using the hotkey k:

Finally, add global labels for each row and column. It is recommended to label them counting from 0 up, since that is how it is handled firmware side as well.

Note that we will NOT be connecting the rows and columns to the MCU just yet.

Finally, a schematic is complete. 

However, there's one more step before getting to work on the physical PCB.


Step 7. Assigning Footprints

As of now, the electrical setup is complete.
However, KiCad doesn't know how to translate this to physical form.

Let's input the data.

First, click the "Assign PCB footprints to schematic" option, or CvPcb.

It will ask you to annotate the schematic. This is because we left our component names un-numbered, i.e. "R?" rather than "R1, R2, R3..." etc.

For larger boards, you will want to at least manually name each switch.
But for something of this size, let's let KiCad do the tedious work for us.

Simply hit annotate, and KiCad will number each component, then launch CvPcb.

One note is that this takes a very, very long time to start up, especially on a slow internet connection.

A menu like this will open.

The left side is a list of component libraries.
The center is the list of components in the schematic.
The right is a list of component in the library selected in the left.

Components come in all shapes and sizes; however, we will use typical and common sizes suited for keyboards.

For the capacitors, we will use the 0805 footprint.
On the left side, select the Capacitors_SMD library.

Select all the capacitors...

Then double click the 0805 footprint in the right panel to assign the C_0805 footprint to all capacitors.

Likewise, assign:

 ->  for the crystal

Library Footprint Component
Diodes_SMD D_SOD-123 All diodes
Resistors_SMD  R_0805 All resistors
Fuse_Holders_and_Fuses Fuse_SMD1206_Reflow Polyfuse
MX_Alps_Hybrid MX-1U All MX switches
Crystals Crystal_SMD_3225-4pin_3.2x2.5mm Crystal
random-keyboard-parts SKQG-1155865 Reset switch
random-keyboard-parts Molex-0548190589-Assembly USB connector
Housings-QFP TQFP-44_10x10mm_Pitch0.8mm Atmega32u4

Even the 32u4 has to be assigned, even though it has a footprint by default.

Press apply, save schematic, and continue once done, then close the dialog.

Now, click the "generate netlist" button in schematic editor:

Simply click Generate Netlist.

The schematic and assigned footprint data has been exported for the PCB editor.

Commit the changes to GitHub just in case. Time to build the PCB!


PCB Designer Guide

PCB Guide Part 5 - Creating the PCB

Now that the schematic is finished and footprint data has been exported, we can begin with the PCB.

Step 8. Preparing the PCB

From the KiCad menu, open the PCB file.

First, let's adjust the grid so it's fine tuned for making keyboards.

On the left pane, switch the units to mm.

In View -> Grid Settings, set the custom grid size to 0.79375mm (19.05/24). This value is just fine enough for placing diodes, and just rough enough for easily placing switches.

Set the fast switching values to custom and 5mil.
This allows fast grid switching by holding Alt+1 and Alt+2.
5mil is a value well suited for routing.

Test grid switching by holding the key combinations Alt+1 and Alt+2 in PCB editor. You will see the grid switch.

Time to import data from the netlist.
Click the read netlist button. Press read current netlist, then close.

Doing so will barf out all the components onto the PCB.

First, let's position our switches.

Switch to Grid 1.

Click the component MX1, and hit M to move.
Protip: Press M without the cursor over the component to make sure the cursor is locked to the center of the footprint rather than to a pad of the footprint.
Protip 2: Use ctrl+f to select a component if too lazy to find it with your eyes.

Place it down on a blank place on the PCB.

Now, place the rest of the switches so the order matches the schematic, and so the outline overlaps perfectly (This should be easy with grid 1.)

Now, place D1-D4 close to their respective switches.

We will be placing all surface mount components on bottomside. To flip the components between sides, use the F hotkey. To rotate footprints, use R.

Bottom copper will be shown as green if you have not changed the stock settings.

I placed them facing downwards as shown.

Now to position the microcontroller components.
This is easier done in grid 2.

Select the 32u4, and place it to the side of the matrix somewhere.

Place the crystal close to the crystal pins on the MCU.
It should be as close to the MCU as possible, but not so close that nearby pins cannot be broken out.
For the purposes of this example, I will place it a fair distance away.

If you need to see which pins need to be connected, control-click a pad.


Place the load capacitors for the crystal as well.

Place each 0.1uF decoupling capacitor near the VCC/GND pin pairs on the MCU. I left the pins 43-44 pair for the 10uF.
Also, place the rest of the components relatively close to their pins. 

Protip: If you ever want to reposition the MCU, you can drag-select all the MCU components, and move/rotate it as if it were a single object.

Before placing the USB connector, let's draw the edge cutout line. 
This is the line along which the PCB will be cut out.

We will round the corners so people don't injure themselves with sharp corners.
Using grid 1, switch to the edge.cuts layer on the right pane, and select the arc tool.

Click the center of the arc, then the beginning and end points in counterclockwise order.

After drawing the arcs, draw the line segments between them.

If any of the arcs were out of place, they can be moved or redrawn.

Now, place the USB connector along the edge.
Place the USB resistors in parallel below.

Place the remaining components.

Now that the components are placed, we can begin routing.
Note: You can always adjust component positions during routing.

Step 9. Routing

First, we need to adjust some settings.

Switch to inch instead of mm on the left pane, and open Setup -> Design Rules.

By default, all tracks are roughly 10 mil wide.
However, it is always good practice to route power traces thicker whenever possible.

Add a new net class named power, and use the bottom menu to add the power nets to it.

Then, set the track widths for each net class to 10 and 15 mil respectively.

Press OK to confirm changes.

Now, the remainder is connecting all of the pads of the same net.
Use the trace tool (Hotkey X), click one pad to begin, another pad to end.
Clicking empty spaces will create corners.

A few important points when doing so:

Here is a sample routed PCB.

After passing through the polyfuse, the +5V line passes through the 10uF capacitor, which acts as a general decoupler for the entire MCU. After passing through it, the +5V rail flips to the top of the PCB, where it draws a U to feed each VCC pin through its decoupling capacitor.

Step 10. Choosing the matrix pinout

You may notice that the switches are not connected to the MCU at all.
This is because the pins to connect the matrix to are best chosen depending on the circumstance.

For example, it is much more logical to use these pins to the right,

Compared to attempting to desperately use the pins at the top left corner.

First, take a note of the pins you want to use,

and in the schematic editor, place the net labels for the rows and cols on the pins you wish to use.

Export these changes to the netlist,

And read these changes into the PCB.

The connections should appear on the MCU.

Quickly route these as well.

Congratulations! You have built your first keyboard PCB.

If you are not satisfied with the routing, you can go to Edit -> Global Deletions and check Tracks to restart.
Practice routing as many times as possible - It takes experience, not reading a tutorial, to learn the little tricks to route cleanly and efficiently.

Once you are finished, commit to GitHub. Then, it's time to add the final touch.

PCB Designer Guide

PCB Guide Part 6 - Fill zones, decoration and production

Now that the routing is finished, let's tune the PCB up.

Step 11. Ground fills

You may remember the mention about how the crystal zone is sensitive.
We can protect it, along with other components, from external electrical noise through the use of ground fills.

Select create fill zones to begin.

We will draw two zones: One around the MCU, and one for the USB connector.

Then click on the first corner of the zone to surround to bring up a menu.

Select the ground net for the fill net, and high resolution for prettier edges.

Click at the corners, and double click at the last corner to end.
Then, press B to fill the zone.

The ground fill question is always an interesting one.
On one hand, it reduces EMI interference both entering and exiting the board.
However, it adds a significant amount of copper, making it more difficult to solder due to the necessity to raise temperatures further for ground-connected components. 
It also makes the PCB opaque. This can be a major disadvantage if you are wishing for the translucent PCB aesthetic.

I will say two things regarding this topic:

Whether you choose aesthetic or function is up to you. Such is a design decision left for the designer.
My personal recommendation is to use fill around the entire MCU zone or entire board until you are used to PCB design and have a few functional prototypes.

Step 12. Decorations

Let's celebrate your first PCB by making it yours.

The following layers can be used for aesthetic designs:

For example, select the text tool on the layer F.SilkS, and place a block of text on the PCB.
Then, press Alt+3 to render the PCB.

Artwork can be done using Bitmap2Component. This will be discussed in a future chapter.

Step 13. Error Check

Are you sure that you haven't made any mistakes?

Use DRC to find out.

Press "Start DRC", then wait a few moments for KiCad to find things to complain about.

If it returns empty, you're all set.

If not, you've made a mistake.
Double click the error to figure out what's wrong. (It will jump to the error point.)

Repeat until KiCad complains no more.

Step 14. Production

Let's get this board produced and in your hands.
Gerber files are the standard for PCB data. We will export this from KiCad.

Open the Plot menu from the toolbar.

Here are the generic settings I use for exporting to most factories.

Once everything is set, press Plot to generate the data.

Now click Generate Drill Files.
Stock settings should work fine here. Simply generate the files and close all dialogs.

Check your repository folder - You'll notice that there are gerber files in the directory you specified.

Add all these gerber files to a zip file.

Congratulations, you can use this file for production.
Commit a celebratory commit to GitHub so you don't lose your work when KiCad decides to have a bad hair day.

For example, you can upload the zip at JLCPCB, and it will generate a quick screenshot of the PCB data.

Step 15. Ordering parts

Let's finish the guide up by buying all the parts necessary to assemble this board.

Component Quantity Package Sample Part
Ceramic Capacitor, 0.1uF 3 0805 1276-2450-1-ND
Ceramic Capacitor, 10uF 1 0805 1276-6455-1-ND
Ceramic Capacitor, 1uF 1 0805 1276-1066-1-ND
Ceramic Capacitor, 22pF 2 0805 1276-2605-1-ND
Diode, Generic 4 SOD-123 1N4148WTPMSCT-ND
Polyfuse, 500mA hold, 1A trip 1 1206  507-1803-1-ND
Resistor, 10k 2 0805 P10KDACT-ND
Resistor, 22 2 0805 P22ACT-ND
Low Profile Tactile Switch 1 5.2x5.2mm CKN10361CT-ND
ATMEGA32U4 Microcontroller 1 44TQFP 10x10mm ATMEGA32U4-AU-ND
Molex Mini-B USB C Receptacle 1 Molex-0548190589 WM3895CT-ND
Crystal, 16MHz 1 3.2x2.5mm, 4 pad 1253-1698-1-ND‎


The guide will be expanded sooner or later to cover LEDs and such.
For now, you can refer to the advanced info.


Also, feel free to join ai03's Discord server.
It provides a safe place for all to discuss and design.

PCB Designer Guide

Example repo


This repository contains the latest version of the example PCB built following the guide.

Advanced Info

Advanced Info


Produce functional PCBs the first time around.

DRC Checks

Begin here.

  • Run a DRC. Does it report anything?
  • Are there any errors aside from overlapping stabilizer/switch pads?

Physical Checks

These errors are easy to miss, since some are not scanned by DRC.

  • Is the PCB the correct size?
  • Is USB connector placed at its proper location?
  • Are there any components so large that they will interfere with the chassis?
  • Are the keys placed in correct layout?
  • Are there overlapping parts?

Trace Checks

Correct routing is important.

  • Do any traces overlap each other?
  • Do any traces go through holes and/or pads?
  • Do any traces fall off the PCB edge?
  • Are there any pointless disconnected traces?
  • Do any traces go so close to pads that they enter their no-mask zone?
    • This can result in shorted circuits after soldering, even if they pass an unsoldered electrical check.

Component Checks

Will the parts function?

  • Is the pinout of the components correct?
    • Specifically, is the crystal, MCU, and USB connector pinouts correct?
      • Often, on a 4-pad crystal, the crystal pads and gnd pads are placed diagonally from each other.
      • If you have two adjacent same nets or an unconnected pad on crystal, you may have incorrect pinout!
    • Even identical footprint components sometimes have differing pinout.
    • Check the documentation for the parts for their correct pinout.
  • Are you using the correct parts for the task?
  • Are you using the correct footprints?
  • Will the placement of parts cause nearby parts to fail?
    • Heat, EMI, etc.
  • Are decoupling capacitors placed at their correct positions?
    • Near VCC/GND MCU pairs, close to crystal, close to RGB LED, etc.


More eyes is better.

  • Load the gerber in a gerber viewer. Does it render as expected?
  • Let peers error-check your project. Do they find anything suspicious?
  • Does the PCB avoid pitfalls described in this wiki?

Aesthetic Checks

For beauty-oriented PCBs.

Advanced Info

Microcontroller Design

For successful and elegant controller circuitry.

Microcontroller Basics

Controller such as ATMEGA32U4 are often used as low-cost, low-power processing units for mechanical keyboard PCBs.
They often require various components of their own in order to function properly.

Choosing the Correct Controller

Space and function constraints will require different choices of controllers.

ATMEGA Series Pros Cons
  • Small form factor.
  • Powerful enough for most smaller keyboards.
  • Not enough pins for large matrices.
  • Not much lower price than 32u4.
  • No I2C support.
  • 25 I/O pins, slightly larger than 32u2.
  • Enough pins for most keyboard matrices.
  • Slightly increased size, and more required components.
  • Slightly more expensive than 32u2.
  • 40+ I/O pins. Handles the largest matrices just fine.
  • Extremely large size.
  • Very expensive.
  • Same size as 32u4, but requires no crystal.
  • No crystal means less chance of failure.
  • Overall small footprint.
  • Many I/O pins.
  • Two separate I2C busses.
  • Not QMK compatible.
    • Runs fine on Keyplus.
  • Requires 3.3v voltage regulator.

When in doubt, pick 32u2 for sub-60%, 32u4 for 60-80% and splits, and 1286 for 80+% keyboards.
When using 32u2, it is strongly recommended to bind B7 to PWM backlight, since it is the only pin known to work with QMK flawlessly.

Controller Layout - The Basics

  • Place the controller and its components in a position that allows for proper placement and breakout.
  • All decoupling capacitors must be placed as close to VCC/GND pin pairs on the controllers as possible. (Detailed below)
  • Break out other pins with even spacing and pattern in order to minimize wasted space.
  • Try to keep "dirty ground current", such as from RGB LEDs or backlighting, away from the controller. For example, run a separate ground plane for the controller, and join it together with the rest of the ground close to the USB port.

Crystal Layout


  • The crystal is one of the most sensitive parts of the controller circuit.
  • Place the crystal in a well-shielded position away from other traces.
  • Do not run any traces close to, through, or under the crystal area unless absolutely necessary.
  • Crystal and its decoupling capacitors should be fairly close to the controller.
  • Crystal layout should be relatively symmetrical.
  • "Dirty ground current" should never run through the crystal.
  • Do not use vias in crystal traces, since they mess with the fine capacitance requirements.
  • Surround the zone with a ground plane.

Crystal Load Capacitors

Controller Decoupling Capacitors

Placement is important

  • The microcontroller decoupling capacitors exist to prevent the controller from unleashing plenty of noise into the VCC and GND channels.
    • Yes, a whole board can fail if these lines are affected enough.
  • Place each decoupling capacitor as close to its respective VCC/GND pin pair as possible.
  • Feed through the capacitor for them to have effect.

Choosing the right values

  • Consult the official documentation and working prototypes for "correct" quantity and values.
  • Official documentation will usually state 0.1uF per VCC pin and 10uF for UVCC pin.
  • However, most common implementations will skip a 0.1uF to cut costs, and still run perfectly fine (i.e. Teensy 2.0, Teensy++ 2.0).

Regarding placement of the large capacitor

  • Placing the largest decoupling capacitor far from the microcontroller makes it a power reservoir for the entire board.
  • Placing the largest decoupling capacitor close to the microcontroller makes it a power reservoir for mainly the controller.
  • Most sources will say that the largest decoupling capacitor should be placed close to the controller instead of near the USB port.
  • It can be used as an "upstream filtering capacitor" by having all VCC current for the MCU travel across the capacitor pad before branching off to feed other VCC pins through their decoupling capacitors.



Advanced Info

Matrices and Duplex Matrix

Improving upon their design.

Maximizing the matrix

  • For non-macropad keyboards, routing a matrix with one pin per row and column will almost always lead to inefficient results.
  • With the same number of keys, a more "square" matrix will require less cols and rows total than a more "rectangular" one.
    • I.E. For 30 keys, 5x6 is 11 pins, while 2x15 is 17 pins.

The Duplex Matrix

  • Each "column" spans two physical columns.
  • Two "rows" exist for each physical row.
  • See schematic at bottom for a routing example.


  • Fit more keys for rectangular keyboards using less pins
  • More pins to use for fancy features
  • Use cheaper controllers to reduce the final product cost


  • More complicated to wire
  • Can be more difficult to add more keys to the matrix later on
  • Harder to follow on a schematic


Advanced Info

Routing Techniques

Tips for a proper, organized PCB

Good Routing Techniques

  • Do not route traces close to the edge. 
  • Do not place EMI-emitting components, such as crystals, near a board edge.
  • Surround pulsating traces with proper ground plane fill to reduce EMI.

Verticals and Horizontals

  • Use front and back for horizontal and vertical traces respectively, or something similar to avoid clashing.
  • Pick sides which do not force the abuse of vias for routing smd components.
  • Let busses take precedence over singular traces (explained below).

Trace Bus

  • Route many traces going in the same direction together for efficient use of space.
  • This can be used to efficiently break out many traces from the controller.


Advanced Info

Backlighting And RGB

Bling bling.

QMK-Compatible LED backlighting

This is one LED per switch.

The structure is:

.     |- LED --- Resistor -|
      |                    |     N-Channel
5V ---|- LED --- Resistor -|----- MOSFET ----- GND
      |                    |        |
      |- LED --- Resistor -|     PWM PIN
  • Use a N-channel MOSFET.
  • A PWM pin can only deliver around 20mA absolute maximum. Drawing tons of LEDs from a single PWM pin will easily fry your microchip. Place a resistor between the PWM pin and MOSFET gate.
  • All LED-Resistor pairs are placed in parallel.
  • All LEDs can be run under a few or single resistor, but this leads to brightness inconsistencies among the LEDs.
  • The current from the LED-Resistor pairs feed into the drain of the MOSFET.
  • PWM feeds into the gate of the MOSFET with a 100~1k or so resistor, usually.
  • Source of the MOSFET goes to ground.
  • Each LED resistor should be planned to let around 1-5mA through the LEDs each. 20mA will hurt your eyes.

Choosing the correct MOSFET

Power Dissipation

  • Make sure the current flowing through times the voltage drop doesn't lead to a power dissipation that doesn't fry the MOSFET.

Maximum voltage and current

  • Check for Drain-Source voltage/current max ratings.


  • Do not pick a MOSFET which will not fit on your PCB.

RGB Underglow

WS2812B is the standard used for underglow.

  • Draws 45-50mA per package maximum.
    • However, AliExpress GH60 PCBs have 16 WS2812B.
    • Current can be limited via QMK.
  • Can be daisy-chained together. One LED passes data onto the next, and so on.
  • Can be purchased in individual WS2812B or by strips. Use individual for assembled PCBs.
  • Wired in the following way:
    • VDD to 5V
    • VSS to GND
    • DIN to previous LED DOUT, or AVR pin if first LED
    • DOUT to next LED DIN, or unconnected if last LED
    • Placing a 500 ohm resistor between AVR pin and first LED is highly recommended

Various other RGB choices

WS2812 (without B) - Unsimplified version of WS2812B with 6 pins
WS2811 - The controller within WS2812B. Can be used as standalone controller with other RGBs.
Controller-less RGBs - Use with separate PWM LED controllers.
WS2812C - Low current variant
SK6812 - An alternative that also works with QMK

Indicator LEDs


MCU PIN --- LED --- Resistor --- GND     (Source setup - Toggle pin high to turn on)


5V --- LED --- Resistor --- MCU PIN (Sink setup - Toggle pin high to turn off)

LED and resistor can be swapped.

Advanced Info

USB Type-C

Make your keyboard future-proof and reversible

Type-C USB

  • Slightly wider than MicroUSB connectors. Keep in mind when designing PCBs to fit standard cases.
  • Soldering is much more difficult.
    • Mini/Micro-USB has 5 pins.
    • Type-C has 24.
  • Completely surface mount Type-C connectors are impossible to solder by iron.
    • Type-C connectors have two rows of pins, one of which exit from below the connector.
    • If hand-soldering via iron, choose a hybrid connector with through-hole pins for the under-connector row.
  • Type-C connectors often do not extend as far as old Mini-USB connectors do from the edge of a PCB.
  • Often, the legs of a Type-C through-hole connector are extremely short (<1mm). Thick PCBs may be difficult to assemble.

Design Considerations

  • Type-C is physically larger.
  • Type-C requires its own components to function.
  • Some Type-C connectors have legs too short for 1.6mm PCBs.
  • Assembly costs may increase.


This diagram breakouts to a header.

Keyboard use

  • Pull-down the CC lines
  • Use the DP/D+ and DM/D- lines just like any other USB connector
  • Connect VBUS and GND like any other USB connector
  • It is inferred that the pull-downed CC lines don’t have to be connected to anything else in particular.

Type C High-Current Legacy Devices

From ST’s PDF, it appears possible to draw more current through Type-C:



Advanced Info

Good USB Routing Practices

A quick summary of Good Usb Practices

Trace length Matching

  • Intel suggests that USB traces be matched to 150 mils within each other in length.
  • Trace spacing is debated.
    • Intel suggests 20 mils spacing between the USB traces.
    • Texas Instruments suggests a minimum of 30 mils.
    • Other sources suggest 5x the trace widths as trace spacing.
  • To forcefully match trace lengths, bend traces in a “zigzag” pattern at the mismatched end.
    • Diagram from Texas Instruments PDF

Signal Integrity

  • Run USB lines in parallel at all times.
  • Avoid jumping voids in ground planes.
  • Lines may have to be routed non-parallel near connectors and controllers. If so, make sure the non-parallel area is within 0.25 inches of the connector and controller.
  • Don’t bend USB signal lines at right angles.
  • Try keeping the traces at least 100 mil from the edges of ground planes.
  • Don’t run the USB signals in parallel to other pulsating traces such as the keyboard matrix or LED backlighting. If this is required, keep the traces at least 50 mils away.
  • When the traces must go through parts (I.E. the 22-ohm resistors), keep the layout symmetric
    • Diagram from Texas Instruments PDF



Advanced Info

EMI Shielding and Reduction

Healthy PCB designing.

Important to prevent a keyboard from malfunctioning from too much outside noise, and also to prevent a keyboard from wreaking havoc upon nearby devices such as pacemakers.
Texas Instruments states that any frequency above 80 MHz is a concern for radio frequency noise, but it’s not bad to be on the safe side, especially since these tips don’t change PCB costs at all.

General Design Considerations

Surface mount v.s. Through-hole

  • Surface mount often has lower noise emissions because the smaller components can be crushed together into a smaller region.
  • I cannot find the source, but I have read somewhere that round plated things such as through-hole pads can act as antennas much like a via under high frequencies.
    No loops
  • Loops are antennas.
  • This diagram from the Texas Instruments guide shows two loops.
    • A-B-C-D-E
    • F-G-H-D-C
  • Avoid them whenever possible.

Vias can act as antennas under higher frequencies. Reduce when possible.

Ground Planes

For the microprocessor:

  • Extend a ground pad on the other side of the controller, at least ¼ inches out beyond the area of the controller.
  • Preferably, use the ground plane to shield crucial components for the controller as well.
  • Don’t use the same ground plane for the controller as the rest of the board. Noisy ground current will flow into the controller area, and will destroy the point of having a ground plane in the first place.
    • Of course, this can be avoided with careful design of the ground plane.
    • Simply make sure that the ground planes do not act as a road for dirty ground signal to interfere with the clean controller ground area.
  • For extended shielding, place a ground plane on the other side as well.
    • Again, this must follow the aforementioned rules: Do not connect the ground planes together in far distances at multiple points or it becomes a loop of its own.
    • Having just one via will be effective.
    • Having many vias distributed across the area at close range within each other is also effective. This will effectively turn the two planes into one huge “block” of copper.
  • Preferably, separate the ground plane for the crystal from the ground plane of the controller area as well.
  • Connect the controller plane to the rest of the board’s ground at only one location.
    • Since electricity travels in the shortest distance possible, proper connection of the two ground planes will make the noisy ground signal from other components such as LEDs travel straight to the USB connector, disregarding the area * near the controller.
  • tl;dr: Shield the controller and don’t fling dirty ground current towards the controller.

General tips and info

  • A ground plane not connected to the ground (USB ground in the case of a regular keyboard) is not technically grounded.
  • For a wireless keyboard, connect the ground plane to the largest ground device possible, I.E. a metal plate or metal case.
    • If none of these are available, disregard this, since the ground plane itself serves as the largest ground.
  • Making the ground plane go all the way to the rim of the PCB can cause some fabs to create the PCB with a bit of the ground plane visible at the edge of the PCB. This can cause short-circuiting if not careful.
  • ALWAYS “rebuild” or “regenerate” the copper plane/ground plane area after changing any traces or component locations. Otherwise, the ground plane may be stuck to a bunch of other traces, causing huge short circuit issues.
  • It is suggested to place the ground plane in the very end.
    • This makes for easier routing.
  • Even if using ground planes, route ground traces.
    • This makes sure that all ground components are properly connected.
    • Using ground plane brute force may end up with improper connections for sensitive components near the controller. (See section 1)
  • Larger ground planes are more effective. Thin ground planes basically do nothing.

Minimal Ground Plane

For when you want maximum aesthetics.

This bare minimum setup has been tested functional:

Only attempt this if you are comfortable with careful component positioning and whatnot.

Via Fencing

It’s exactly how it sounds.

  • Placing multiple ground vias in a line, connected on both sides to a non-noisy ground trace/area, acts as a “fence” or “wall” to vacuum the ugliest RF noise.
  • Larger vias work better (Larger wall)

Calculating distance between vias

  • At least 1/10 of wavelength
  • At least 1/20 of wavelength recommended
  • Based on this excerpt from EDN’s PDF:
  • A common 16MHz signal used in keyboards has a wavelength of at least 23 inches, so the via spacing must be at most greater than 1 inches apart. Nothing to worry about here.
    Preferably, more vias = greater effect, but more vias = more drilling = higher PCB cost sometimes. Don’t overdo them to prevent turnaround time from skyrocketing or extra charges from piling up.


  • Can be used to reinforce sensitive areas, such as the area around the controller.
    • This is an example of keeping RF interference out.
  • Can be used when pulsing traces are too close to the edge of the PCB for the ground plane to effectively soak up the noise from exiting the board.
    • Simply make an effective ground plane between the trace and the edge of the board.
    • This is an example of keeping EMI in.



Advanced Info

Breakaway Tabs

Occasionally, you'll want to use breakaway tabs in your PCB to combine a few PCBs into a single physical board that breaks apart.

This guide explains how to use them to your advantage.

1. Obtaining the footprint

Grab the random-keyboard-parts.pretty library, either adding it to the project or adding it as a submodule (for git users).
Inside, there is a breakaway-mousebites footprint.

2. Placing the footprint

Simply place the footprint where you want the breakaway to be.
For the PCB holistic outline, simply draw on the edge.cuts layer.
For examples, see the Soyuz and Orbit PCBs.

3. Considerations

There is no guarantee that every single PCB is manufactured the same.
Leave some space between the breakaway bites and traces/components, for an un-clean snap could tear into such nearby components.

When having multiple breakaway tabs, take care to make it easy to break; for example, have a few "break lines", or lined up tabs so that things break smoothly instead of having to apply strange force and torque to the tabs.

The break usually occurs through the center of the mousebite drills. This means the placement of the mousebites determines how the board breaks apart.

Placing the footprint so the guide line matches up with the break line means that you will have small indents at the break tab, but protrusions will not extend beyond the expected outline. This is the ideal setup for internal things, such as regular PCBs. For example, see the Orbit repository.

On the other hand, placing the footprint so the drills are tangent to the break line means that you will have small protrusions at the cut, but no indents. This may be more ideal for exterior use parts such as plates, since the protrusions can be filed off whereas indents are much more difficult to deal with. For example, see the Soyuz repository.

4. Further reading




List of KiCad Keyboard Parts Libraries

For all footprint needs.
Library name Library description Author URL
MX_Alps_Hybrid.pretty Combined MX-Alps hybrid footprints ai03 https://github.com/ai03-2725/MX_Alps_Hybrid.pretty
keebs.pretty KiCAD library for hybrid MX/Alps footprints and microcontrollers egladman https://github.com/egladman/keebs.pretty
keyboard_parts.pretty KiCad modules for keyboard design Hasu https://github.com/tmk/keyboard_parts.pretty
keyboard_parts.pretty Fork of Hasu's library with more footprints colemarkham https://github.com/colemarkham/keyboard_parts.pretty
kicad_lib_tmk KiCad library for tmk project Hasu https://github.com/tmk/kicad_lib_tmk
random-keyboard-parts.pretty Various parts for keyboards, such as Mini-B USB connectors, reset buttons, etc. ai03



WS2812B.pretty KiCad footprints for WS2812B LEDs (and pin-compatible ones) madworm https://github.com/madworm/WS2812B.pretty
WS2812B.pretty Fork of above tailored for automated PCB assembly ai03



Keebio-Parts.pretty Various KiCAD footprints for mechanical keyboard parts keebio https://github.com/keebio/Keebio-Parts.pretty
Type-C.pretty Library for a few Type-C USB connectors ai03 https://github.com/ai03-2725/Type-C.pretty



PCB Quantity vs Price Comparisons

Using JLCPCB price quotes. All blanks; no PCBA cost factored in.

First set of data without shipping;

Second set of data including DHL shipping to US: