Diode orientation is a critical part of keyboard matrix design. A diode installed in the wrong direction can prevent keys from registering, cause an apparent matrix failure, or create confusing voltage readings during troubleshooting.
The most important point is that COL2ROW and ROW2COL describe the diode direction and matrix scanning arrangement together. They should not be interpreted simply as the direction in which a signal or current must always flow.
For a standard QMK-style matrix, the correct diode orientation depends on which side of the matrix is scanned and which side is read. QMK defines COL2ROW as a configuration in which the diode's cathode marking faces the row side, while ROW2COL reverses that diode direction. QMK's standard matrix code also distinguishes COL2ROW row reads from ROW2COL column reads.
This distinction matters because a design that drives a Column LOW and reads the Row requires the opposite diode orientation from a design that drives a Row LOW and reads the Column.
This guide explains the electrical relationship step by step so that the diode direction can be verified from the actual circuit rather than from the name alone.
In This Guide
- How a Keyboard Matrix Uses Diodes
- Anode and Cathode Identification
- COL2ROW: Correct Diode Direction and Scan Logic
- ROW2COL: Correct Diode Direction and Scan Logic
- The Most Common Source of Confusion
- PCB Footprint and Schematic Design
- Testing and Troubleshooting
- Practical Design Checklist
How a Keyboard Matrix Uses Diodes
A keyboard matrix reduces the number of MCU GPIO pins required to scan many switches. Instead of connecting every key to a dedicated input, switches are arranged at the intersections of rows and columns.
A typical matrix contains:
- Row traces
- Column traces
- Mechanical or electrical switches
- One diode associated with each matrix switch in a standard anti-ghosting design
- MCU GPIO pins connected to the row and column lines
- Firmware that selects one side of the matrix and reads the other
The diode provides directional isolation. Without appropriate isolation, current can travel through multiple pressed switches and create unintended electrical paths known as ghosting.
The diode therefore does more than simply indicate a preferred PCB orientation. Its polarity must agree with the electrical direction used by the matrix scanner.
Forward and Reverse Bias
A conventional diode conducts when its anode is at a sufficiently higher potential than its cathode.
- Forward bias: current can flow from anode to cathode.
- Reverse bias: the diode substantially blocks current from cathode to anode.
For a keyboard matrix, the important question is therefore:
When the selected matrix line is driven and a key is pressed, can the diode conduct from the driven side toward the sensed side?
That question is more reliable than trying to infer the answer from the words COL2ROW or ROW2COL.
Why the Diode Prevents Ghosting
Consider a matrix with several simultaneously pressed keys. If there are only switches and no directional isolation, the pressed keys can create unintended paths between different rows and columns.
Adding a diode at each switch intersection restricts current to one direction. This prevents many unwanted paths and allows the firmware to determine which switch intersections are actually active.
QMK's matrix documentation describes the same principle: a diode is placed after the switch and before the matrix line so that current can travel in only one direction. QMK's documented COL2ROW example places the diode's black marking toward the row side.
How to Identify the Diode Anode and Cathode
Before determining whether a diode belongs in a COL2ROW or ROW2COL circuit, identify its physical polarity correctly.
Through-Hole 1N4148
For a conventional glass 1N4148 in a DO-35 package:
- The black band identifies the cathode.
- The opposite lead is the anode.
The band is the most useful physical reference when installing the component. Lead length should not be used as a permanent polarity reference after the leads have been cut or formed.
SMD 1N4148W and Similar Parts
For common SMD switching diodes such as 1N4148W, the manufacturer specifies a cathode marking on the package. The exact marking appearance depends on the manufacturer and package.
For example, the Diodes Incorporated 1N4148W is a SOD-123 switching diode and specifies a cathode band. Always verify the exact manufacturer's datasheet for the specific part number and package used in production.
Do not assume that every visually similar diode package uses exactly the same marking style.
BAV70 Dual Diode
BAV70 is a dual switching diode with a common cathode in the standard SOT-23 version. For the Nexperia BAV70 pinout:
- Pin 1 = anode of diode 1
- Pin 2 = anode of diode 2
- Pin 3 = common cathode
Other manufacturers may use different package variants or pin configurations, so the exact datasheet must be checked before creating the PCB footprint.
This is an important correction to a common mistake: do not assume that every three-pin dual diode has the same pinout.
Verify With a Multimeter
If the package marking is unclear, use a multimeter's diode-test function.
A typical silicon switching diode will show a forward-voltage reading when:
- Red probe โ anode
- Black probe โ cathode
With the probes reversed, the meter should normally indicate an open or overload condition.
The exact forward-voltage value depends on the diode and test current, so the purpose of this test is primarily to identify polarity rather than to certify a specific voltage.
COL2ROW: Correct Diode Direction and Scan Logic
QMK defines COL2ROW as a matrix configuration in which the diode's black marking, which identifies the cathode, faces the row side and is located between the switch and the row. QMK also provides a COL2ROW-specific matrix read function named matrix_read_cols_on_row().
The Correct Hardware Rule
COL2ROW: Cathode โ Row
Therefore:
- Anode โ switch / column side
- Cathode โ row side
The physical diode marking points toward the Row.
Typical Electrical Path
In the common active-low interpretation:
Column side
|
Switch
|
Anode
|
Diode
|
Cathode
|
Row side
When the selected matrix configuration provides a valid forward-bias path, current must flow:
Column โ Switch โ Diode โ Row
The exact GPIO idle, active, pull-up, pull-down, and polarity behavior is firmware-dependent. The important hardware relationship is that the diode conducts from the column side toward the row side.
QMK Configuration
A QMK configuration can specify:
#define DIODE_DIRECTION COL2ROW
In newer keyboard.json configurations, the equivalent setting is:
{
"diode_direction": "COL2ROW"
}
QMK documents COL2ROW and ROW2COL as the two supported diode-direction settings for a conventional diode matrix.
Important Clarification About "Column to Row"
The name COL2ROW should not be treated as a universal statement that the MCU always drives the Column LOW.
It is better to remember:
COL2ROW
Cathode โ Row
and then verify the firmware's actual scan behavior.
QMK's own documentation describes COL2ROW for the diode marking facing the rows, while its low-level matrix API describes the configuration as row-based reads of columns.
ROW2COL: Correct Diode Direction and Scan Logic
ROW2COL reverses the diode direction compared with COL2ROW.
The Correct Hardware Rule
ROW2COL: Cathode โ Column
Therefore:
- Anode โ row side
- Cathode โ column side
The physical diode marking points toward the Column.
Typical Electrical Path
Row side
|
Switch
|
Anode
|
Diode
|
Cathode
|
Column side
The forward-current direction is therefore:
Row โ Diode โ Switch โ Column
The switch and diode order can be represented differently in a schematic depending on the drawing convention, but the electrical polarity must remain the same.
QMK Configuration
In config.h:
#define DIODE_DIRECTION ROW2COL
Or in keyboard.json:
{
"diode_direction": "ROW2COL"
}
QMK's matrix API identifies the corresponding read operation as matrix_read_rows_on_col(), which makes the relationship between the selected column and the rows being read explicit.
When ROW2COL Makes Sense
ROW2COL can be appropriate when:
- The existing keyboard hardware already uses this direction.
- The PCB routing is substantially easier with the reversed diode orientation.
- The firmware is already designed for ROW2COL.
- A custom matrix implementation requires this electrical direction.
- You are maintaining an existing keyboard design and must preserve its hardware interface.
There is no inherent electrical rule that makes one diode direction universally superior. The firmware and hardware must agree.
The Most Common Source of Confusion: Which Side Is Driven?
This is the most important section when troubleshooting a keyboard matrix.
The terms COL2ROW and ROW2COL are often misunderstood because people sometimes interpret them as merely describing the direction in which a GPIO signal travels.
Instead, determine the circuit from three questions:
- Which side is being driven by the MCU?
- Which side is being read by the MCU?
- In which direction does the diode conduct?
Case A: Column Is Driven, Row Is Read
Suppose the circuit is intentionally designed as:
Column = driven output
Row = input
and the selected Column is driven LOW.
If the Row input has a pull-up:
3.3 V
|
Row pull-up
|
ROW input
|
Diode
|
Switch
|
COLUMN output
|
LOW
For a key press to pull the Row voltage down, the diode must conduct from Row toward Column.
Therefore:
Anode โ Row
Cathode โ Column
This is the ROW2COL diode orientation.
So if you drive the Column LOW, press the switch, and still measure approximately 3.3 V at the Row input, one possible explanation is that the diode is reverse-biased because it was installed in the COL2ROW direction.
This is exactly why a SPICE model can appear to contradict a simplified explanation of diode direction: the model is following the actual electrical polarity, not the label attached to the matrix configuration.
Case B: Row Is Driven, Column Is Read
Now reverse the scan arrangement:
Row = driven output
Column = input
If the Row is driven LOW and the Column input is pulled HIGH:
3.3 V
|
Column pull-up
|
COLUMN input
|
Diode
|
Switch
|
ROW output
|
LOW
The diode must conduct from Column toward Row.
Therefore:
Anode โ Column
Cathode โ Row
This is the COL2ROW diode orientation.
The Correct Comparison
| Matrix configuration | Driven side | Read side | Diode anode | Diode cathode |
|---|---|---|---|---|
| COL2ROW | Row | Column | Column side | Row side |
| ROW2COL | Column | Row | Row side | Column side |
This table is the safest way to understand the relationship.
However, do not assume that every custom keyboard scanner uses exactly this active-low arrangement. QMK supports custom matrix scanning, and custom implementations can change how the GPIOs are controlled. The actual firmware should therefore be checked whenever a design does not use the standard matrix scanner.
Why a Row Can Remain at 3.3 V
If:
ROW = 3.3 V through pull-up
COLUMN = 0 V
and the diode is oriented:
Cathode โ ROW
Anode โ COLUMN
then:
ROW = 3.3 V
COLUMN = 0 V
places the diode in reverse bias.
The diode does not provide the expected path from Row to Column.
Consequently, pressing the switch does not necessarily pull the Row input LOW.
This is not a mysterious MCU problem. It is exactly what the diode polarity predicts.
PCB Footprint and Schematic Design for Clear Diode Orientation
A correct electrical design can still fail during PCB assembly if the footprint does not clearly communicate polarity.
Schematic Symbol
Use a standard diode symbol from a trusted CAD library and verify its pin names.
The schematic symbol should clearly distinguish:
- Anode
- Cathode
- Cathode bar
Do not describe the diode symbol as an "arrow." The cathode is represented by the bar, while the diode symbol itself is not an arrow. The physical package marking and schematic cathode must correspond.
PCB Footprint Marking
For each diode footprint, use a clear cathode indicator.
Useful methods include:
- A silkscreen bar aligned with the cathode
- A clearly marked cathode pad
- A polarity indicator in the assembly drawing
- A consistent component orientation across the entire board
- Pin-1 or pad references where applicable
Do not use a generic triangle or ambiguous shape as the only polarity indicator.
Keep the Orientation Consistent
If the PCB allows it, orient all keyboard diodes consistently.
For example:
All cathodes โ Row
for a COL2ROW design.
Or:
All cathodes โ Column
for a ROW2COL design.
Consistent placement makes AOI review, manual inspection, and troubleshooting much easier.
Match the Footprint to the Actual Part
The footprint should be verified against the exact component manufacturer and package.
This is particularly important for:
- SOD-123
- SOD-323
- SOD-523
- SOT-23
- Other dual-diode packages
Package names alone do not guarantee identical pin assignments or identical marking conventions across all components.
Assembly Documentation
The assembly drawing should identify diode polarity clearly.
For production PCBA, the manufacturing package should ideally include:
- Gerber files
- Pick-and-place data
- BOM
- Assembly drawing
- Polarity information
- Any special orientation notes
The polarity shown in the schematic, PCB, BOM, and assembly drawing should describe the same physical orientation. This is the package an SMT assembly line uses to set diode orientation on a keyboard PCB.
Testing and Troubleshooting Keyboard Diode Direction
Diode-direction problems can normally be isolated with a combination of visual inspection, diode testing, voltage measurements, and firmware verification.
Visual Inspection
Before powering the board:
- Identify the cathode marking on the actual diode.
- Compare it with the PCB footprint marking.
- Confirm that all diodes follow the intended matrix direction.
- Check that no diode was rotated 180 degrees.
- Confirm that the component package matches the BOM.
For SMD parts, magnification is often necessary.
Individual Diode Test
If a diode is suspected:
- Disconnect power.
- Isolate the diode if in-circuit measurements are ambiguous.
- Set the multimeter to diode-test mode.
- Place the red probe on the expected anode.
- Place the black probe on the expected cathode.
- Confirm forward conduction.
- Reverse the probes and confirm blocking behavior.
In-circuit measurements can be affected by other components and matrix paths, so a suspicious result should be confirmed with the diode isolated.
Matrix Voltage Test
For a circuit in which:
Column = output LOW
Row = input with pull-up
measure the Row voltage:
- Key released โ Row may remain HIGH through its pull-up.
- Key pressed with correct ROW2COL diode polarity โ Row should be pulled toward the selected LOW Column, subject to the GPIO configuration and diode drop.
- Key pressed with reverse diode polarity โ Row may remain HIGH because the diode is reverse-biased.
This test is especially useful when debugging a SPICE simulation or a prototype board.
Firmware Verification
Check the firmware setting.
For QMK:
#define DIODE_DIRECTION COL2ROW
or:
#define DIODE_DIRECTION ROW2COL
For keyboard.json:
"diode_direction": "COL2ROW"
or:
"diode_direction": "ROW2COL"
The setting must match the physical matrix design.
QMK also supports custom matrix implementations. If the keyboard uses a custom scanner, do not assume that the standard matrix behavior applies without checking the custom code.
Common Troubleshooting Patterns
All keys fail
Possible causes include:
- Firmware diode direction does not match the hardware.
- Matrix GPIO configuration is incorrect.
- A common row/column trace is open.
- The scanner is configured for the wrong matrix dimensions.
One key fails
Possible causes include:
- Reversed diode
- Soldering defect
- Open trace
- Defective switch
- Incorrect component
One row or column fails
Possible causes include:
- Broken row or column trace
- Bad connector or solder joint
- Incorrect MCU pin assignment
- Short circuit
- Incorrect matrix configuration
Row remains near 3.3 V when Column is driven LOW
First verify:
- The Row really has a pull-up.
- The Column is actually configured and driven LOW.
- The switch closes electrically.
- The diode polarity allows current from Row toward Column.
- The firmware is using the intended ROW2COL-style scan relationship.
Ghosting appears with multiple keys
Check:
- Missing diodes
- Incorrect diode orientation
- Incorrect matrix wiring
- Firmware matrix configuration
- Any custom matrix logic
Keyboard Diode Direction Design Checklist
Before releasing a keyboard PCB for fabrication or assembly, verify the following.
Electrical Design
- Define whether the matrix is COL2ROW or ROW2COL.
- Identify which side is driven during scanning.
- Identify which side is read by the MCU.
- Confirm the intended current path when a key is pressed.
- Confirm every diode is forward-biased in the intended pressed-key state.
- Confirm the diode direction prevents unwanted reverse paths.
Schematic
- Verify the diode cathode symbol.
- Verify anode and cathode net names.
- Confirm the switch and diode are connected to the intended matrix lines.
- Confirm the schematic matches the firmware configuration.
- Avoid ambiguous polarity symbols.
PCB Layout
- Verify every diode footprint polarity.
- Add a clear cathode marking.
- Keep diode orientation consistent where possible.
- Check the exact manufacturer's package drawing.
- Confirm the PCB silkscreen does not become hidden by the component body.
Firmware
- Verify
DIODE_DIRECTION. - Verify
matrix_pins.cols. - Verify
matrix_pins.rows. - Confirm the firmware scan direction matches the physical diode direction.
- Check for custom matrix scanning before assuming standard behavior.
Manufacturing
- Verify the BOM part number.
- Verify the package.
- Verify the cathode marking in the assembly drawing.
- Verify pick-and-place rotation.
- Inspect diode polarity after placement.
- Run AOI.
- Perform electrical matrix testing on assembled boards.
COL2ROW vs ROW2COL Quick Reference
The following summary is the most important part to keep with the PCB design documentation:
| Item | COL2ROW | ROW2COL |
|---|---|---|
| Cathode | Row | Column |
| Anode | Column | Row |
| QMK direction setting | COL2ROW |
ROW2COL |
| QMK standard read function | matrix_read_cols_on_row() |
matrix_read_rows_on_col() |
| Typical hardware current path | Column โ Switch โ Diode โ Row | Row โ Diode โ Switch โ Column |
| If the design drives Column LOW and reads Row | Not the matching standard direction | Matching direction |
| If the design drives Row LOW and reads Column | Matching direction | Not the matching standard direction |
The key rule is simple:
Do not choose the diode direction from the words "Column" and "Row" alone. Determine which matrix side is driven, which side is sensed, and whether the diode is forward-biased when the key is pressed.
For QMK's standard definitions, COL2ROW means the cathode marking faces the Row, while ROW2COL reverses it. QMK also documents separate row-read and column-read matrix functions for these configurations.
HILPCB Keyboard PCB Assembly
Correct diode polarity is an important part of reliable keyboard PCBA production. A production-ready keyboard assembly process should verify the component part number, package, placement rotation, cathode marking, and matrix functionality.
HILPCB supports keyboard PCB assembly and SMT production with processes that can include:
- BOM and component verification
- Pick-and-place programming
- SMT assembly
- Automated optical inspection (AOI)
- Electrical testing
- Prototype and small-batch assembly
- Volume production
For keyboard PCB projects, the manufacturing data should clearly define the diode part number, package, polarity, and assembly orientation.
Final Takeaway
The safest way to determine keyboard diode direction is to work backward from the actual electrical scan circuit.
If the design is:
Column = driven LOW
Row = input with pull-up
the diode must conduct:
Row โ Column
so:
Anode โ Row
Cathode โ Column
which corresponds to ROW2COL in the standard QMK terminology.
If the design is:
Row = driven LOW
Column = input with pull-up
the diode must conduct:
Column โ Row
so:
Anode โ Column
Cathode โ Row
which corresponds to COL2ROW.
Therefore, a Row input that remains near 3.3 V while a Column is driven LOW can be a normal result of a reverse-biased diode if the hardware uses COL2ROW polarity while the scan routine expects the opposite direction.
Always verify the actual firmware scan implementation, especially for custom matrix scanners, because the electrical behavior of the firmwareโnot the label aloneโdetermines which GPIOs are driven and which are read.