Pustakam Library

Free Science learning guide

How to Design and Build a Custom Keyboard From Scratch

How to Design and Build a Custom Keyboard From Scratch — a free intermediate-level guide covering how to build a custom keyboard from scratch. Learn...

101 min read10 chaptersintermediate

What you will learn

  1. Anatomy and Architecture of a Custom Keyboard
  2. Component Selection and Sourcing
  3. PCB Design Fundamentals
  4. Firmware Configuration and Programming
  5. Case and Plate Design
  6. Hand-Wiring Prototyping
  7. Soldering and PCB Assembly
  8. Switch Preparation and Lubing
  9. Stabilizer Modding and Acoustic Dampening
  10. Final Assembly and Troubleshooting

1. Anatomy and Architecture of a Custom Keyboard

The Illusion of Simplicity A custom keyboard looks like a single, solid block of plastic and metal. You press a key, a letter appears. But drop a pre-built board on your desk and listen to the hollow, rattling echo. Now, do the same with a custom-built keyboard, and you hear a sharp, confident "thock." That acoustic difference isn't magic—it’s the result of precise mechanical coupling and acoustic chambers working in harmony. Building a custom keyboard from scratch requires you to stop thinking of the keyboard as a single peripheral and start seeing it as a system of interacting layers. Every component, from the printed circuit board to the screws holding the case together, dictates the final sound, feel, and durability of the board. Before you can design a PCB, source switches, or write firmware, you need to understand the physical and electronic architecture that holds it all together. The Core Structural Layers A custom keyboard is built like a sandwich. Depending on the specific design, this sandwich can have anywhere from four to seven distinct layers. Each layer serves a specific structural, acoustic, or electronic purpose. The Case The case is the outermost shell that houses the entire assembly. It defines the exterior footprint, provides mounting points for the internal hardware, and acts as the primary acoustic chamber. Cases are typically cast or milled from aluminum, but acrylic, polycarbonate, and even wood are common. The case’s internal geometry is not arbitrary; it must precisely match the layout and mounting style of the PCB and plate. A case designed for a tray-mount keyboard will feature internal standoffs that screw directly into the plate, while a top-mount case will have a top piece that clamps down on the plate's edges. The Plate Situated directly beneath the switches, the plate is the structural backbone of the typing surface. It holds the switches perfectly aligned and prevents them from rotating or popping out during rapid typing. Plates are typically made of aluminum, brass, polycarbonate, or FR4 (a fiberglass composite). The material choice drastically alters the typing feel: Brass and Steel: Highly rigid. They produce a sharper, higher-pitched sound and offer very little flex. Aluminum and FR4: Offer a medium flex profile, absorbing some impact and creating a deeper sound. Polycarbonate: Highly flexible. "Flex cuts" (strategic cutouts in the plate) are often paired with polycarbonate to allow the plate to bend slightly under heavy typing, creating a soft, cushioned feel. The PCB (Printed Circuit Board) The PCB is the electronic brain of the keyboard. It routes the electrical signals from each switch to a microcontroller, which then translates those signals into keystrokes. Beyond pure electronics, the PCB provides secondary structural support and acts as a …

2. Component Selection and Sourcing

