// Copyright 2016-2020 Espressif Systems (Shanghai) PTE LTD // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #pragma once #include "touch_element/touch_element.h" #ifdef __cplusplus extern "C" { #endif /* --------------------------------- General slider instance default configuration --------------------------------- */ #define TOUCH_SLIDER_GLOBAL_DEFAULT_CONFIG() \ { \ .quantify_lower_threshold = 0.3, \ .threshold_divider = 0.8, \ .filter_reset_time = 50, \ .benchmark_update_time = 500, \ .position_filter_size = 10, \ .position_filter_factor = 2, \ .calculate_channel_count = 3 \ } /* ------------------------------------------------------------------------------------------------------------------ */ /** * @brief Slider initialization configuration passed to touch_slider_install */ typedef struct { float quantify_lower_threshold; //!< Slider signal quantification threshold float threshold_divider; //!< Slider channel threshold divider uint16_t filter_reset_time; //!< Slider position filter reset time (Unit is esp_timer callback tick) uint16_t benchmark_update_time; //!< Slider benchmark update time (Unit is esp_timer callback tick) uint8_t position_filter_size; //!< Moving window filter buffer size uint8_t position_filter_factor; //!< One-order IIR filter factor uint8_t calculate_channel_count; //!< The number of channels which will take part in calculation } touch_slider_global_config_t; /** * @brief Slider configuration (for new instance) passed to touch_slider_create() */ typedef struct { const touch_pad_t *channel_array; //!< Slider channel array const float *sensitivity_array; //!< Slider channel sensitivity array uint8_t channel_num; //!< The number of slider channels uint8_t position_range; //!< The right region of touch slider position range, [0, position_range (less than or equal to 255)] } touch_slider_config_t; /** * @brief Slider event type */ typedef enum { TOUCH_SLIDER_EVT_ON_PRESS, //!< Slider on Press event TOUCH_SLIDER_EVT_ON_RELEASE, //!< Slider on Release event TOUCH_SLIDER_EVT_ON_CALCULATION, //!< Slider on Calculation event TOUCH_SLIDER_EVT_MAX } touch_slider_event_t; typedef uint32_t touch_slider_position_t; //!< Slider position data type /** * @brief Slider message type */ typedef struct { touch_slider_event_t event; //!< Slider event touch_slider_position_t position; //!< Slider position } touch_slider_message_t; typedef touch_elem_handle_t touch_slider_handle_t; //!< Slider instance handle typedef void(*touch_slider_callback_t)(touch_slider_handle_t, touch_slider_message_t *, void *); //!< Slider callback type /** * @brief Touch slider initialize * * This function initializes touch slider object and acts on all * touch slider instances. * * @param[in] global_config Touch slider global initialization configuration * * @return * - ESP_OK: Successfully initialized touch slider * - ESP_ERR_INVALID_STATE: Touch element library was not initialized * - ESP_ERR_INVALID_ARG: slider_init is NULL * - ESP_ERR_NO_MEM: Insufficient memory */ esp_err_t touch_slider_install(const touch_slider_global_config_t *global_config); /** * @brief Release resources allocated using touch_slider_install() * * @return * - ESP_OK: Successfully released resources */ void touch_slider_uninstall(void); /** * @brief Create a new touch slider instance * * @param[in] slider_config Slider configuration * @param[out] slider_handle Slider handle * * @note The index of Channel array and sensitivity array must be one-one correspondence * * @return * - ESP_OK: Successfully create touch slider * - ESP_ERR_INVALID_STATE: Touch slider 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_slider_create(const touch_slider_config_t *slider_config, touch_slider_handle_t *slider_handle); /** * @brief Release resources allocated using touch_slider_create * * @param[in] slider_handle Slider handle * @return * - ESP_OK: Successfully released resources * - ESP_ERR_INVALID_STATE: Touch slider driver was not initialized * - ESP_ERR_INVALID_ARG: slider_handle is null * - ESP_ERR_NOT_FOUND: Input handle is not a slider handle */ esp_err_t touch_slider_delete(touch_slider_handle_t slider_handle); /** * @brief Touch slider subscribes event * * This function uses event mask to subscribe to touch slider 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] slider_handle Slider handle * @param[in] event_mask Slider subscription event mask * @param[in] arg User input argument * * @note Touch slider only support three kind of event masks, they are * TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE. You can use those event masks in any * combination to achieve the desired effect. * * @return * - ESP_OK: Successfully subscribed touch slider event * - ESP_ERR_INVALID_STATE: Touch slider driver was not initialized * - ESP_ERR_INVALID_ARG: slider_handle is null or event is not supported */ esp_err_t touch_slider_subscribe_event(touch_slider_handle_t slider_handle, uint32_t event_mask, void *arg); /** * @brief Touch slider set dispatch method * * This function sets a dispatch method that the driver core will use * this method as the event notification method. * * @param[in] slider_handle Slider handle * @param[in] dispatch_method Dispatch method (By callback/event) * * @return * - ESP_OK: Successfully set dispatch method * - ESP_ERR_INVALID_STATE: Touch slider driver was not initialized * - ESP_ERR_INVALID_ARG: slider_handle is null or dispatch_method is invalid */ esp_err_t touch_slider_set_dispatch_method(touch_slider_handle_t slider_handle, touch_elem_dispatch_t dispatch_method); /** * @brief Touch slider 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] slider_handle Slider handle * @param[in] slider_callback User input callback * * @note Slider 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 slider driver was not initialized * - ESP_ERR_INVALID_ARG: slider_handle or slider_callback is null */ esp_err_t touch_slider_set_callback(touch_slider_handle_t slider_handle, touch_slider_callback_t slider_callback); /** * @brief Touch slider get message * * This function decodes the element message from touch_element_message_receive() and return * a slider message pointer. * * @param[in] element_message element message * * @return Touch slider message pointer */ const touch_slider_message_t* touch_slider_get_message(const touch_elem_message_t* element_message); #ifdef __cplusplus } #endif