The matrix circuit forms the electrical foundation of every keyboard, enabling a limited number of microcontroller pins to detect keypresses across dozens or hundreds of switches. Understanding matrix design is essential for keyboard PCB design, as the matrix determines firmware configuration, rollover capability, and overall keyboard functionality.
HILPCB manufactures keyboard PCBs with the consistent quality required for reliable matrix operation—precise hole placement for switches and proper trace connectivity for accurate key detection.
In This Guide
- Why Keyboards Use Matrix Circuits
- Matrix Scanning Process
- The Ghosting Problem
- Diode Solution for N-Key Rollover
- COL2ROW vs ROW2COL Configurations
- Matrix Optimization Strategies
- QMK Firmware Configuration
Why Keyboards Use Matrix Circuits
Direct wiring—connecting each switch to a dedicated MCU pin—would be impractical for any keyboard beyond a numeric keypad. A full-size 104-key keyboard would require 104 GPIO pins, far exceeding the capabilities of affordable microcontrollers like the ATmega32U4 (26 I/O pins) or even the RP2040 (30 GPIO).
Matrix circuits solve this constraint by arranging switches at the intersections of row and column lines. The mathematical efficiency is compelling:
Direct wiring (104 keys): 104 pins required 8×14 matrix (104 keys): 22 pins required (8 rows + 14 columns) Pin reduction: 79%
For a 60% keyboard (61 keys), an 8×8 matrix requires only 16 pins—leaving ample I/O for LEDs, rotary encoders, OLED displays, and other features.
The trade-off is complexity: matrix scanning introduces timing considerations, and without additional components, matrices are susceptible to "ghosting" that limits simultaneous key detection. These challenges are well-understood and solved through proper design.
Matrix Scanning Process
Matrix scanning is a sequential process where the microcontroller activates one row (or column) at a time while reading all positions on the opposite axis. By repeating rapidly across all rows, the MCU determines which switches are closed.
Scanning Sequence
- MCU sets Row 0 to LOW, all other rows HIGH (or floating with internal pull-ups)
- MCU reads all column pins simultaneously
- Any column reading LOW indicates a pressed switch at Row 0, that column
- MCU sets Row 1 to LOW (Row 0 returns HIGH), repeats column reading
- Process continues through all rows, completing one full scan
- Entire sequence repeats hundreds or thousands of times per second
Scan Rate and Latency
Scan rate directly affects perceived keyboard responsiveness:
- 125Hz (8ms per scan): Perceptible lag during fast typing or gaming
- 500Hz (2ms): Acceptable for most users
- 1000Hz (<1ms): Standard for quality keyboards, effectively instantaneous
- 8000Hz (0.125ms): Marketing-driven for competitive gaming, minimal practical benefit over 1000Hz
QMK firmware achieves 1000Hz on typical ATmega32U4 or RP2040 hardware with basic matrix configurations. Complex configurations (large matrices, extensive RGB, OLED displays) may reduce achievable rates, though 500Hz+ remains typical.
Matrix Efficiency Comparison
The Ghosting Problem
Ghosting occurs when matrix circuits create unintended electrical paths, causing the MCU to detect keypresses that didn't happen. Understanding the mechanism helps appreciate why diodes are essential.
How Ghosting Occurs
Consider three keys pressed simultaneously that form three corners of a rectangle in the matrix—positions (Row0, Col0), (Row0, Col1), and (Row1, Col0).
When scanning Row0: both Col0 and Col1 read LOW correctly (those switches are pressed).
When scanning Row1: Col0 reads LOW correctly. But Col1 also reads LOW even though the switch at (Row1, Col1) is NOT pressed. Current flows backward: from the LOW Row1 line, through the pressed switch at (Row1, Col0), into Col0, through the pressed switch at (Row0, Col0), into Row0, through the pressed switch at (Row0, Col1), and finally to Col1—creating a "sneak path" that makes an unpressed key appear pressed.
Ghosting Characteristics
- Requires at least 3 simultaneous keypresses
- Those keys must form 3 corners of a rectangle in the matrix
- The 4th corner falsely registers as pressed
- More simultaneous keys create more potential ghosting patterns
Some budget keyboards implement "blocking"—preventing certain combinations from registering rather than producing ghosts. This is unacceptable for gaming and fast typing where complex key combinations are routine.
Diode Solution for N-Key Rollover
Adding a diode in series with each switch eliminates ghosting by preventing current from flowing backward through the matrix. Diodes conduct in one direction only—from anode to cathode—blocking the sneak paths that cause ghost detection.
How Diodes Prevent Ghosting
With properly oriented diodes, current can flow from a switch to its row (or column) line but cannot flow backward from that line through another switch. Each switch position becomes electrically isolated from creating ghost circuits. The MCU reads only genuine keypresses regardless of how many keys are pressed.
Result: N-Key Rollover (NKRO)
With per-switch diodes:
- Any combination of keys detected accurately
- No blocking combinations
- Consistent behavior regardless of simultaneous keypresses
- Essential for gaming and fast typing
This is why all quality mechanical keyboards include one diode per switch. The component cost and assembly complexity are justified by the dramatic improvement in functionality.
Common Diode Options
- 1N4148 (through-hole DO-35): Classic choice, easy hand soldering, larger footprint
- 1N4148W (SOD-123): Standard SMT package, good balance of size and handling
- 1N4148WS (SOD-323): Smaller SMT for space-constrained designs
- BAV70 (SOT-23): Dual-diode package containing two diodes with common cathode—serves two switches, reduces component count
Orientation details in keyboard diode direction.
COL2ROW vs ROW2COL Configurations
Two standard configurations exist for keyboard matrices, differing in which axis drives current versus which reads results. Both work equally well—the choice typically depends on routing convenience.
COL2ROW (Most Common)
- Diode cathode (marked end) connects to the ROW line
- Column pins configured as outputs, driving LOW during scan
- Row pins configured as inputs with pull-up resistors
- Memory aid: "COL2ROW = Cathode to Row"—the "C" in both words
QMK configuration: #define DIODE_DIRECTION COL2ROW
ROW2COL (Alternative)
- Diode cathode connects to the COLUMN line
- Row pins configured as outputs, driving LOW during scan
- Column pins configured as inputs with pull-ups
- Signal flows from Row, through switch and diode, TO COLumn
QMK configuration: #define DIODE_DIRECTION ROW2COL
Critical Requirement
Firmware must match hardware exactly. If the PCB uses COL2ROW orientation but firmware specifies ROW2COL, the entire matrix will be non-functional. This mismatch is a common source of "dead keyboard" issues during initial bring-up.
Common Keyboard Matrix Dimensions
Matrix Optimization Strategies
Thoughtful matrix organization simplifies PCB routing, eases firmware development, and minimizes GPIO requirements.
Balancing Rows and Columns
For a given key count, multiple dimensions work mathematically. A 60-key board could use 5×12 (17 pins), 6×10 (16 pins), or 8×8 (16 pins with 4 unused positions).
Square or near-square matrices typically minimize total pin count while balancing routing complexity between layers. Approximately equal horizontal and vertical line counts distribute routing work evenly.
Physical Alignment
Aligning matrix rows with physical keyboard rows dramatically simplifies both routing and firmware:
- Row traces naturally run horizontally (matching physical layout)
- Column traces run vertically
- Keymap definition becomes intuitive (visual match to physical keyboard)
- Reduced crossing points and via count
Spare Positions
Leave unused matrix positions for layout variants:
- Split Backspace (two 1u keys vs one 2u)
- ISO Enter vs ANSI Enter
- Split Right Shift
- Alternative bottom row configurations
An 8×8 matrix with 61 keys leaves 3 positions for alternatives without additional pins.
QMK Firmware Configuration
QMK requires exact matrix specification matching hardware. The firmware needs matrix dimensions, pin assignments, and diode orientation.
Configuration in config.h
#define MATRIX_ROWS 8
#define MATRIX_COLS 8
#define MATRIX_ROW_PINS { B0, B1, B2, B3, B4, B5, B6, B7 }
#define MATRIX_COL_PINS { D0, D1, D2, D3, D4, D5, D6, D7 }
#define DIODE_DIRECTION COL2ROW
Pin naming varies by MCU: ATmega uses B0, D2, F4; RP2040 uses GP0, GP1, etc. Verify against the specific MCU datasheet.
Testing and Verification
Before finalizing firmware:
- Flash basic firmware with matrix debug enabled
- Short each switch position with tweezers
- Monitor debug output for correct row/column detection
- Test simultaneous keypresses to confirm no ghosting
- Verify all expected positions register correctly
Troubleshooting patterns:
- Entire row/column dead → Trace routing error or wrong pin assignment
- Scattered dead keys → Individual diode issues
- Complete matrix dead → DIODE_DIRECTION mismatch
HILPCB Matrix PCB Fabrication
HILPCB manufactures keyboard PCBs with the precision required for reliable matrix circuits:
- Hole Placement: Consistent switch alignment across the entire board
- Via Plating: 20-25μm barrel copper for reliable through-connections
- Trace Uniformity: ±10% across panels for consistent electrical characteristics
- Diode Assembly: SMT assembly with verified orientation for all common packages
We support keyboard projects from prototype quantities through group buy volumes with consistent quality at every scale.
Contact HILPCB for keyboard matrix design review and manufacturing quotation.