Documentation/devicetree/bindings/input/gpio-charlieplex-keypad.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---

$id: http://devicetree.org/schemas/input/gpio-charlieplex-keypad.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: GPIO charlieplex keypad

maintainers:
  - Hugo Villeneuve <hvilleneuve@dimonoff.com>

description: |
  The charlieplex keypad supports N^2)-N different key combinations (where N is
  the number of I/O lines). Key presses and releases are detected by configuring
  only one line as output at a time, and reading other line states. This process
  is repeated for each line. Diodes are required to ensure current flows in only
  one direction between any pair of pins, as well as pull-up or pull-down
  resistors on all I/O lines.
  This mechanism doesn't allow to detect simultaneous key presses.

  Wiring example for 3 lines keyboard with 6 switches and 3 diodes (pull-up/down
  resistors not shown but needed on L0, L1 and L2):

  L0  --+---------------------+----------------------+
        |                     |                      |
  L1  -------+-----------+---------------------+     |
        |    |           |    |                |     |
  L2  -------------+----------------+-----+    |     |
        |    |     |     |    |     |     |    |     |
        |    |     |     |    |     |     |    |     |
        |  S1 \  S2 \    |  S3 \  S4 \    |  S5 \  S6 \
        |    |     |     |    |     |     |    |     |
        |    +--+--+     |    +--+--+     |    +--+--+
        |       |        |       |        |       |
        |    D1 v        |    D2 v        |    D3 v
        |       - (k)    |       - (k)    |       - (k)
        |       |        |       |        |       |
        +-------+        +-------+        +-------+

  L: GPIO line
  S: switch
  D: diode (k indicates cathode)

allOf:
  - $ref: input.yaml#
  - $ref: /schemas/input/matrix-keymap.yaml#

properties:
  compatible:
    const: gpio-charlieplex-keypad

  autorepeat: true

  debounce-delay-ms:
    default: 5

  line-gpios:
    description:
      List of GPIOs used as lines. The gpio specifier for this property
      depends on the gpio controller to which these lines are connected.

  linux,keymap: true

  poll-interval: true

  settling-time-us: true

  wakeup-source: true

required:
  - compatible
  - line-gpios
  - linux,keymap
  - poll-interval

additionalProperties: false

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/input/input.h>

    keyboard {
        compatible = "gpio-charlieplex-keypad";
        debounce-delay-ms = <20>;
        poll-interval = <5>;
        settling-time-us = <2>;

        line-gpios = <&gpio2 25 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)
                      &gpio2 26 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)
                      &gpio2 27 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>;

        /* MATRIX_KEY(output, input, key-code) */
        linux,keymap = <
            /*
             * According to wiring diagram above, if L1 is configured as
             * output and HIGH, and we detect a HIGH level on input L0,
             * then it means S1 is pressed: MATRIX_KEY(L1, L0, KEY...)
             */
            MATRIX_KEY(1, 0, KEY_F1) /* S1 */
            MATRIX_KEY(2, 0, KEY_F2) /* S2 */
            MATRIX_KEY(0, 1, KEY_F3) /* S3 */
            MATRIX_KEY(2, 1, KEY_F4) /* S4 */
            MATRIX_KEY(1, 2, KEY_F5) /* S5 */
            MATRIX_KEY(0, 2, KEY_F6) /* S6 */
        >;
    };