Overview
SwitchMatrixInput is a templated input source for reading buttons arranged in a matrix configuration with rows and columns. This approach reduces the number of GPIO pins required compared to individual button wiring.
For example, a 5x13 matrix can read up to 65 buttons using only 18 GPIO pins (5 + 13), whereas individual wiring would require 65 pins.
Class Declaration
Template parameter specifying the number of rows in the matrix.
Template parameter specifying the number of columns in the matrix.
Diode Direction
Diodes are oriented with anodes connected to rows and cathodes connected to columns. Rows are driven LOW and columns are read.
Diodes are oriented with anodes connected to columns and cathodes connected to rows. Columns are driven LOW and rows are read.
Constructor
Array of GPIO pin numbers for matrix rows. Array size must match the
num_rows template parameter.Array of GPIO pin numbers for matrix columns. Array size must match the
num_cols template parameter.2D array mapping matrix positions to button identifiers. Use
NA (or BTN_UNSPECIFIED) for unused positions.Diode orientation in the matrix hardware. Must match your physical circuit design.
Methods
ScanSpeed()
ReturnsInputScanSpeed::FAST, indicating this input source should be polled frequently.
Always returns
InputScanSpeed::FASTUpdateInputs()
Scans the entire matrix and updates the input state with current button states.Reference to the
InputState structure to update with current button states.Configuration Example
Complete Matrix Configuration
config.cpp
Dual-Core Usage (Raspberry Pi Pico)
For optimal performance on RP2040, scan the matrix on the second core:config.cpp
Hardware Design
Matrix Wiring Basics
A switch matrix uses diodes to prevent “ghosting” when multiple buttons are pressed simultaneously.COL2ROW Configuration
ROW2COL Configuration
Matrix Layout Planning
Using NA for Empty Positions
Optimizing Matrix Dimensions
Choose matrix dimensions to minimize GPIO usage:- Total pins required =
num_rows + num_cols - Maximum buttons =
num_rows × num_cols - Optimal ratio: Try to keep rows and columns roughly balanced
| Buttons | Configuration | Total Pins | Efficiency |
|---|---|---|---|
| 20 | 4×5 | 9 pins | 2.22 buttons/pin |
| 20 | 2×10 | 12 pins | 1.67 buttons/pin |
| 20 | 5×4 | 9 pins | 2.22 buttons/pin |
For matrices with many empty positions, consider using multiple smaller matrices or switching to GpioButtonInput for buttons that don’t fit well in the matrix.
Scanning Algorithm
The matrix is scanned by:- Setting one output (row or column) to LOW
- Reading all inputs (columns or rows)
- Recording pressed buttons at the intersections
- Returning the output to HIGH (pull-up)
- Moving to the next output
Performance
- Scan Speed:
FAST- suitable for high-frequency polling - Typical Scan Rate: 1000Hz+ (all buttons scanned per cycle)
- Latency: < 1ms for button state changes
- Pin Efficiency: ~2-3 buttons per GPIO pin (depending on matrix size)
Platform Notes
Raspberry Pi Pico (RP2040)
- Supports up to 29 GPIO pins (GP0-GP28)
- Hardware-accelerated GPIO reads for fast scanning
- Dual-core support allows dedicated scanning core
- Recommended for large matrices (10+ rows/columns)
Arduino (AVR)
- Limited GPIO availability (14-20 pins depending on board)
- Suitable for smaller matrices (5×5 or smaller)
- Single-core requires efficient loop() implementation
Troubleshooting
Multiple Buttons Triggering Simultaneously
- Cause: Incorrect diode direction
- Solution: Verify physical diode orientation matches
DiodeDirectionparameter
Buttons Not Responding
- Cause: Swapped row/column pin assignments
- Solution: Double-check pin arrays match physical wiring
Intermittent Button Presses
- Cause: Scan rate too low, timing issues
- Solution: Use dual-core scanning on Pico, verify
UpdateInputs()is called in loop
Matrix scanning is sensitive to timing. Always call
UpdateInputs() in every loop iteration, or use a dedicated core for continuous scanning.See Also
- GpioButtonInput - For non-matrix button configurations
- DebouncedSwitchMatrixInput - Matrix input with hardware debouncing
- Button Reference - Complete button identifier reference
- Input Sources - Overview of all input source types