Defining Your Typing Experience You have your concept. You know you want a 65% board with a gasket mount configuration and an FR4 plate for a deep, flexible typing feel. But a gasket mount is only as good as the components you sandwich between those layers. If you drop a heavy, scratchy switch into a beautifully dampened case, the acoustic and tactile potential of your mounting style is wasted. Selecting components is where the abstract concept of a keyboard becomes a physical reality. Every choice—down to the polymer used in a switch stem—alters the final sound profile, typing resistance, and longevity of your board. This chapter focuses on evaluating the raw materials, switches, and electronics required to bridge the gap between your plate architecture and your microcontroller. Switches: The Heart of the Keyboard The switch is the single most impactful component regarding how your keyboard feels and sounds. As established in Chapter 1, the vast majority of custom keyboards utilize MX-compatible switches, though low-profile builds may rely on Kailh Choc alternatives. Assuming you are working within the MX ecosystem, selecting the right switch requires evaluating materials, spring weight, and tactile feedback. Switch Materials and Acoustic Profiles Modern MX-style switches are primarily made from a combination of Polycarbonate (PC), Nylon, POM, and PBT. The housing and stem materials dictate both the durability of the switch and its default acoustic signature. Polycarbonate (PC) Top Housings: PC is standard for top housings because it is stiff, allowing for a crisp, sharp sound when the stem strikes the top housing on the upstroke. Nylon Bottom Housings: Nylon is softer and more sound-absorbent than PC. It produces a deeper, "thockier" bottom-out sound. Many classic switches use a PC top and Nylon bottom to achieve a balanced sound profile. POM Stems: Polyoxymethylene (POM) is highly self-lubricating and resistant to wear. It is the standard stem material for linear switches, providing a smooth travel path. PBT Stems/Housings: PBT is sometimes used for its dimensional stability across temperature changes, though it is less common in modern enthusiast switches than PC and Nylon. Scenario: The "Thock" Chaser If your goal is a deep, muted "thock" reminiscent of a classic IBM beam spring, you would avoid switches with full PC housings, which sound high-pitched and clacky. Instead, you would source switches with a Nylon bottom housing, a POM stem, and potentially a PC top housing to keep the upstroke crisp without adding excessive treble. Spring Weight and Bottom-Out Force Spring weight is measured in grams of force (g) required to actuate the switch, but more importantly, to bottom it out. Manufacturers usually list bottom-out force, as that dictates the physical limit of your keypress. Light (45g – 55g bottom-out): Ideal …

3. PCB Design Fundamentals

From Concept to Copper: The Schematic Phase You’ve sourced your MX-compatible switches, picked out a microcontroller, and decided on a plate material. Now, you need to design the nervous system that connects them: the PCB. Designing a printed circuit board for a keyboard comes down to two distinct phases: drawing the logical relationships in a schematic, and arranging the physical copper in a board layout. For this, we will use KiCad, a powerful, open-source CAD software suite. Because you already understand basic electronics, we will move quickly through the interface and focus directly on building a keyboard matrix. Understanding the Keyboard Matrix If you have a 60-key keyboard, wiring each switch directly to its own pin on a microcontroller would require 60 individual pins—far more than standard microcontrollers possess. Instead, keyboards use a matrix. By arranging switches in a grid of rows and columns, a 60-key keyboard (5 rows by 14 columns) only requires 19 microcontroller pins. Here is how a matrix scan works: 1. The microcontroller sets one row to LOW (or HIGH, depending on your firmware design). 2. It reads all the columns. 3. If a switch is pressed, the row signal flows through the switch and into the column, which the microcontroller detects. 4. It iterates through the remaining rows. However, if you press two keys in the same row simultaneously, electrical current can flow backward down a column, registering a third, unpressed key. This is called ghosting. To prevent this, we place a diode in series with every switch. Diodes act as one-way valves, ensuring current can only flow from the row, through the switch, into the column. Assigning Rows and Columns in KiCad Open KiCad and create a new project. Launch the Schematic Editor. Your first task is to place your components. You will need: - Switch footprints: Use the SwitchSWKeyboard library to find standard MX-compatible or Kailh Choc symbols. - Diodes: Standard 1N4148 signal diodes. You can use through-hole (DO-35) or surface mount (SOD-123) packages. Remember from our component sourcing chapter that surface mount diodes save space and speed up assembly, but through-hole is easier for beginners to solder. - Microcontroller: Use a generic header symbol (e.g., Conn01x24) to represent your chosen microcontroller's pins. Wiring the Matrix: 1. Place your switches in a rough grid. 2. Place a diode next to each switch. 3. Wire the anode of the diode to one pin of the switch, and the cathode to the next. 4. Connect all the diode cathodes in a single horizontal line. This becomes your Row. 5. Connect the other pin of every switch in a single vertical line. This becomes your Column. 6. Assign Net Labels (press L in KiCad). Label your …

4. Firmware Configuration and Programming

