import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.B9AX-CPi.js"; const __pageData = JSON.parse('{"title":"Custom Matrix","description":"","frontmatter":{},"headers":[],"relativePath":"custom_matrix.md","filePath":"custom_matrix.md"}'); const _sfc_main = { name: "custom_matrix.md" }; const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

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:

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:

keyboards/<keyboard>/matrix.c

And to configure compilation for the new file, add this to your rules.mk:

make
SRC += matrix.c

'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:

make
CUSTOM_MATRIX = lite

And implement the following functions in a matrix.c file in your keyboard folder:

c
void matrix_init_custom(void) {\n    // TODO: initialize hardware here\n}\n\nbool matrix_scan_custom(matrix_row_t current_matrix[]) {\n    bool matrix_has_changed = false;\n\n    // TODO: add matrix scanning routine here\n\n    return matrix_has_changed;\n}

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:

make
CUSTOM_MATRIX = yes

And implement the following functions in a matrix.c file in your keyboard folder:

c
matrix_row_t matrix_get_row(uint8_t row) {\n    // TODO: return the requested row data\n}\n\nvoid matrix_print(void) {\n    // TODO: use print() to dump the current matrix state to console\n}\n\nvoid matrix_init(void) {\n    // TODO: initialize hardware and global matrix state here\n\n    // Unless hardware debouncing - Init the configured debounce routine\n    debounce_init(MATRIX_ROWS);\n\n    // This *must* be called for correct keyboard behavior\n    matrix_init_kb();\n}\n\nuint8_t matrix_scan(void) {\n    bool changed = false;\n\n    // TODO: add matrix scanning routine here\n\n    // Unless hardware debouncing - use the configured debounce routine\n    changed = debounce(raw_matrix, matrix, MATRIX_ROWS, changed);\n\n    // This *must* be called for correct keyboard behavior\n    matrix_scan_kb();\n\n    return changed;\n}

And also provide defaults for the following callbacks:

c
__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }\n\n__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }\n\n__attribute__((weak)) void matrix_init_user(void) {}\n\n__attribute__((weak)) void matrix_scan_user(void) {}
', 22); const _hoisted_23 = [ _hoisted_1 ]; function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { return openBlock(), createElementBlock("div", null, _hoisted_23); } const custom_matrix = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); export { __pageData, custom_matrix as default };