Custom Matrix
QMK provides a mechanism to supplement or replace the default matrix scanning routine with your own code.
The reasons to use this feature include:
  • Extra hardware between the keyboard's switches and MCU pins
    • I/O multiplexer
    • Line decoder
  • Irregular switch matrix
    • Simultaneous use of COL2ROW and ROW2COL

Prerequisites

Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called matrix.c.
Add a new file to your keyboard directory:
1
keyboards/<keyboard>/matrix.c
Copied!
And to configure compilation for the new file, add this to your rules.mk:
1
SRC += matrix.c
Copied!

'lite'

Provides a default implementation for various scanning functions, reducing the boilerplate code when implementing custom matrix. To configure it, add this to your rules.mk:
1
CUSTOM_MATRIX = lite
Copied!
And implement the following functions in a matrix.c file in your keyboard folder:
1
void matrix_init_custom(void) {
2
// TODO: initialize hardware here
3
}
4
5
bool matrix_scan_custom(matrix_row_t current_matrix[]) {
6
bool matrix_has_changed = false;
7
8
// TODO: add matrix scanning routine here
9
10
return matrix_has_changed;
11
}
Copied!

Full Replacement

When more control over the scanning routine is required, you can choose to implement the full scanning routine. To configure it, add this to your rules.mk:
1
CUSTOM_MATRIX = yes
Copied!
And implement the following functions in a matrix.c file in your keyboard folder:
1
matrix_row_t matrix_get_row(uint8_t row) {
2
// TODO: return the requested row data
3
}
4
5
void matrix_print(void) {
6
// TODO: use print() to dump the current matrix state to console
7
}
8
9
void matrix_init(void) {
10
// TODO: initialize hardware and global matrix state here
11
12
// Unless hardware debouncing - Init the configured debounce routine
13
debounce_init(MATRIX_ROWS);
14
15
// This *must* be called for correct keyboard behavior
16
matrix_init_quantum();
17
}
18
19
uint8_t matrix_scan(void) {
20
bool matrix_has_changed = false;
21
22
// TODO: add matrix scanning routine here
23
24
// Unless hardware debouncing - use the configured debounce routine
25
debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
26
27
// This *must* be called for correct keyboard behavior
28
matrix_scan_quantum();
29
30
return matrix_has_changed;
31
}
Copied!
And also provide defaults for the following callbacks:
1
__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
2
3
__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
4
5
__attribute__((weak)) void matrix_init_user(void) {}
6
7
__attribute__((weak)) void matrix_scan_user(void) {}
Copied!
Last modified 1yr ago