The Brain of the Board: Choosing Your Framework You’ve spent hours in EDA software routing traces, finalizing your PCB layout, and carefully selecting your plate material for that perfect flex profile. But right now, your keyboard is essentially a very expensive paperweight. Without firmware, a microcontroller is just a silicon wafer waiting for instructions. It doesn't know what a keypress is, let alone how to interpret a complex 15-key chord macro. Firmware is the bridge between your physical hardware and your operating system. To program the microcontroller, we rely on open-source firmware frameworks. The two undisputed heavyweights in the custom keyboard space are QMK (Quantum Mechanical Keyboard) and ZMK (Zephyr Mechanical Keyboard). As an intermediate builder, you likely already know the broad strokes: QMK is the legacy standard, incredibly powerful and deeply documented, while ZMK is the modern darling, built on the Zephyr RTOS and designed from the ground up for wireless split keyboards. Which should you choose? Choose QMK if: Your PCB uses an AVR (like an ATmega32U4) or a wired ARM microcontroller. If you are building a traditional, wired, single-piece or split keyboard, QMK’s massive community library and decades of troubleshooting threads make it the path of least resistance. Choose ZMK if: Your board utilizes Bluetooth Low Energy (BLE), particularly if you are building a wireless split keyboard using nice!nanos or compatible Nordic nRF52840 chips. ZMK handles wireless synchronization and power management far more elegantly than QMK. For the remainder of this chapter, we will use QMK as our primary reference for code examples and compilation workflows, as its C-based keymap structure is the most universal starting point. However, the conceptual logic—layers, macros, and matrix scanning—translates directly to ZMK’s Device Tree overlay system. Setting Up Your Local Development Environment While browser-based configurators like the QMK Configurator exist, they are graphical training wheels. To truly leverage custom behaviors, tap-dance routines, and complex macros, you need a local development environment. Installing the Toolchain Compiling firmware requires a specific set of build tools. Rather than hunting down individual compilers and dependencies, the QMK community has streamlined this process. 1. Install QMK MSYS (Windows) or Homebrew (macOS): On Windows, download and run the QMK MSYS installer. This provides a Unix-like shell pre-loaded with all the necessary Git and Python tools. On macOS, install Homebrew, then run the official QMK Homebrew tap: brew install qmk/qmk/qmk. On Linux, use your distribution’s package manager to install git, python3, pip, and make. 2. Clone the Repository: Open your terminal and run qmk setup. This command clones the entire QMK firmware repository to your local machine (usually ~/qmkfirmware). It will also set up your global configuration file, ~/.qmkrc. 3. Verify the Environment: Run qmk doctor. This diagnostic …

5. Case and Plate Design

From Schematic to Solid: The Structural Layer You’ve validated your circuit, generated your Gerber files, and flashed your firmware to a working prototype. The PCB works. But when you rest your bare board on the desk and type on it, the switches wobble, the board flexes, and the sound is a hollow, rattling echo. A PCB alone is not a keyboard. It needs structural integrity, acoustic dampening, and physical weight to transform it from a fragile circuit board into a premium input device. This brings us to the structural housing and the switch plate. Designing these components requires shifting your mindset from electrical engineering to mechanical CAD. You are no longer routing traces; you are managing tolerances, selecting materials for their acoustic and structural properties, and preparing models for real-world manufacturing. Establishing the Footprint and Layout Before you open your 3D modeling software of choice (Fusion 360, SolidWorks, and FreeCAD are all excellent choices for this), you need the physical outline of your PCB. If you designed your own PCB as covered in PCB Design Fundamentals, export the board outline DXF file directly from your EDA software. This file contains the exact external silhouette of your board, including mounting holes, USB cutouts, and any edge cuts. Import this DXF into your CAD software as a sketch. This imported sketch will serve as the immutable boundary for both your plate and your case design. Defining the Layout Matrix Whether you are building a compact 60% or a full-size TKL, your layout must be locked in before you draft a single plate cutout. While you may have defined the matrix in your firmware, physical design requires exact coordinate geometry. Standard ANSI and ISO layouts use a 19.05mm (0.75 inch) spacing between switch centers—often referred to as 19.05mm pitch. However, the physical footprint of a 1u keycap is typically 18mm wide, leaving roughly 0.525mm of gap between keycaps. When designing your plate, your switch cutouts will be centered on this 19.05mm grid. For non-standard key widths (1.25u, 1.5u, 2u, etc.), multiply the unit size by 19.05mm to find the center-to-center distance. The switch itself, however, always remains the same physical size. It is the keycap that grows, meaning your plate cutouts remain identical regardless of the keycap size—the only exception being the cutouts required for Stabilizers. Designing the Switch Plate The switch plate is the primary interface between your fingers and the switches. It dictates switch alignment, contributes heavily to the typing feel, and requires extreme precision. If a cutout is 0.2mm too large, the switch will spin; if it is 0.2mm too small, the switch legs will crush during installation. Switch Cutout Dimensions Most custom keyboards utilize MX-compatible switches, which share a …

