driver/input: Add keyboard matrix driver to read matrix keyboard using polling way. #18368

FelipeMdeO · 2026-02-08T14:45:00Z

Note: Please adhere to Contributing Guidelines.

Summary

Add a generic keyboard matrix (kmatrix) lower-half driver with polling/debounce, plus an STM32 GPIO board adapter and public API to expose /dev/kbdN. Include a 4x3 keypad keymap example and documentation/test helper.
I2C interface to used keypad was done but not tested yet.
The IRQ feature will be done as soon as possible. This is a first step development.

This change solve this request: apache/nuttx-apps#1764

Please @acassis , help me to verify if I followed all standards.

Impact

Optional input driver; no behavior change unless enabled. Enabling kmatrix adds periodic GPIO scanning and keyboard events on /dev/kbd0.

Testing

Host: Ubuntu 24.04.3 LTS x86_64.
Board: STM32F4Discovery + 4x3 membrane keypad (GPIO). See picture of keypad used below:

Build: stm32f4discovery:nsh with:

CONFIG_INPUT=y
CONFIG_INPUT_KMATRIX=y
CONFIG_EXAMPLES_KEYBOARD=y
CONFIG_EXAMPLES_KEYBOARD_DEVPATH="/dev/kbd0"
CONFIG_INPUT_KMATRIX_POLL_MS=10 (default)
CONFIG_INPUT_KMATRIX_DEBOUNCE=3 (default)
CONFIG_INPUT_KMATRIX_BUFSIZE=64 (default)

Runtime: Ran kbd and observed key press/release events.
Logs:

nsh> kbd
kbd_main: nsamples: 0
kbd_main: Opening /dev/kbd0
Sample :
code : 49
type : 0
Sample :
code : 49
type : 1
Sample :
code : 50
type : 0
Sample :
code : 50
type : 1
Sample :
code : 51
type : 0
Sample :
code : 51
type : 1
Sample :
code : 52
type : 0
Sample :
code : 52
type : 1
Sample :
code : 53
type : 0
Sample :
code : 53
type : 1
Sample :
code : 54
type : 0
Sample :
code : 54
type : 1
Sample :
code : 55
type : 0
Sample :
code : 55
type : 1
Sample :
code : 56
type : 0
Sample :
code : 56
type : 1
Sample :
code : 57
type : 0
Sample :
code : 57
type : 1
Sample :
code : 42
type : 0
Sample :
code : 42
type : 1
Sample :
code : 48
type : 0
Sample :
code : 48
type : 1
Sample :
code : 35
type : 0
Sample :
code : 35
type : 1

boards/arm/stm32/common/src/stm32_kmatrix_gpio.c

acassis · 2026-02-08T15:01:36Z

drivers/input/kmatrix.c

+
+/* Format string for /dev/kbdN device */
+
+#define DEV_FORMAT      "/dev/kbd%d"


Suggestion: use /dev/keypad%d or similar, /dev/kdb%d is already used by real keyboard, not an big issue, but could have some incompatibilities (if it is a /dev/kbd0 for example, it should be 100% compatible with a real keyboard, including scanning encoding support)

Good catch, I will solve this.

acassis

@FelipeMdeO also since you are adding a new feature, we need Documentation/ to this matrix keyboard/keypad. Explain the purpose of this matrix keyboard, why it uses polling instead of interruptions, etc. Also drivers which functions a board needs to implement in order to support it (use the current stm32f4discovery implementation as reference)

FelipeMdeO · 2026-02-08T22:48:27Z

Hello @acassis , I don't know how to proceed with documentation.
I found the doc: https://nuttx.apache.org/docs/latest/components/drivers/character/input/keypad.html
But its seems not outdated.
Can you give some tips, please?

FelipeMdeO · 2026-02-09T02:18:04Z

I did a documentation, please check if it is enough.

michallenc

Nice work!

drivers/input/Make.defs

acassis · 2026-02-09T11:16:25Z

@FelipeMdeO you can add your kmatrix driver inside Documentation/components/drivers/character/input/

Yes, that documentation is very old and needs to be updated later.

Please create a Documentation giving context about your driver, what is its purpose, why is was created, how to add it to your board, etc.

The Documentation is written in ReStructuredText (similar to Markdown) and you can use this document to verify if everything is fine:
https://nuttx.apache.org/docs/latest/contributing/documentation.html

acassis

Very good @FelipeMdeO !!!
In your KMATRIX Documentation you can include that phone keypad to illustrate the idea ;-)

acassis · 2026-02-09T11:20:34Z

Documentation/components/drivers/character/input/keypad-keyboard.rst

+events into the text data stream. The function interfaces that
+comprise that encoding/decoding layer are defined in the header
+file ``include/nuttx/input/kbd_code.h``. These functions provide
+an matched set of (a) driver encoding interfaces, and (b)


Suggested change

an matched set of (a) driver encoding interfaces, and (b)

a matched set of (a) driver encoding interfaces, and (b)

acassis · 2026-02-09T11:28:52Z

I did a documentation, please check if it is enough.

Yes, your Documentation seems very good, I just suggested adding the keypad image after the title to illustrate the idea. Normally it makes the article more pleasant for someone reading the text.

Documentation/components/drivers/character/input/keypad.rst

