esp-idf/components/touch_element/include/touch_element/touch_element.h

/*
 * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#pragma once

#include "driver/touch_sensor.h"

#ifdef __cplusplus
extern "C" {
#endif

/* -------------------------------- General hardware & system default configuration  -------------------------------- */
/* Since those are important hardware and algorithm parameters, user should not change them before knowing all details*/
/* ------------------------------------------------------------------------------------------------------------------ */
#define TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG()                                    \
{                                                                             \
    .hardware = {                                                             \
        .upper_voltage = TOUCH_HVOLT_2V7,                                     \
        .voltage_attenuation = TOUCH_HVOLT_ATTEN_0V5,                         \
        .lower_voltage = TOUCH_LVOLT_0V5,                                     \
        .suspend_channel_polarity = TOUCH_PAD_CONN_HIGHZ,                     \
        .denoise_level = TOUCH_PAD_DENOISE_BIT4,                              \
        .denoise_equivalent_cap = TOUCH_PAD_DENOISE_CAP_L0,                   \
        .smooth_filter_mode = TOUCH_PAD_SMOOTH_IIR_2,                         \
        .benchmark_filter_mode = TOUCH_PAD_FILTER_IIR_16,                     \
        .sample_count = 500,                                                  \
        .sleep_cycle = 0xf,                                                   \
        .benchmark_debounce_count = 2,                                        \
        .benchmark_calibration_threshold = 2,                                 \
        .benchmark_jitter_step = 5                                            \
    },                                                                        \
    .software = {                                                             \
        .waterproof_threshold_divider = 0.8,                                  \
        .processing_period = 10,                                              \
        .intr_message_size = 14,                                              \
        .event_message_size = 20                                              \
    }                                                                         \
}
/* ------------------------------------------------------------------------------------------------------------------ */

/* ---------------------------------------------- Event subscription  ----------------------------------------------- */
#define TOUCH_ELEM_EVENT_NONE                       BIT(0)      //!< None event
#define TOUCH_ELEM_EVENT_ON_PRESS                   BIT(1)      //!< On Press event
#define TOUCH_ELEM_EVENT_ON_RELEASE                 BIT(2)      //!< On Release event
#define TOUCH_ELEM_EVENT_ON_LONGPRESS               BIT(3)      //!< On LongPress event
#define TOUCH_ELEM_EVENT_ON_CALCULATION             BIT(4)      //!< On Calculation event
/* ------------------------------------------------------------------------------------------------------------------ */
#define TOUCH_WATERPROOF_GUARD_NOUSE       (0)         //!< Waterproof no use guard sensor
/* -------------------------------- Global hardware & software configuration struct --------------------------------- */
/**
 * @brief   Touch element software configuration
 */
typedef struct {
    float waterproof_threshold_divider;        //!< Waterproof guard channel threshold divider
    uint8_t processing_period;                 //!< Processing period(ms)
    uint8_t intr_message_size;                 //!< Interrupt message queue size
    uint8_t event_message_size;                //!< Event message queue size
} touch_elem_sw_config_t;

/**
 * @brief   Touch element hardware configuration
 */
typedef struct {
    touch_high_volt_t upper_voltage;                  //!< Touch sensor channel upper charge voltage
    touch_volt_atten_t voltage_attenuation;           //!< Touch sensor channel upper charge voltage attenuation (Diff voltage is upper - attenuation - lower)
    touch_low_volt_t lower_voltage;                   //!< Touch sensor channel lower charge voltage
    touch_pad_conn_type_t suspend_channel_polarity;   //!< Suspend channel polarity (High Impedance State or GND)
    touch_pad_denoise_grade_t denoise_level;          //!< Internal de-noise level
    touch_pad_denoise_cap_t denoise_equivalent_cap;   //!< Internal de-noise channel (Touch channel 0) equivalent capacitance
    touch_smooth_mode_t smooth_filter_mode;           //!< Smooth value filter mode (This only apply to touch_pad_filter_read_smooth())
    touch_filter_mode_t benchmark_filter_mode;        //!< Benchmark filter mode
    uint16_t sample_count;                            //!< The count of sample in each measurement of touch sensor
    uint16_t sleep_cycle;                             //!< The cycle (RTC slow clock) of sleep
    uint8_t benchmark_debounce_count;                 //!< Benchmark debounce count
    uint8_t benchmark_calibration_threshold;          //!< Benchmark calibration threshold
    uint8_t benchmark_jitter_step;                    //!< Benchmark jitter filter step (This only works at while benchmark filter mode is jitter filter)
} touch_elem_hw_config_t;

/**
 * @brief   Touch element global configuration passed to touch_element_install
 */
typedef struct {
    touch_elem_hw_config_t hardware;         //!< Hardware configuration
    touch_elem_sw_config_t software;         //!< Software configuration
} touch_elem_global_config_t;

/**
 * @brief   Touch element waterproof configuration passed to touch_element_waterproof_install
 */
typedef struct {
    touch_pad_t guard_channel;     //!< Waterproof Guard-Sensor channel number (index)
    float guard_sensitivity;       //!< Waterproof Guard-Sensor sensitivity
} touch_elem_waterproof_config_t;