6. Hand-Wiring Prototyping

The Case for Skipping the PCB Imagine you want a split keyboard with a 5-column layout, an integrated trackball, and a cluster of macro keys angled precisely for your left hand. You could spend weeks routing traces in KiCad, waiting for a fabricator to print a custom PCB, and praying you didn't misalign a switch footprint. Or, you could buy a sheet of FR4, a pile of switches, and a Pro Micro, and be typing on your dream layout by the weekend. Hand-wiring is the bridge between imagination and physical reality. As introduced in Component Selection and Sourcing, it bypasses the traditional PCB entirely, allowing for rapid prototyping and highly bespoke layouts without the overhead of custom fabrication. While PCB Design Fundamentals taught you how a matrix is routed via copper traces, this chapter forces you to build that matrix manually. By connecting MX-compatible switches directly to a microcontroller using copper wire and diodes, you will learn the underlying electrical architecture of a keyboard in a way that routing software never quite reveals. Once the solder cools, you will flash a hand-wire compatible firmware to test your prototype, and learn how to hunt down the inevitable electrical gremlins. Planning the Matrix Architecture In a custom PCB, the matrix is hidden beneath the switches. In a hand-wired build, the matrix is the structural foundation. Before touching a soldering iron, you must map out your rows and columns on paper. Whether you are building a standard ANSI layout, an ISO variant, or a completely custom ergo layout, the electrical logic remains the same: switches are arranged in a grid. One leg of each switch belongs to a column, and the other leg belongs to a row. Diode Orientation and Row/Column Logic Because multiple switches share the same row and column wires, the microcontroller needs a way to know exactly which key is pressed. Without diodes, pressing two keys in the same row and two keys in the same column simultaneously creates an electrical short, causing "ghosting"—where unpressed keys register as pressed. To prevent this, every switch requires a 1N4148 diode. Diodes act as one-way valves for electricity. In hand-wiring, you have two choices for how to orient them: Row-to-Column (Column-pins read, Row-pins send): The diode is placed on the row wire, allowing current to flow from the row to the column. Column-to-Row (Row-pins read, Column-pins send): The diode is placed on the column wire, allowing current to flow from the column to the row. The most common hand-wiring convention is Row-to-Column. Current flows from the microcontroller's row pin, through the diode, through the switch, and down to the column pin. The Non-Negotiable Rule: The black line (cathode) on the diode must face …

7. Soldering and PCB Assembly

The Soldering Station: Setup and Thermal Dynamics You’ve spent weeks agonizing over Component Selection and Sourcing, laying out traces in your PCB Design Fundamentals, and writing the QMK code in Firmware Configuration and Programming. Now, those custom components are sitting on your workbench, and the bare FR4 PCB is waiting. This is the moment of truth. Soldering a custom keyboard PCB is a delicate balance of heat transfer, timing, and material control. Whether you are populating a compact 40% board or a full-size ANSI layout, the assembly process demands precision. A single cold joint can cause an entire row to drop out, requiring hours of desoldering and rework. Before touching solder to pad, your station must be calibrated. For keyboard assembly, a temperature-controlled soldering iron is non-negotiable. Fixed-temperature irons cycle on and off, leading to wild thermal fluctuations that can delaminate pads. Temperature Selection: Leaded Solder (63/37 or 60/40 Sn/Pb): Set your iron between 315°C and 340°C (600–645°F). Leaded solder melts at around 183°C, but you need the higher thermal mass to rapidly heat the joint without lingering on the pad. Lead-Free Solder (SAC305): Set your iron between 350°C and 380°C (660–715°F). Lead-free alloys melt at a higher temperature (around 217°C) and require a slightly hotter iron to achieve adequate wetting quickly. The goal is to get in and out fast. A common beginner mistake is setting the iron too cold, thinking it will protect the PCB. In reality, a cold iron forces you to dwell on the joint for 5–10 seconds, allowing heat to spread into the FR4 and delaminate the copper pad. A hotter iron allows you to complete the joint in 1–2 seconds, limiting the heat-affected zone. Tip Selection: Ditch the conical tip that came with your iron. Conical tips have minimal surface contact with the pad, leading to poor heat transfer. Use a chisel tip or bevel tip. The flat surface area of a chisel tip bridges the pad and the component leg, creating a perfect thermal highway. Securing the PCB for Assembly Keyboard assembly is sequential. You cannot solder switches if the diodes aren’t installed, and you cannot easily install diodes if you’ve already mounted the plate. Because you are working with a custom PCB, your assembly order is dictated by the mounting style and component types defined in your design phase. 1. Secure the PCB: Use a helping-hand arm, a PCB vise, or magnetic third-hands to hold the board about six inches above your desk. You need clearance for component legs to pass through the bottom of through-hole vias. 2. Inspect the Silkscreen: Before applying heat, do a final visual sweep. Check the silkscreen for diode orientation (the cathode line) and confirm your layout …

