|
1 | 1 | ======================= |
2 | | -Keyboard/Keypad Drivers |
| 2 | +Matrix Keypad (KMATRIX) |
3 | 3 | ======================= |
4 | 4 |
|
5 | | -**Keypads vs. Keyboards** Keyboards and keypads are really the |
6 | | -same devices for NuttX. A keypad is thought of as simply a |
7 | | -keyboard with fewer keys. |
8 | | - |
9 | | -**Special Commands**. In NuttX, a keyboard/keypad driver is simply |
10 | | -a character driver that may have an (optional) encoding/decoding |
11 | | -layer on the data returned by the character driver. A keyboard may |
12 | | -return simple text data (alphabetic, numeric, and punctuation) or |
13 | | -control characters (enter, control-C, etc.) when a key is pressed. |
14 | | -We can think about this the "normal" keyboard data stream. |
15 | | -However, in addition, most keyboards support actions that cannot |
16 | | -be represented as text or control data. Such actions include |
17 | | -things like cursor controls (home, up arrow, page down, etc.), |
18 | | -editing functions (insert, delete, etc.), volume controls, (mute, |
19 | | -volume up, etc.) and other special functions. In this case, some |
20 | | -special encoding may be required to multiplex the normal text data |
21 | | -and special command key press data streams. |
22 | | - |
23 | | -**Key Press and Release Events** Sometimes the time that a key is |
24 | | -released is needed by applications as well. Thus, in addition to |
25 | | -normal and special key press events, it may also be necessary to |
26 | | -encode normal and special key release events. |
27 | | - |
28 | | -**Encoding/Decoding** Layer. An optional encoding/decoding layer |
29 | | -can be used with the basic character driver to encode the keyboard |
30 | | -events into the text data stream. The function interfaces that |
31 | | -comprise that encoding/decoding layer are defined in the header |
32 | | -file ``include/nuttx/input/kbd_code.h``. These functions provide |
33 | | -an matched set of (a) driver encoding interfaces, and (b) |
34 | | -application decoding interfaces. |
35 | | - |
36 | | -#. **Driver Encoding Interfaces**. These are interfaces used by |
37 | | - the keyboard/keypad driver to encode keyboard events and data. |
38 | | - |
39 | | - - ``kbd_press()`` |
40 | | - |
41 | | - **Function Prototype:** |
42 | | - |
43 | | - **Description:** |
44 | | - |
45 | | - **Input Parameters:** |
46 | | - |
47 | | - - ``ch``: The character to be added to the output stream. |
48 | | - - ``stream``: An instance of ``lib_outstream_s`` to perform |
49 | | - the actual low-level put operation. |
50 | | - |
51 | | - **Returned Value:** |
52 | | - |
53 | | - - ``kbd_release()`` |
54 | | - |
55 | | - **Function Prototype:** |
56 | | - |
57 | | - **Description:** |
58 | | - |
59 | | - **Input Parameters:** |
60 | | - |
61 | | - - ``ch``: The character associated with the key that was |
62 | | - released. |
63 | | - - ``stream``: An instance of ``lib_outstream_s`` to perform |
64 | | - the actual low-level put operation. |
65 | | - |
66 | | - **Returned Value:** |
67 | | - |
68 | | - - ``kbd_specpress()`` |
69 | | - |
70 | | - **Function Prototype:** |
71 | | - |
72 | | - **Description:** |
73 | | - |
74 | | - **Input Parameters:** |
75 | | - |
76 | | - - ``keycode``: The command to be added to the output |
77 | | - stream. The enumeration ``enum kbd_keycode_e keycode`` |
78 | | - identifies all commands known to the system. |
79 | | - - ``stream``: An instance of ``lib_outstream_s`` to perform |
80 | | - the actual low-level put operation. |
81 | | - |
82 | | - **Returned Value:** |
83 | | - |
84 | | - - ``kbd_specrel()`` |
85 | | - |
86 | | - **Function Prototype:** |
87 | | - |
88 | | - **Description:** |
89 | | - |
90 | | - **Input Parameters:** |
91 | | - |
92 | | - - ``keycode``: The command to be added to the output |
93 | | - stream. The enumeration ``enum kbd_keycode_e keycode`` |
94 | | - identifies all commands known to the system. |
95 | | - - ``stream``: An instance of ``lib_outstream_s`` to perform |
96 | | - the actual low-level put operation. |
97 | | - |
98 | | - **Returned Value:** |
99 | | - |
100 | | -#. **Application Decoding Interfaces**. These are user interfaces |
101 | | - to decode the values returned by the keyboard/keypad driver. |
102 | | - |
103 | | - - ``kbd_decode()`` |
104 | | - |
105 | | - **Function Prototype:** |
106 | | - |
107 | | - **Description:** |
108 | | - |
109 | | - **Input Parameters:** |
110 | | - |
111 | | - - ``stream``: An instance of ``lib_instream_s`` to perform |
112 | | - the actual low-level get operation. |
113 | | - - ``pch``: The location to save the returned value. This |
114 | | - may be either a normal, character code or a special |
115 | | - command (i.e., a value from ``enum kbd_getstate_s``. |
116 | | - - ``state``: A user provided buffer to support parsing. |
117 | | - This structure should be cleared the first time that |
118 | | - ``kbd_decode()`` is called. |
119 | | - |
120 | | - **Returned Value:** |
121 | | - |
122 | | - - ``KBD_PRESS`` (0)**: Indicates the successful receipt |
123 | | - of normal, keyboard data. This corresponds to a keypress |
124 | | - event. The returned value in ``pch`` is a simple byte of |
125 | | - text or control data. |
126 | | - - ``KBD_RELEASE`` (1)**: Indicates a key release event. |
127 | | - The returned value in ``pch`` is the byte of text or |
128 | | - control data corresponding to the released key. |
129 | | - - ``KBD_SPECPRESS`` (2)**: Indicates the successful |
130 | | - receipt of a special keyboard command. The returned value |
131 | | - in ``pch`` is a value from ``enum kbd_getstate_s``. |
132 | | - - ``KBD_SPECREL`` (3)**: Indicates a special command key |
133 | | - release event. The returned value in ``pch`` is a value |
134 | | - from ``enum kbd_getstate_s``. |
135 | | - - ``KBD_ERROR`` (``EOF``)**: An error has getting the |
136 | | - next character (reported by the ``stream``). Normally |
137 | | - indicates the end of file. |
138 | | - |
139 | | -**I/O Streams**. Notice the use of the abstract I/O streams in |
140 | | -these interfaces. These stream interfaces are defined in |
141 | | -``include/nuttx/streams.h``. |
| 5 | +**What is a Keypad?** |
| 6 | +A keypad is a small keyboard with a limited set of keys, typically |
| 7 | +arranged in a matrix. It is commonly used for numeric input, access |
| 8 | +control, or simple user interfaces. |
| 9 | + |
| 10 | +For example, a typical 12-key numeric keypad looks like this: |
| 11 | + |
| 12 | +.. image:: images/keypad-example.png |
| 13 | + :alt: Example of a 12-key matrix keypad |
| 14 | + :align: center |
| 15 | + :width: 200px |
| 16 | + |
| 17 | +**Purpose**. The KMATRIX driver provides a generic keypad |
| 18 | +implementation for boards that expose a switch matrix through GPIOs. |
| 19 | +It periodically scans rows and columns, detects state changes with a |
| 20 | +simple debounce, and emits keyboard events through the common keyboard |
| 21 | +upper-half. This makes the device available as a character driver |
| 22 | +(e.g., ``/dev/keypad0``) using the standard keyboard |
| 23 | +interfaces. |
| 24 | + |
| 25 | +**Why Polling**. This first version uses polling to be broadly usable |
| 26 | +on any board with available GPIOs, without requiring per-board IRQ |
| 27 | +wiring, pin interrupt capabilities, or expander-specific interrupt |
| 28 | +support. Polling also simplifies early bring-up and makes the driver |
| 29 | +predictable while the keymap and GPIO configuration are validated. |
| 30 | +Future iterations are expected to add interrupt-driven scanning and |
| 31 | +I2C expander variants; the GPIO polling path remains a good baseline |
| 32 | +and fallback. |
| 33 | + |
| 34 | +**Driver Overview**. The KMATRIX lower-half scans the matrix and calls |
| 35 | +``keyboard_event()`` when it detects a press or release. The keyboard |
| 36 | +upper-half registers the character device at the requested ``devpath`` |
| 37 | +and stores events in a circular buffer. Applications read |
| 38 | +``struct keyboard_event_s`` from the device or use the optional |
| 39 | +kbd-codec layer. |
| 40 | + |
| 41 | +**Board Support**. To support KMATRIX, a board must provide: |
| 42 | + |
| 43 | +#. **GPIO Definitions** |
| 44 | + |
| 45 | + - Define the row and column GPIOs (arrays of pins). |
| 46 | + - Provide a keymap array indexed by ``row * ncols + col``. |
| 47 | + |
| 48 | +#. **Configuration Callbacks** |
| 49 | + |
| 50 | + - ``config_row(pin)``: Configure a row GPIO as output. |
| 51 | + - ``config_col(pin)``: Configure a column GPIO as input with pull-up |
| 52 | + or pull-down consistent with the wiring. |
| 53 | + - ``row_set(pin, active)``: Drive a row active/inactive. For the |
| 54 | + STM32F4Discovery example, rows are driven low to activate. |
| 55 | + - ``col_get(pin)``: Read a column and return ``true`` when pressed. |
| 56 | + |
| 57 | +#. **Registration Hook** |
| 58 | + |
| 59 | + - Implement ``board_kmatrix_initialize(const char *devpath)`` to |
| 60 | + call ``kmatrix_register(&config, devpath)``. |
| 61 | + - Invoke the board hook during bring-up (for example, |
| 62 | + ``board_kmatrix_initialize("/dev/keypad0")``). |
| 63 | + |
| 64 | +**Reference Implementation (STM32F4Discovery)**. The current reference |
| 65 | +is in ``boards/arm/stm32/common/src/stm32_kmatrix_gpio.c``: |
| 66 | + |
| 67 | +- Rows: ``BOARD_KMATRIX_ROW0..3`` (outputs) |
| 68 | +- Columns: ``BOARD_KMATRIX_COL0..2`` (inputs with pull-up) |
| 69 | +- Keymap: 4x3 phone keypad layout |
| 70 | +- Callbacks: ``km_stm32_config_row``, ``km_stm32_config_col``, |
| 71 | + ``km_stm32_row_set``, ``km_stm32_col_get`` |
| 72 | +- Registration: ``board_kmatrix_initialize()`` calls |
| 73 | + ``kmatrix_register()`` |
| 74 | + |
| 75 | +**Data Path Summary**. |
| 76 | + |
| 77 | +- Board calls ``board_kmatrix_initialize("/dev/keypad0")`` |
| 78 | +- ``kmatrix_register()`` configures GPIOs and calls |
| 79 | + ``keyboard_register(&lower, devpath, buflen)`` |
| 80 | +- The upper-half registers the device node at ``devpath`` |
| 81 | +- ``kmatrix_scan_worker()`` calls ``keyboard_event()`` on press/release |
| 82 | +- Applications read events from the device node |
142 | 83 |
|
0 commit comments