/**
 * @brief   Touch element sleep configuration passed to touch_element_enable_light_sleep or touch_element_enable_deep_sleep
*/
typedef struct {
    uint16_t sample_count;                     //!< scan times in every measurement, normally equal to the 'sample_count' field in 'touch_elem_hw_config_t'.
    uint16_t sleep_cycle;                    //!< sleep_cycle decide the interval between two measurements， t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency), normally equal to the 'sleep_cycle' field in 'touch_elem_hw_config_t'.
} touch_elem_sleep_config_t;
/* ------------------------------------------------------------------------------------------------------------------ */
typedef void *touch_elem_handle_t;        //!< Touch element handle type
typedef uint32_t touch_elem_event_t;      //!< Touch element event type

/**
 * @brief   Touch element handle type
 */
typedef enum {
    TOUCH_ELEM_TYPE_BUTTON,         //!< Touch element button
    TOUCH_ELEM_TYPE_SLIDER,         //!< Touch element slider
    TOUCH_ELEM_TYPE_MATRIX,         //!< Touch element matrix button
} touch_elem_type_t;

/**
 * @brief   Touch element event dispatch methods (event queue/callback)
 */
typedef enum {
    TOUCH_ELEM_DISP_EVENT,           //!< Event queue dispatch
    TOUCH_ELEM_DISP_CALLBACK,        //!< Callback dispatch
    TOUCH_ELEM_DISP_MAX
} touch_elem_dispatch_t;

/**
 * @brief   Touch element event message type from touch_element_message_receive()
 */
typedef struct {
    touch_elem_handle_t handle;             //!< Touch element handle
    touch_elem_type_t element_type;         //!< Touch element type
    void *arg;                              //!< User input argument
    uint8_t child_msg[8];                   //!< Encoded message
} touch_elem_message_t;
/* ------------------------------------------------------------------------------------------------------------------ */

/**
 * @brief   Touch element processing initialization
 *
 * @param[in]   global_config   Global initialization configuration structure
 *
 * @note    To reinitialize the touch element object, call touch_element_uninstall() first
 *
 * @return
 *      - ESP_OK: Successfully initialized
 *      - ESP_ERR_INVALID_ARG: Invalid argument
 *      - ESP_ERR_NO_MEM: Insufficient memory
 *      - ESP_ERR_INVALID_STATE: Touch element is already initialized
 *      - Others: Unknown touch driver layer or lower layer error
 */
esp_err_t touch_element_install(const touch_elem_global_config_t *global_config);

/**
 * @brief   Touch element processing start
 *
 * This function starts the touch element processing system
 *
 * @note    This function must only be called after all the touch element instances finished creating
 *
 * @return
 *      - ESP_OK: Successfully started to process
 *      - Others: Unknown touch driver layer or lower layer error
 */
esp_err_t touch_element_start(void);

/**
 * @brief   Touch element processing stop
 *
 * This function stops the touch element processing system
 *
 * @note    This function must be called before changing the system (hardware, software) parameters
 *
 * @return
 *      - ESP_OK: Successfully stopped to process
 *      - Others: Unknown touch driver layer or lower layer error
 */
esp_err_t touch_element_stop(void);

/**
 * @brief   Release resources allocated using touch_element_install
 *
 */
void touch_element_uninstall(void);

/**
 * @brief   Get current event message of touch element instance
 *
 * This function will receive the touch element message (handle, event type, etc...)
 * from te_event_give(). It will block until a touch element event or a timeout occurs.
 *
 * @param[out]  element_message          Touch element event message structure
 * @param[in]   ticks_to_wait   Number of FreeRTOS ticks to block for waiting event
 * @return
 *      - ESP_OK: Successfully received touch element event
 *      - ESP_ERR_INVALID_STATE: Touch element library is not initialized
 *      - ESP_ERR_INVALID_ARG: element_message is null
 *      - ESP_ERR_TIMEOUT: Timed out waiting for event
 */
esp_err_t touch_element_message_receive(touch_elem_message_t *element_message, uint32_t ticks_to_wait);

/**
 * @brief   Touch element waterproof initialization
 *
 * This function enables the hardware waterproof, then touch element system uses Shield-Sensor
 * and Guard-Sensor to mitigate the influence of water-drop and water-stream.
 *
 * @param[in] waterproof_config     Waterproof configuration
 *
 * @note    If the waterproof function is used, Shield-Sensor can not be disabled and it will use channel 14 as
 *          it's internal channel. Hence, the user can not use channel 14 for another propose. And the Guard-Sensor
 *          is not necessary since it is optional.
 *
 * @note    Shield-Sensor: It always uses channel 14 as the shield channel, so user must connect
 *          the channel 14 and Shield-Layer in PCB since it will generate a synchronous signal automatically
 *
 * @note    Guard-Sensor: This function is optional. If used, the user must connect the guard channel and Guard-Ring
 *          in PCB. Any channels user wants to protect should be added into Guard-Ring in PCB.
 *
 * @return
 *      - ESP_OK: Successfully initialized
 *      - ESP_ERR_INVALID_STATE: Touch element library is not initialized
 *      - ESP_ERR_INVALID_ARG: waterproof_config is null or invalid Guard-Sensor channel
 *      - ESP_ERR_NO_MEM: Insufficient memory
 */