8. Switch Preparation and Lubing

You’ve spent hours agonizing over the perfect acoustic profile. You selected a brass plate for its high-frequency resonance, paired it with a gasket mount FR4 case for flex, and meticulously soldered your switches to a custom PCB. But when you finally plug it in and type your first sentence, the sound is a chaotic, scratchy rattle instead of the deep, muted "thock" you envisioned. The culprit? Untouched, factory-state switches. Mass-produced switches are engineered for tolerances and cost-efficiency, not acoustic perfection. Out of the bag, the plastic stems grind against the housing rails, and the springs ping with every compression. Modifying mechanical switches through lubrication and filming is the most tedious step in building a custom keyboard, but it yields the most dramatic transformation in both feel and sound. By the end of this process, you will turn an off-the-shelf component into a bespoke actuator tailored precisely to your tactile and acoustic preferences. Disassembly: Opening the Switch Safely Whether you are working with through-hole or Surface mount PCBs, the physical switch sitting in your plate operates identically. To modify a switch, you must first open it. Most modern custom switches feature a top-housing clip design, meaning the top housing snaps onto the bottom housing via four plastic clips. The Right Tool for the Job While you can theoretically pry a switch open with a flathead screwdriver, doing so almost guarantees mangled plastic and broken clips. You need a dedicated switch opener. - TW-opener style: Features a central plunger that pushes the stem down while four arms simultaneously push the clips outward. This is the safest method for opening switches in bulk without stressing the plastic. - Lever-style openers: Operates like a pair of pliers. Squeezing the handle pushes the clips apart. These are effective but require careful pressure control to avoid cracking the top housing. Step-by-Step Disassembly 1. Orient the switch: Ensure the switch is right-side up, with the pins facing down and the top housing facing up. 2. Engage the opener: Place the switch into the opener. If using a lever style, apply slow, even pressure until you hear the clips snap free. 3. Separate the components: Gently lift the top housing away. Remove the stem and the spring. 4. Organize your parts: Switch disassembly generates hundreds of tiny components. Use a component tray or ice cube tray to keep the bottoms, tops, stems, and springs grouped. Even if you are lubing batch by batch, keeping parts organized prevents accidental loss. A Note on Reusing Parts: If you are modding a set of switches harvested from an older build, inspect the leaf contacts inside the bottom housing. If they are bent or dirty, they can cause actuation inconsistencies. A quick …

9. Stabilizer Modding and Acoustic Dampening

