debounce-button-matrix-eng
debounce-button-matrix-eng is a no_std crate for scanning a rectangular
button matrix through embedded-hal GPIO traits.
The crate is based on the simple debounced state machine from
debounce-button-eng, but keeps only matrix-related basics:
- debounced
Pressed/Releasedstate for every key; - press and release events;
- hold duration while a key is pressed;
- final hold duration on release;
- multiple key events returned from one scan;
- user-defined key names returned with every event;
- no heap allocation.
GPIO Model
A matrix is passed as two arrays:
rows: [ROW; ROWS], whereROW: embedded_hal::digital::InputPin;columns: [COL; COLS], whereCOL: embedded_hal::digital::OutputPin.
Every scan selects one column output, reads all row inputs, updates the debouncer for each key in that column, deselects the column, and moves to the next one.
The common pull-up wiring is:
- rows are inputs with pull-up resistors;
- columns are outputs;
- inactive columns are high;
- the currently scanned column is driven low;
- a pressed key makes the row read low.
That is the default MatrixConfig::active_low() mode.
For pull-down style wiring, use MatrixConfig::active_high().
Key Names
Each key has a user-provided name:
let names = ;
The name type only needs to be Copy. For production firmware, an enum is
often better than strings:
let names = ;
Every returned event contains event.name, event.row, and event.column.
Quick Start
use ;
let rows = ;
let columns = ;
let names = ;
let config = active_low.with_debounce_ms;
let mut matrix = with_config;
loop
Passing GPIO from esp-hal
The exact type names depend on the esp-hal version and chip, but the shape is
the same: create input pins for rows, output pins for columns, then pass arrays
to the matrix.
let rows = ;
let columns = ;
let names = ;
let mut matrix = new;
For an active-low matrix, initialize column outputs high. scan() will drive one
column low at a time and return it high before selecting the next column.
Multiple Keys
Each key has an independent debounce state. If two keys become stable during the same scan, both events are returned:
let events = matrix.scan?;
for event in events.iter
The crate can track multiple pressed keys in software. For arbitrary multi-key combinations in real hardware, the matrix should use diodes. Without diodes, some combinations can create ghost keys electrically before software sees the signals.
Examples
Short and long presses
Use the release event's held_ms to distinguish a tap from a long press. The
duration starts when the press becomes debounced, so it does not include the
initial debounce interval.
use ButtonEventKind;
const LONG_PRESS_MS: u64 = 750;
for event in matrix.scan?.iter
Check one key or all held keys
is_pressed and held_ms are useful for controls whose action continues
while they are held. Indexes outside the matrix are safe: they return false
or None.
// Give the Up key an auto-repeat action after 300 ms.
if matrix.is_pressed
// Or update every held key. The iterator is row-major and allocates nothing.
for key in matrix.pressed_keys
Active-high matrix
For pull-down rows, initialize unselected columns low and use
MatrixConfig::active_high(). While scanning, the selected column is driven
high and a pressed key makes its row read high.
use ;
let rows = ;
let columns = ; // Configure outputs initially low.
let names = ;
let config = active_high.with_debounce_ms;
let mut matrix = with_config;
If the board requires mixed polarity, set the two parts separately:
use ;
let config = active_low
.with_row_active_level
.with_column_drive;
Report GPIO failures with their matrix position
scan returns MatrixError, which identifies the failing row or column.
This lets firmware add useful diagnostics without giving up the underlying GPIO
error.
use MatrixError;
match matrix.scan
API Summary
MatrixConfig:
MatrixConfig::active_low()- selected columns are low, pressed rows read low;MatrixConfig::active_high()- selected columns are high, pressed rows read high;with_debounce_ms(...)- debounce time in milliseconds;with_row_active_level(...)- override row input polarity;with_column_drive(...)- override column output polarity.
ButtonMatrix:
ButtonMatrix::new(rows, columns, names);ButtonMatrix::with_config(rows, columns, names, config);scan(now_ms)- scan the whole matrix once;state(row, column)- current stable state for one key;is_pressed(row, column)- stable pressed state check;held_ms(row, column, now_ms)- current hold duration for one key;pressed_keys(now_ms)- iterator over all currently pressed keys;rows_mut()andcolumns_mut()- mutable access to GPIO arrays;into_parts()- return rows, columns, and names.
ButtonMatrixEvents:
count()- number of events in the scan;is_empty()- true when no key changed;event_at(row, column)- event for one key if it changed;iter()- row-major iterator over all events.
Timing
scan(now_ms) accepts monotonic time in milliseconds. The timestamp must not go
backwards. The crate uses timestamp differences to:
- decide when a raw key state passed debounce;
- compute current hold time;
- compute final hold time on release.
The scanner does not block and does not delay internally. Call it regularly from the main loop, an RTOS task, or a timer.
Tests
Run tests:
cargo test
Run formatting and clippy checks:
cargo fmt --check
cargo clippy --all-targets -- -D warnings