esp_err_t touch_element_waterproof_install(const touch_elem_waterproof_config_t *waterproof_config);

/**
 * @brief   Release resources allocated using touch_element_waterproof_install()
 */
void touch_element_waterproof_uninstall(void);

/**
 * @brief   Add a masked handle to protect while Guard-Sensor has been triggered
 *
 * This function will add an application handle (button, slider, etc...) as a masked handle. While Guard-Sensor
 * has been triggered, waterproof function will start working and lock the application internal state. While the
 * influence of water is reduced, the application will be unlock and reset into IDLE state.
 *
 * @param[in] element_handle     Touch element instance handle
 *
 * @note    The waterproof protection logic must follow the real circuit in PCB, it means that all of the channels
 *          inside the input handle must be inside the Guard-Ring in real circuit.
 *
 * @return
 *      - ESP_OK: Successfully added a masked handle
 *      - ESP_ERR_INVALID_STATE: Waterproof is not initialized
 *      - ESP_ERR_INVALID_ARG: element_handle is null
 */
esp_err_t touch_element_waterproof_add(touch_elem_handle_t element_handle);

/**
 * @brief   Remove a masked handle to protect
 *
 * This function will remove an application handle from masked handle table.
 *
 * @param[in] element_handle     Touch element instance handle
 *
 * @return
 *      - ESP_OK: Successfully removed a masked handle
 *      - ESP_ERR_INVALID_STATE: Waterproof is not initialized
 *      - ESP_ERR_INVALID_ARG: element_handle is null
 *      - ESP_ERR_NOT_FOUND: Failed to search element_handle from waterproof mask_handle list
 */
esp_err_t touch_element_waterproof_remove(touch_elem_handle_t element_handle);

/**
 * @brief   Touch element light sleep initialization
 *
 * @note    It should be called after touch button element installed.
 *          Any of installed touch element can wake up from the light sleep
 *
 * @param[in] sleep_config Sleep configurations, set NULL to use default config
 * @return
 *      - ESP_OK: Successfully initialized touch sleep
 *      - ESP_ERR_INVALID_STATE: Touch element is not installed or touch sleep has been installed
 *      - ESP_ERR_INVALID_ARG: inputed argument is NULL
 *      - ESP_ERR_NO_MEM: no memory for touch sleep struct
 *      - ESP_ERR_NOT_SUPPORTED: inputed wakeup_elem_handle is not touch_button_handle_t type, currently only touch_button_handle_t supported
 */
esp_err_t touch_element_enable_light_sleep(const touch_elem_sleep_config_t *sleep_config);

/**
 * @brief   Release the resources that allocated by touch_element_enable_deep_sleep()
 *
 * This function will also disable the touch sensor to wake up the device
 *
 * @return
 *      - ESP_OK: uninstall success
 *      - ESP_ERR_INVALID_STATE: touch sleep has not been installed
 */
esp_err_t touch_element_disable_light_sleep(void);

/**
 * @brief   Touch element deep sleep initialization
 *
 * This function will enable the device wake-up from deep sleep or light sleep by touch sensor
 *
 * @note    It should be called after touch button element installed.
 *          Only one touch button can be registered as the deep sleep wake-up button
 *
 * @param[in] wakeup_elem_handle    Touch element instance handle for waking up the device, only support button element
 * @param[in] sleep_config          Sleep configurations, set NULL to use default config
 *
 * @return
 *      - ESP_OK: Successfully initialized touch sleep
 *      - ESP_ERR_INVALID_STATE: Touch element is not installed or touch sleep has been installed
 *      - ESP_ERR_INVALID_ARG: inputed argument is NULL
 *      - ESP_ERR_NO_MEM: no memory for touch sleep struct
 *      - ESP_ERR_NOT_SUPPORTED: inputed wakeup_elem_handle is not touch_button_handle_t type, currently only touch_button_handle_t supported
 */
esp_err_t touch_element_enable_deep_sleep(touch_elem_handle_t wakeup_elem_handle, const touch_elem_sleep_config_t *sleep_config);

/**
 * @brief   Release the resources that allocated by touch_element_enable_deep_sleep()
 *
 * This function will also disable the touch sensor to wake up the device
 *
 * @return
 *      - ESP_OK: uninstall success
 *      - ESP_ERR_INVALID_STATE: touch sleep has not been installed
 */
esp_err_t touch_element_disable_deep_sleep(void);

/**
 * @brief   Touch element wake up calibrations
 *
 * This function will also disable the touch sensor to wake up the device
 *
 * @return
 *      - ESP_OK: uninstall success
 *      - ESP_ERR_INVALID_STATE: touch sleep has not been installed
 */
esp_err_t touch_element_sleep_enable_wakeup_calibration(touch_elem_handle_t element_handle, bool en);

#ifdef __cplusplus
}
#endif