Add a generic kmatrix lower-half with polling/debounce, STM32 board adapters, Kconfig options, a public API header, and a test example/documentation. Signed-off-by: Felipe Moura <[email protected]> decouple kbd / keypad. Fix some comments add documentation fix rule issues Update CMakeLists.txt update documentation. improve documentation

github-actions · 2026-02-09T19:35:32Z

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

acassis · 2026-02-09T19:42:09Z

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

I think we can ignore this warning. Probably some new rule to avoid big commits

FelipeMdeO requested review from GUIDINGLI, acassis, hartmannathan, jerpelea, masayuki2009, raiden00pl, simbit18 and xiaoxiang781216 as code owners February 8, 2026 14:45

github-actions bot added Arch: simulator Issues related to the SIMulator Area: Drivers Drivers issues Board: arm Board: simulator Size: XL The size of the change in this PR is very large. Consider breaking down the PR into smaller pieces. labels Feb 8, 2026

FelipeMdeO force-pushed the feature/kbd-driver branch 2 times, most recently from 8e7d651 to b9b64f9 Compare February 8, 2026 14:49

github-actions bot removed the Arch: simulator Issues related to the SIMulator label Feb 8, 2026

FelipeMdeO force-pushed the feature/kbd-driver branch from b9b64f9 to b078847 Compare February 8, 2026 14:52

github-actions bot removed the Board: simulator label Feb 8, 2026

FelipeMdeO force-pushed the feature/kbd-driver branch from b078847 to 4375fbc Compare February 8, 2026 14:53

acassis reviewed Feb 8, 2026

View reviewed changes

FelipeMdeO force-pushed the feature/kbd-driver branch from 4375fbc to 80a162a Compare February 8, 2026 15:01

acassis reviewed Feb 8, 2026

View reviewed changes

FelipeMdeO force-pushed the feature/kbd-driver branch from 80a162a to 50fed85 Compare February 8, 2026 15:12

acassis requested changes Feb 8, 2026

View reviewed changes

FelipeMdeO force-pushed the feature/kbd-driver branch 3 times, most recently from 0e7d5be to 88ffb4a Compare February 9, 2026 02:17

github-actions bot added the Area: Documentation Improvements or additions to documentation label Feb 9, 2026

FelipeMdeO requested a review from acassis February 9, 2026 02:18

FelipeMdeO force-pushed the feature/kbd-driver branch from 88ffb4a to 5a155b8 Compare February 9, 2026 02:24

jerpelea previously approved these changes Feb 9, 2026

View reviewed changes

michallenc requested changes Feb 9, 2026

View reviewed changes

drivers/input/Make.defs Show resolved Hide resolved

simbit18 reviewed Feb 9, 2026

View reviewed changes

drivers/input/Make.defs Show resolved Hide resolved

FelipeMdeO dismissed jerpelea’s stale review via b0b0ccd February 9, 2026 10:53

FelipeMdeO force-pushed the feature/kbd-driver branch from 5a155b8 to b0b0ccd Compare February 9, 2026 10:53

FelipeMdeO requested a review from michallenc February 9, 2026 10:56

michallenc previously approved these changes Feb 9, 2026

View reviewed changes

FelipeMdeO requested a review from simbit18 February 9, 2026 10:56

simbit18 previously approved these changes Feb 9, 2026

View reviewed changes

acassis reviewed Feb 9, 2026

View reviewed changes

FelipeMdeO dismissed stale reviews from simbit18 and michallenc via 58d5a51 February 9, 2026 17:27

FelipeMdeO force-pushed the feature/kbd-driver branch from b0b0ccd to 58d5a51 Compare February 9, 2026 17:27

FelipeMdeO requested a review from acassis February 9, 2026 17:27

acassis previously approved these changes Feb 9, 2026

View reviewed changes

Documentation/components/drivers/character/input/keypad.rst Show resolved Hide resolved

simbit18 previously approved these changes Feb 9, 2026

View reviewed changes

FelipeMdeO dismissed stale reviews from simbit18 and acassis via 652f764 February 9, 2026 19:34

FelipeMdeO force-pushed the feature/kbd-driver branch from 58d5a51 to 652f764 Compare February 9, 2026 19:34

acassis approved these changes Feb 9, 2026

View reviewed changes

FelipeMdeO requested review from jerpelea, michallenc and simbit18 February 9, 2026 21:33


		/* Format string for /dev/kbdN device */

		#define DEV_FORMAT "/dev/kbd%d"

	an matched set of (a) driver encoding interfaces, and (b)
	a matched set of (a) driver encoding interfaces, and (b)

driver/input: Add keyboard matrix driver to read matrix keyboard using polling way. #18368

Are you sure you want to change the base?

driver/input: Add keyboard matrix driver to read matrix keyboard using polling way. #18368

Uh oh!

Conversation

FelipeMdeO commented Feb 8, 2026

Summary

Impact

Testing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

acassis Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

FelipeMdeO Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

acassis left a comment

Choose a reason for hiding this comment

Uh oh!

FelipeMdeO commented Feb 8, 2026

Uh oh!

FelipeMdeO commented Feb 9, 2026

Uh oh!

michallenc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

acassis commented Feb 9, 2026

Uh oh!

acassis left a comment

Choose a reason for hiding this comment

Uh oh!

acassis Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

acassis commented Feb 9, 2026

Uh oh!

Uh oh!

github-actions bot commented Feb 9, 2026

Uh oh!

acassis commented Feb 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants