keyboard_button.rst

Keyboard Scanning

:link_to_translation:`zh_CN:[中文]`

The Keyboard Scanning Component implements fast and efficient keyboard scanning, supporting key debouncing, key release and press event reporting, as well as combination keys.

This component uses matrix key row-column scanning and, through special circuit design, achieves full-key rollover circuit detection.

• In this circuit, rows output high-level signals sequentially, detecting whether columns have high-level signals. If they do, it indicates the key is pressed.

Note

• Since the logic of this component does not involve swapping row-column scanning, it is not suitable for traditional row-column scanning circuits and is only applicable to full-key rollover circuits for keyboards.

Component Events

• :cpp:enumerator:`KBD_EVENT_PRESSED`: Reports data when there is a change in key states.

  • key_pressed_num: Number of keys pressed.
  • key_release_num: Number of keys released.
  • key_change_num: Number of keys with changed states compared to the previous state. >0 indicates an increase in pressed keys, <0 indicates a decrease.
  • key_data: Information of the currently pressed keys, with positions (x, y). Indexed in the order they were pressed, with smaller indexes being pressed earlier.
  • key_release_data: Information of keys released compared to the previous state, with positions (x, y).

• :cpp:enumerator:`KBD_EVENT_COMBINATION`: Combination key event. Triggered when a combination key is pressed.

  • key_num: Number of keys in the combination.
  • key_data: Position information of the combination keys. For setting a combination key (1,1) and (2,2), (1,1) must be pressed first followed by (2,2) to trigger the combination key event. Combination keys only trigger with increasing combinations.

Application Example

Initializing Keyboard Scanning

keyboard_btn_config_t cfg = {
    .output_gpios = (int[])
    {
        40, 39, 38, 45, 48, 47
    },
    .output_gpio_num = 6,
    .input_gpios = (int[])
    {
        21, 14, 13, 12, 11, 10, 9, 4, 5, 6, 7, 15, 16, 17, 18
    },
    .input_gpio_num = 15,
    .active_level = 1,
    .debounce_ticks = 2,
    .ticks_interval = 500,      // us
    .enable_power_save = false, // enable power save
};
keyboard_btn_handle_t kbd_handle = NULL;
keyboard_button_create(&cfg, &kbd_handle);

Registering Callback Functions

• Registration of KBD_EVENT_PRESSED event is as follows:

keyboard_btn_cb_config_t cb_cfg = {
    .event = KBD_EVENT_PRESSED,
    .callback = keyboard_cb,
};
keyboard_button_register_cb(kbd_handle, cb_cfg, NULL);

• Registration of KBD_EVENT_COMBINATION event requires passing combination key information through the combination member:

keyboard_btn_cb_config_t cb_cfg = {
    .event = KBD_EVENT_COMBINATION,
    .callback = keyboard_combination_cb1,
    .event_data.combination.key_num = 2,
    .event_data.combination.key_data = (keyboard_btn_data_t[]) {
        {5, 1},
        {1, 1},
    },
};

keyboard_button_register_cb(kbd_handle, cb_cfg, NULL);

Note

Additionally, multiple callbacks can be registered for each event. When registering multiple callbacks, it's recommended to save keyboard_btn_cb_handle_t *rtn_cb_hdl for later unbinding of specific callbacks.

Key Scanning Efficiency

• Testing with ESP32S3 chip scanning a 5*16 matrix keyboard, the maximum scanning rate can reach 20K.

Low Power Support

• Set enable_power_save to true during initialization to activate the low-power mode. In this mode, key scanning is suspended when no key changes occur, allowing the CPU to enter a sleep state. The CPU wakes up when a key is pressed.

Note

This feature only ensures that it does not occupy the CPU; it does not guarantee that the CPU will necessarily enter low-power mode. Currently, only Light Sleep mode is supported.

API Reference

.. include-build-file:: inc/keyboard_button.inc