Advanced Info

The real work.


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.

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.


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


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.