# Copyright 2022, Basalte bv
# SPDX-License-Identifier: Apache-2.0

description: |
  SDL keyboard GPIO input Emulator

  Simulate GPIO state/interrupts using SDL keyboard events. This node has
  to be a child of a `zephyr,gpio-emul` compatible.
  Add a list of scancodes for the desired keys to be mapped.

  This driver uses USB HID scancodes, they are different from linux key codes,
  and thus do not match Zephyr code values as described in input-event-codes.h.
  Refer to https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
  section Keyboard/Keypad (p53) for a list of scancode values.

  The following example maps the first 3 numeric keys to GPIO pins:
  - Scancode 30: "Keyboard 1 and !", mapped to gpio0 0
  - Scancode 31: "Keyboard 2 and @", mapped to gpio0 1
  - Scancode 32: "Keyboard 3 and \#", mapped to gpio0 2

  The "typical position" column from HID table suggests to match them
  with standard keycode values 2, 3 and 4, corresponding to
  INPUT_KEY_1, INPUT_KEY_2 and INPUT_KEY_3 in input-event-codes.h.

  /* gpio0 has to be a zephyr,gpio-emul device */
  &gpio0 {
    ngpios = <3>;

    sdl_gpio {
      compatible = "zephyr,gpio-emul-sdl";
      scancodes = <30 31 32>;
    };
  };

  keypad: keypad {
    compatible = "gpio-keys";
    key1: key1 {
      gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
    };
    key2: key2 {
      gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
    };
    key3: key3 {
      gpios = <&gpio0 2 GPIO_ACTIVE_HIGH>;
    };
  };

  The limitations of usage are:
  - Only active high as we don't get events for keys that aren't pressed
  - Pressing multiple keys is best effort, state will be kept but no events
    are generated once the last key is released

compatible: "zephyr,gpio-emul-sdl"

include: base.yaml

properties:
  scancodes:
    type: array
    required: true
    description: |
      An array of SDL scancodes mapped to its GPIO index