You’ve spent hours meticulously filming and lubing your switches. You’ve selected a heavy brass plate for rigidity, paired it with a custom FR4 PCB, and agonized over a Gasket Mount case for the perfect flex. You solder everything together, plug it in, and hit the spacebar. Clack-rattle-rattle-thud. Instead of the deep, satisfying thock you anticipated, you hear a tinny, rattling mess. The culprit? Untuned stabilizers and an untreated acoustic chamber. A custom keyboard is only as good as its largest keys, and the hollow echo of an empty case will amplify every imperfection in your build. Having covered the fundamentals of Soldering and PCB Assembly and Switch Preparation and Lubing, we now turn to the final frontier of keyboard acoustics: taming the stabilizers and dampening the case. The Anatomy of a Stabilizer By now, you know that stabilizers keep larger keys like the spacebar, shift, and enter level. To mod them effectively, you need to understand their discrete components: - Housing: The outer plastic shell. Usually comes in two pieces (top and bottom) that snap together. - Insert (or Stem): The cross-shaped component that the keycap sits on. It connects to the wire. - Wire: A bent metal bar that ties two stabilizer inserts together, ensuring they move in unison. - Band-aid/PCB contact point: The area on the PCB directly beneath the stabilizer wire where it bottoms out. Most custom builds use plate-mount or PCB-mount Cherry-style or screw-in stabilizers. Regardless of the mounting style, the mods we will apply remain largely the same. The Band-Aid Mod Every time you press a stabilized key, the stabilizer wire arcs downward. At the bottom of the keystroke, the wire hits the bare PCB. Without intervention, this is a harsh, plastic-on-fiber-glass collision that transmits a sharp "clack" through the board. The Band-Aid mod softens this impact. Materials and Preparation Do not use actual fabric bandages. Fabric retains moisture and degrades over time. Instead, use transparent film bandages (often marketed as blister bandages or waterproof bandages). These feature a polyurethane pad that is highly durable, non-absorbent, and perfectly cushioned. 1. Clean the area on the PCB where the stabilizer wire will strike. Use isopropyl alcohol to remove any flux residue from soldering or natural skin oils. 2. Cut the transparent film bandages into small squares. The exact size depends on your stabilizer spacing, but roughly 10mm x 10mm is a standard starting point. 3. Ensure the squares are cut cleanly. Frayed edges can catch the wire or prevent the stabilizer housing from sitting flush against the PCB. Application Peel the backing off the cut bandage squares and apply them directly to the PCB where the wire will make contact. Press firmly to ensure full adhesion. …

10. Final Assembly and Troubleshooting

You’ve spent hours modding your stabilizers, meticulously lubing switches, and perfecting your soldering joints. But when you finally plug in your completed PCB, half the alpha cluster is dead, and the spacebar sounds like a maraca. The final assembly stage is where the theoretical meets the physical. A perfectly soldered PCB can fail due to a stripped screw, a pinched wire, or a plate slightly out of tolerance. This chapter focuses on integrating your assembled components into their final case, diagnosing the inevitable hiccups, and executing a flawless functional test. Integrating the Build: Mounting the PCB and Plate By now, your switches are seated in the plate, soldered to the PCB, and your stabilizers are modded and installed. The first step of final assembly is mating this assembly with the case you designed or selected in Case and Plate Design. How you approach this depends entirely on your chosen mounting style. Pre-Assembly Checks Before dropping the assembly into the case, perform a quick tactile audit: 1. The Switch Squeeze: Pinch the top and bottom housings of a few switches. If they separate easily, the plastic latches are broken or the switch wasn't fully seated during Soldering and PCB Assembly. Replace them now. 2. Stabilizer Clearance: Ensure your stabilizer wires have enough vertical clearance. If your plate is a tighter tolerance than expected, the stabilizer housing might be pressing hard against it, which will cause binding. 3. PCB Inspection: Check the bottom of the PCB for stray solder blobs or clipped leg fragments that could short against the case. Mounting Style Mechanics Each mounting style requires a specific approach to final torque and alignment: - Tray Mount: This is the most forgiving style. Drop the assembly in, align the standoffs, and secure it using the case screws. Pro tip: Do not overtighten. Tray mount relies on a slight gap between the PCB and the case standoff for acoustic isolation. Overtightening transfers vibration directly to the case, ruining the acoustic dampening work you did in Stabilizer Modding and Acoustic Dampening. - Top Mount: The plate attaches directly to the top piece of the case. You will need to carefully align the plate cutouts with the internal standoffs. Because the PCB hangs from the plate, ensure the PCB isn't flexing under its own weight before securing the top case half. - Bottom Mount: The PCB/plate assembly secures to the bottom of the case. You will need to route your USB cable carefully before flipping the assembly over, as the cable can get trapped between the PCB and the case bottom. - Sandwich Mount: The plate is squeezed between the top and bottom case pieces. Loosely assemble all screws first, then tighten them in …

Continue learning