键盘扫描

[English]

键盘扫描组件实现了快速高效的键盘扫描，支持按键消抖，按键松开按下事件上报，以及组合键。

该组件采用了矩阵按键的行列扫描，通过特殊的电路设计，实现了全键无冲的电路检测。

此电路中，行依次输出高电平，检测列是否有高电平，如果有，则表示该按键被按下。

备注

由于该组件逻辑并不会交换行列扫描，所以不适用于传统的行列扫描电路，只适用于键盘的全键无冲电路。

组件事件

KBD_EVENT_PRESSED: 当有按键状态变化时，上报数据。
- key_pressed_num: 按键按下的数量。
- key_release_num: 按键松开的数量。
- key_change_num: 和上一次状态相比，状态变化的按键数量。>0 按下按键增加，<0 按下按键减少。
- key_data: 当前按下的按键信息，按下按键的位置（x, y）, 索引从小到大为按下的顺序，索引越小越早按下
- key_release_data: 和上一次相比松开的按键信息，松开按键的位置（x, y）。
KBD_EVENT_COMBINATION: 组合按键事件，当组合键被按下时，触发回调。
- key_num: 组合按键的数量
- key_data: 组合按键的位置信息，如设置组合键（1，1）（2，2），那么必须先按下（1，1）再按下（2，2）才会触发组合按键事件。组合按键只触发正向增长的组合键。

应用示例

初始化键盘扫描

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);

注册回调函数

KBD_EVENT_PRESSED 事件的注册如下

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

KBD_EVENT_COMBINATION 事件的注册如下，需要传递组合键的信息通过 combination 成员

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);

备注

此外事件都支持注册多个回调，在注册多个回调时，最好保存 keyboard_btn_cb_handle_t *rtn_cb_hdl 以方便后续解绑指定回调。

按键扫描效率

测试使用 ESP32S3 芯片扫描 5*16 的矩阵键盘，最大扫描速率可达 20K。

低功耗支持

在初始化时将 enable_power_save 设置为 true, 即可开启低功耗模式，此模式将在没有按键改变的时候不进行按键扫描，CPU 同时进入休眠状态，在有按键按下时唤醒 CPU。

备注

该功能只保证不占用 CPU, 不保证 CPU 一定会进入低功耗模式。且目前只支持 Light Sleep 模式。

API Reference

Header File

components/keyboard_button/include/keyboard_button.h

Functions

esp_err_t keyboard_button_create(keyboard_btn_config_t *kbd_cfg, keyboard_btn_handle_t *kbd_handle)

Create a keyboard instance.

参数

kbd_cfg – keyboard configuration
kbd_handle – keyboard handle

返回

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is invalid.
ESP_ERR_NO_MEM No more memory allocation.

esp_err_t keyboard_button_delete(keyboard_btn_handle_t kbd_handle)

Delete the keyboard instance.

参数

kbd_handle – keyboard handle

返回

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is invalid.

esp_err_t keyboard_button_register_cb(keyboard_btn_handle_t kbd_handle, keyboard_btn_cb_config_t cb_cfg, keyboard_btn_cb_handle_t *rtn_cb_hdl)

Register the button callback function.

参数

kbd_handle – keyboard handle
cb_cfg – callback configuration
rtn_cb_hdl – callback handle for unregister

返回

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is invalid.
ESP_ERR_NO_MEM No more memory allocation for the event

esp_err_t keyboard_button_unregister_cb(keyboard_btn_handle_t kbd_handle, keyboard_btn_event_t event, keyboard_btn_cb_handle_t rtn_cb_hdl)

Unregister the button callback function.

备注

If only the event is provided, all callbacks associated with this event will be canceled. If rtn_cb_hdl is provided, only the specified callback will be unregistered.

参数

kbd_handle – keyboard handle
event – event type
rtn_cb_hdl – callback handle for unregister

返回

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is invalid.
ESP_ERR_NO_MEM No more memory allocation for the event

esp_err_t keyboard_button_get_index_by_gpio(keyboard_btn_handle_t kbd_handle, uint32_t gpio_num, kbd_gpio_mode_t gpio_mode, uint32_t *index)

Get index by gpio number.

参数

kbd_handle – keyboard handle
gpio_num – gpio number
gpio_mode – gpio mode, input or output
index – return index

返回

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is invalid.
ESP_ERR_NOT_FOUND The gpio number is not found.

esp_err_t keyboard_button_get_gpio_by_index(keyboard_btn_handle_t kbd_handle, uint32_t index, kbd_gpio_mode_t gpio_mode, uint32_t *gpio_num)

Get gpio number by index.

参数

kbd_handle – keyboard handle
index – index
gpio_mode – gpio mode, input or output
gpio_num – return gpio number

返回

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is invalid.
ESP_ERR_NOT_FOUND The index is not found.

Unions

union keyboard_btn_event_data_t

#include <keyboard_button.h>

keyboard button event data

Public Members

struct keyboard_btn_event_data_t::combination_t combination: combination event

struct combination_t

#include <keyboard_button.h>

combination event data eg: Set key_data = {(1,1), (2,2)} means that the button sequence is (1,1) -> (2,2)

Public Members

uint32_t key_num: Number of keys

keyboard_btn_data_t *key_data: Array, contains key codes by index. The button sequence is also provided through this

Structures

struct keyboard_btn_data_t

keyboard button data

Public Members

uint8_t output_index: key position’s output gpio number

uint8_t input_index: key position’s input gpio number

struct keyboard_btn_report_t

keyboard button report data

Public Members

int key_change_num: Number of key changes

uint32_t key_pressed_num: Number of keys pressed

uint32_t key_release_num: Number of keys released

keyboard_btn_data_t *key_data: Array, contains key codes

keyboard_btn_data_t *key_release_data: Array, contains key codes

struct keyboard_btn_cb_config_t

keyboard button callback config

Public Members

keyboard_btn_event_t event: Event type

keyboard_btn_event_data_t event_data: Event data

keyboard_btn_callback_t callback: Callback function

void *user_data: Callback user data

struct keyboard_btn_config_t

keyboard button config

Public Members

const int *output_gpios: Array, contains output GPIO numbers used by rom/col line

const int *input_gpios: Array, contains input GPIO numbers used by rom/col line

uint32_t output_gpio_num: output_gpios array size

uint32_t input_gpio_num: input_gpios array size

uint32_t active_level: active level for the input gpios

uint32_t debounce_ticks: debounce time in ticks

uint32_t ticks_interval: interval time in us

bool enable_power_save: enable power save mode

UBaseType_t priority: FreeRTOS task priority

BaseType_t core_id: ESP32 core ID

Type Definitions

typedef struct keyboard_btn_t *keyboard_btn_handle_t: keyboard handle type

typedef void *keyboard_btn_cb_handle_t: keyboard callback handle for unregister

typedef void (*keyboard_btn_callback_t)(keyboard_btn_handle_t kbd_handle, keyboard_btn_report_t kbd_report, void *user_data)

Enumerations

enum keyboard_btn_event_t

Keyboard button event.

Values:

enumerator KBD_EVENT_PRESSED: Report all currently pressed keys when a key is either pressed or released.

enumerator KBD_EVENT_COMBINATION: When the component buttons are pressed in sequence, report.

enumerator KBD_EVENT_MAX

提供有关此文档的反馈