1 // Copyright 2020 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include <stdint.h> 18 #include "esp_err.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #define MAKE_KEY_CODE(row, col) ((row << 8) | (col)) 25 #define GET_KEY_CODE_ROW(code) ((code >> 8) & 0xFF) 26 #define GET_KEY_CODE_COL(code) (code & 0xFF) 27 28 /** 29 * @brief Type defined for matrix keyboard handle 30 * 31 */ 32 typedef struct matrix_kbd_t *matrix_kbd_handle_t; 33 34 /** 35 * @brief Matrix keyboard event ID 36 * 37 */ 38 typedef enum { 39 MATRIX_KBD_EVENT_DOWN, /*!< Key is pressed down */ 40 MATRIX_KBD_EVENT_UP /*!< Key is released */ 41 } matrix_kbd_event_id_t; 42 43 /** 44 * @brief Type defined for matrix keyboard event handler 45 * 46 * @note The event handler runs in a OS timer context 47 * 48 * @param[in] mkbd_handle Handle of matrix keyboard that return from `matrix_kbd_install` 49 * @param[in] event Event ID, refer to `matrix_kbd_event_id_t` to see all supported events 50 * @param[in] event_data Data for corresponding event 51 * @param[in] handler_args Arguments that user passed in from `matrix_kbd_register_event_handler` 52 * @return Currently always return ESP_OK 53 */ 54 typedef esp_err_t (*matrix_kbd_event_handler)(matrix_kbd_handle_t mkbd_handle, matrix_kbd_event_id_t event, void *event_data, void *handler_args); 55 56 /** 57 * @brief Configuration structure defined for matrix keyboard 58 * 59 */ 60 typedef struct { 61 const int *row_gpios; /*!< Array, contains GPIO numbers used by row line */ 62 const int *col_gpios; /*!< Array, contains GPIO numbers used by column line */ 63 uint32_t nr_row_gpios; /*!< row_gpios array size */ 64 uint32_t nr_col_gpios; /*!< col_gpios array size */ 65 uint32_t debounce_ms; /*!< Debounce time */ 66 } matrix_kbd_config_t; 67 68 /** 69 * @brief Default configuration for matrix keyboard driver 70 * 71 */ 72 #define MATRIX_KEYBOARD_DEFAULT_CONFIG() \ 73 { \ 74 .row_gpios = NULL, \ 75 .col_gpios = NULL, \ 76 .nr_row_gpios = 0, \ 77 .nr_col_gpios = 0, \ 78 .debounce_ms = 20, \ 79 } 80 81 /** 82 * @brief Install matrix keyboard driver 83 * 84 * @param[in] config Configuration of matrix keyboard driver 85 * @param[out] mkbd_handle Returned matrix keyboard handle if installation succeed 86 * @return 87 * - ESP_OK: Install matrix keyboard driver successfully 88 * - ESP_ERR_INVALID_ARG: Install matrix keyboard driver failed because of some invalid argument 89 * - ESP_ERR_NO_MEM: Install matrix keyboard driver failed because there's no enough capable memory 90 * - ESP_FAIL: Install matrix keyboard driver failed because of other error 91 */ 92 esp_err_t matrix_kbd_install(const matrix_kbd_config_t *config, matrix_kbd_handle_t *mkbd_handle); 93 94 /** 95 * @brief Uninstall matrix keyboard driver 96 * 97 * @param[in] mkbd_handle Handle of matrix keyboard that return from `matrix_kbd_install` 98 * @return 99 * - ESP_OK: Uninstall matrix keyboard driver successfully 100 * - ESP_ERR_INVALID_ARG: Uninstall matrix keyboard driver failed because of some invalid argument 101 * - ESP_FAIL: Uninstall matrix keyboard driver failed because of other error 102 */ 103 esp_err_t matrix_kbd_uninstall(matrix_kbd_handle_t mkbd_handle); 104 105 /** 106 * @brief Start matrix keyboard driver 107 * 108 * @param[in] mkbd_handle Handle of matrix keyboard that return from `matrix_kbd_install` 109 * @return 110 * - ESP_OK: Start matrix keyboard driver successfully 111 * - ESP_ERR_INVALID_ARG: Start matrix keyboard driver failed because of some invalid argument 112 * - ESP_FAIL: Start matrix keyboard driver failed because of other error 113 */ 114 esp_err_t matrix_kbd_start(matrix_kbd_handle_t mkbd_handle); 115 116 /** 117 * @brief Stop matrix kayboard driver 118 * 119 * @param[in] mkbd_handle Handle of matrix keyboard that return from `matrix_kbd_install` 120 * @return 121 * - ESP_OK: Stop matrix keyboard driver successfully 122 * - ESP_ERR_INVALID_ARG: Stop matrix keyboard driver failed because of some invalid argument 123 * - ESP_FAIL: Stop matrix keyboard driver failed because of other error 124 */ 125 esp_err_t matrix_kbd_stop(matrix_kbd_handle_t mkbd_handle); 126 127 /** 128 * @brief Register matrix keyboard event handler 129 * 130 * @param[in] mkbd_handle Handle of matrix keyboard that return from `matrix_kbd_install` 131 * @param[in] handler Event handler 132 * @param[in] args Arguments that will be passed to the handler 133 * @return 134 * - ESP_OK: Register event handler successfully 135 * - ESP_ERR_INVALID_ARG: Register event handler failed because of some invalid argument 136 * - ESP_FAIL: Register event handler failed because of other error 137 */ 138 esp_err_t matrix_kbd_register_event_handler(matrix_kbd_handle_t mkbd_handle, matrix_kbd_event_handler handler, void *args); 139 140 #ifdef __cplusplus 141 } 142 #endif 143
