Lines Matching +full:gpio +full:- +full:kbd +full:- +full:matrix
1 .. _gpio-kbd:
3 GPIO Keyboard Matrix
6 The :dtcompatible:`gpio-kbd-matrix` driver supports a large variety of keyboard
7 matrix hardware configurations and has numerous options to change its behavior.
21 .. figure:: no-diodes.svg
25 A 3x3 matrix, no diodes
27 The system must support GPIO interrupts, and the interrupt can be enabled on all
30 .. code-block:: devicetree
32 kbd-matrix {
33 compatible = "gpio-kbd-matrix";
34 row-gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
37 col-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
42 In this configuration the matrix scanning library enters idle mode once all
43 keys are released, and the keyboard matrix thread only wakes up when a key has
49 time can be tweaked by changing the ``settle-time-us`` property.
54 If the matrix has isolation diodes for every key, then it's possible to:
56 - disable ghosting detection, allowing any key combination to be detected
57 - configuring the driver to drive unselected columns GPIO to inactive state
59 (potentially down to 0), and use the more efficient port wide GPIO read APIs
60 (happens automatically if the GPIO pins are sequential)
62 Matrixes with diodes going from rows to columns must use pull-ups on rows and
65 .. figure:: diodes-rc.svg
69 A 3x3 matrix with row to column isolation diodes.
71 .. code-block:: devicetree
73 kbd-matrix {
74 compatible = "gpio-kbd-matrix";
75 row-gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
78 col-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
81 col-drive-inactive;
82 settle-time-us = <0>;
83 no-ghostkey-check;
86 Matrixes with diodes going from columns to rows must use pull-downs on rows and
89 .. figure:: diodes-cr.svg
93 A 3x3 matrix with column to row isolation diodes.
95 .. code-block:: devicetree
97 kbd-matrix {
98 compatible = "gpio-kbd-matrix";
99 row-gpios = <&gpio0 0 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>,
102 col-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>,
105 col-drive-inactive;
106 settle-time-us = <0>;
107 no-ghostkey-check;
110 GPIO with no interrupt support
113 Some GPIO controllers have limitations on GPIO interrupts, and may not support
118 is a single GPIO API operation if the pins are sequential.
120 This configuration can be enabled by setting the ``idle-mode`` property to
123 .. code-block:: devicetree
125 kbd-matrix {
126 compatible = "gpio-kbd-matrix";
128 idle-mode = "poll";
131 GPIO multiplexer
138 This can be done by setting ``idle-mode`` to ``scan`` and ``poll-timeout-ms``
141 .. code-block:: devicetree
143 kbd-matrix {
144 compatible = "gpio-kbd-matrix";
146 poll-timeout-ms = <0>;
147 idle-mode = "scan";
150 Row and column GPIO selection
153 If the row GPIOs are sequential and on the same gpio controller, the driver
154 automatically switches API to read from the whole GPIO port rather than the
159 The same is true for column GPIOs, but only if the matrix is configured for
160 ``col-drive-inactive``, so that is only usable for matrixes with isolation
163 16-bit row support
166 The driver uses an 8-bit datatype to store the row state by default, which
167 limits the matrix row size to 8. This can be increased to 16 by enabling the
173 If the key matrix is not complete, a map of the keys that are actually
174 populated can be specified using the ``actual-key-mask`` property. This allows
175 the matrix state to be filtered to remove keys that are not present before
179 For example for a 3x3 matrix missing a key:
181 .. figure:: no-sw4.svg
185 A 3x3 matrix missing a key.
187 .. code-block:: devicetree
189 kbd-matrix {
190 compatible = "gpio-kbd-matrix";
192 actual-key-mask = <0x07 0x05 0x07>;
205 Keyboard matrix devices report a series of x/y/touch events. These can be
206 mapped to normal key events using the :dtcompatible:`input-keymap` driver.
212 .. code-block:: devicetree
214 kbd {
217 compatible = "input-keymap";
229 row-size = <3>;
230 col-size = <3>;
234 Keyboard matrix shell commands
238 functionality of any keyboard matrix driver implemented using the keyboard
239 matrix library. Once enabled it logs the state of the matrix every time it
240 changes, and once disabled it prints an or-mask of any key that has been
241 detected, which can be used to set the ``actual-key-mask`` property.
248 .. code-block:: console
252 - kbd-matrix (READY)
253 uart:~$ input kbd_matrix_state_dump kbd-matrix
254 Keyboard state logging enabled for kbd-matrix
255 [00:01:41.678,466] <inf> input: kbd-matrix state [01 -- -- --] (1)
256 [00:01:41.784,912] <inf> input: kbd-matrix state [-- -- -- --] (0)
262 [00:01:47.967,651] <inf> input: kbd-matrix key-mask [07 05 07 --] (8)
264 Keyboard matrix library
267 The GPIO keyboard matrix driver is based on a generic keyboard matrix library,
269 idle mode etc. This can be reused to implement other keyboard matrix drivers,