/* * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once #include "touch_element/touch_element.h" #ifdef __cplusplus extern "C" { #endif /* ----------------------------- General matrix button instance default configuration ------------------------------ */ #define TOUCH_MATRIX_GLOBAL_DEFAULT_CONFIG() \ { \ .threshold_divider = 0.8, \ .default_lp_time = 1000 \ } /* ------------------------------------------------------------------------------------------------------------------ */ /** * @brief Matrix button initialization configuration passed to touch_matrix_install */ typedef struct { float threshold_divider; //!< Matrix button channel threshold divider uint32_t default_lp_time; //!< Matrix button default LongPress event time (ms) } touch_matrix_global_config_t; /** * @brief Matrix button configuration (for new instance) passed to touch_matrix_create() */ typedef struct { const touch_pad_t *x_channel_array; //!< Matrix button x-axis channels array const touch_pad_t *y_channel_array; //!< Matrix button y-axis channels array const float *x_sensitivity_array; //!< Matrix button x-axis channels sensitivity array const float *y_sensitivity_array; //!< Matrix button y-axis channels sensitivity array uint8_t x_channel_num; //!< The number of channels in x-axis uint8_t y_channel_num; //!< The number of channels in y-axis } touch_matrix_config_t; /** * @brief Matrix button event type */ typedef enum { TOUCH_MATRIX_EVT_ON_PRESS, //!< Matrix button Press event TOUCH_MATRIX_EVT_ON_RELEASE, //!< Matrix button Press event TOUCH_MATRIX_EVT_ON_LONGPRESS, //!< Matrix button LongPress event TOUCH_MATRIX_EVT_MAX } touch_matrix_event_t; /** * @brief Matrix button position data type */ typedef struct { uint8_t x_axis; //!< Matrix button x axis position uint8_t y_axis; //!< Matrix button y axis position uint8_t index; //!< Matrix button position index } touch_matrix_position_t; /** * @brief Matrix message type */ typedef struct { touch_matrix_event_t event; //!< Matrix event touch_matrix_position_t position; //!< Matrix position } touch_matrix_message_t; typedef touch_elem_handle_t touch_matrix_handle_t; //!< Matrix button instance handle typedef void(*touch_matrix_callback_t)(touch_matrix_handle_t, touch_matrix_message_t *, void *); //!< Matrix button callback type /** * @brief Touch matrix button initialize * * This function initializes touch matrix button object and acts on all * touch matrix button instances. * * @param[in] global_config Touch matrix global initialization configuration * * @return * - ESP_OK: Successfully initialized touch matrix button * - ESP_ERR_INVALID_STATE: Touch element library was not initialized * - ESP_ERR_INVALID_ARG: matrix_init is NULL * - ESP_ERR_NO_MEM: Insufficient memory */ esp_err_t touch_matrix_install(const touch_matrix_global_config_t *global_config); /** * @brief Release resources allocated using touch_matrix_install() * */ void touch_matrix_uninstall(void); /** * @brief Create a new touch matrix button instance * * @param[in] matrix_config Matrix button configuration * @param[out] matrix_handle Matrix button handle * * @note Channel array and sensitivity array must be one-one correspondence in those array * * @note Touch matrix button does not support Multi-Touch now * * @return * - ESP_OK: Successfully create touch matrix button * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized * - ESP_ERR_INVALID_ARG: Invalid configuration struct or arguments is NULL * - ESP_ERR_NO_MEM: Insufficient memory */ esp_err_t touch_matrix_create(const touch_matrix_config_t *matrix_config, touch_matrix_handle_t *matrix_handle); /** * @brief Release resources allocated using touch_matrix_create() * * @param[in] matrix_handle Matrix handle * @return * - ESP_OK: Successfully released resources * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized * - ESP_ERR_INVALID_ARG: matrix_handle is null * - ESP_ERR_NOT_FOUND: Input handle is not a matrix handle */ esp_err_t touch_matrix_delete(touch_matrix_handle_t matrix_handle); /** * @brief Touch matrix button subscribes event * * This function uses event mask to subscribe to touch matrix events, once one of * the subscribed events occurs, the event message could be retrieved by calling * touch_element_message_receive() or input callback routine. * * @param[in] matrix_handle Matrix handle * @param[in] event_mask Matrix subscription event mask * @param[in] arg User input argument * * @note Touch matrix button only support three kind of event masks, they are * TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE, TOUCH_ELEM_EVENT_ON_LONGPRESS. You can use those event * masks in any combination to achieve the desired effect. * * @return * - ESP_OK: Successfully subscribed touch matrix event * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized * - ESP_ERR_INVALID_ARG: matrix_handle is null or event is not supported */ esp_err_t touch_matrix_subscribe_event(touch_matrix_handle_t matrix_handle, uint32_t event_mask, void *arg); /** * @brief Touch matrix button set dispatch method * * This function sets a dispatch method that the driver core will use * this method as the event notification method. * * @param[in] matrix_handle Matrix button handle * @param[in] dispatch_method Dispatch method (By callback/event) * * @return * - ESP_OK: Successfully set dispatch method * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized * - ESP_ERR_INVALID_ARG: matrix_handle is null or dispatch_method is invalid */ esp_err_t touch_matrix_set_dispatch_method(touch_matrix_handle_t matrix_handle, touch_elem_dispatch_t dispatch_method); /** * @brief Touch matrix button set callback * * This function sets a callback routine into touch element driver core, * when the subscribed events occur, the callback routine will be called. * * @param[in] matrix_handle Matrix button handle * @param[in] matrix_callback User input callback * * @note Matrix message will be passed from the callback function and it will be destroyed when the callback function return. * * @warning Since this input callback routine runs on driver core (esp-timer callback routine), * it should not do something that attempts to Block, such as calling vTaskDelay(). * * @return * - ESP_OK: Successfully set callback * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized * - ESP_ERR_INVALID_ARG: matrix_handle or matrix_callback is null */ esp_err_t touch_matrix_set_callback(touch_matrix_handle_t matrix_handle, touch_matrix_callback_t matrix_callback); /** * @brief Touch matrix button set long press trigger time * * This function sets the threshold time (ms) for a long press event. If a matrix button is pressed * and held for a period of time that exceeds the threshold time, a long press event is triggered. * * @param[in] matrix_handle Matrix button handle * @param[in] threshold_time Threshold time (ms) of long press event occur * * @return * - ESP_OK: Successfully set the time of long press event * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized * - ESP_ERR_INVALID_ARG: matrix_handle is null or time (ms) is 0 */ esp_err_t touch_matrix_set_longpress(touch_matrix_handle_t matrix_handle, uint32_t threshold_time); /** * @brief Touch matrix get message * * This function decodes the element message from touch_element_message_receive() and return * a matrix message pointer. * * @param[in] element_message element message * * @return Touch matrix message pointer */ const touch_matrix_message_t* touch_matrix_get_message(const touch_elem_message_t* element_message); #ifdef __cplusplus } #endif