71 lines
3.2 KiB
C
71 lines
3.2 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
#pragma once
|
|
|
|
#include "esp_err.h"
|
|
#include "button_types.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Button matrix key configuration.
|
|
* Just need to configure the GPIO associated with this GPIO in the matrix keyboard.
|
|
*
|
|
* Matrix Keyboard Layout (3x3):
|
|
* ----------------------------------------
|
|
* | Button 1 | Button 2 | Button 3 |
|
|
* | (R1-C1) | (R1-C2) | (R1-C3) |
|
|
* |--------------------------------------|
|
|
* | Button 4 | Button 5 | Button 6 |
|
|
* | (R2-C1) | (R2-C2) | (R2-C3) |
|
|
* |--------------------------------------|
|
|
* | Button 7 | Button 8 | Button 9 |
|
|
* | (R3-C1) | (R3-C2) | (R3-C3) |
|
|
* ----------------------------------------
|
|
*
|
|
* - Button matrix key is driven using row scanning.
|
|
* - Buttons within the same column cannot be detected simultaneously,
|
|
* but buttons within the same row can be detected without conflicts.
|
|
*/
|
|
typedef struct {
|
|
int32_t *row_gpios; /**< GPIO number list for the row */
|
|
int32_t *col_gpios; /**< GPIO number list for the column */
|
|
uint32_t row_gpio_num; /**< Number of GPIOs associated with the row */
|
|
uint32_t col_gpio_num; /**< Number of GPIOs associated with the column */
|
|
} button_matrix_config_t;
|
|
|
|
/**
|
|
* @brief Create a new button matrix device
|
|
*
|
|
* This function initializes and configures a button matrix device using the specified row and column GPIOs.
|
|
* Each button in the matrix is represented as an independent button object, and its handle is returned in the `ret_button` array.
|
|
*
|
|
* @param[in] button_config Configuration for the button device, including callbacks and debounce parameters.
|
|
* @param[in] matrix_config Configuration for the matrix, including row and column GPIOs and their counts.
|
|
* @param[out] ret_button Array of handles for the buttons in the matrix.
|
|
* @param[inout] size Pointer to the total number of buttons in the matrix. Must match the product of row and column GPIO counts.
|
|
* On success, this value is updated to reflect the size of the button matrix.
|
|
*
|
|
* @return
|
|
* - ESP_OK: Successfully created the button matrix device.
|
|
* - ESP_ERR_INVALID_ARG: Invalid argument provided, such as null pointers or mismatched matrix dimensions.
|
|
* - ESP_ERR_NO_MEM: Memory allocation failed.
|
|
* - ESP_FAIL: General failure, such as button creation failure for one or more buttons.
|
|
*
|
|
* @note
|
|
* - Each row GPIO is configured as an output, while each column GPIO is configured as an input.
|
|
* - The total number of buttons in the matrix must equal the product of the row and column GPIO counts.
|
|
* - The `ret_button` array must be large enough to store handles for all buttons in the matrix.
|
|
* - If any button creation fails, the function will free all allocated resources and return an error.
|
|
*/
|
|
esp_err_t iot_button_new_matrix_device(const button_config_t *button_config, const button_matrix_config_t *matrix_config, button_handle_t *ret_button, size_t *size);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|