/* * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once #include "esp_err.h" #include "driver/touch_sens_types.h" #include "driver/touch_version_types.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Allocate a new touch sensor controller * @note The touch sensor driver will be in INIT state after this function is called successfully. * * @param[in] sens_cfg Touch sensor controller configurations * @param[out] ret_sens_handle The return handle of the touch controller instance * @return * - ESP_OK On success * - ESP_ERR_NO_MEM No memory for the touch sensor controller * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller is already allocated */ esp_err_t touch_sensor_new_controller(const touch_sensor_config_t *sens_cfg, touch_sensor_handle_t *ret_sens_handle); /** * @brief Delete the touch sensor controller * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * * @param[in] sens_handle Touch sensor controller handle * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE Controller not disabled or still some touch channels not deleted */ esp_err_t touch_sensor_del_controller(touch_sensor_handle_t sens_handle); /** * @brief Allocate a new touch channel from the touch sensor controller * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * * @param[in] sens_handle Touch sensor controller handle * @param[in] chan_id Touch channel index * @param[in] chan_cfg Touch channel configurations * @param[out] ret_chan_handle The return handle of the touch channel instance * @return * - ESP_OK On success * - ESP_ERR_NO_MEM No memory for the touch sensor channel * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller has not disabled or this channel has been allocated */ esp_err_t touch_sensor_new_channel(touch_sensor_handle_t sens_handle, int chan_id, const touch_channel_config_t *chan_cfg, touch_channel_handle_t *ret_chan_handle); /** * @brief Delete the touch channel * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * * @param[in] chan_handle Touch channel handle * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller has not disabled */ esp_err_t touch_sensor_del_channel(touch_channel_handle_t chan_handle); /** * @brief Re-configure the touch sensor controller * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * @note The re-configuration only applies to the touch controller, * so it requires the controller handle that allocated from ``touch_sensor_new_controller``, * meanwhile, it won't affect the touch channels, no matter the channels are allocated or not. * * @param[in] sens_handle Touch sensor controller handle * @param[in] sens_cfg Touch sensor controller configurations * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller has not disabled */ esp_err_t touch_sensor_reconfig_controller(touch_sensor_handle_t sens_handle, const touch_sensor_config_t *sens_cfg); /** * @brief Re-configure the touch channel * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * @note The re-configuration only applies to a particular touch channel, * so it requires the channel handle that allocated from ``touch_sensor_new_channel`` * * @param[in] chan_handle Touch channel handle * @param[in] chan_cfg Touch channel configurations * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller has not disabled */ esp_err_t touch_sensor_reconfig_channel(touch_channel_handle_t chan_handle, const touch_channel_config_t *chan_cfg); /** * @brief Configure the touch sensor filter * @note This function is allowed to be called after the touch sensor is enabled * * @param[in] sens_handle Touch sensor controller handle * @param[in] filter_cfg Filter configurations, set NULL to disable the filter * @return * - ESP_OK: Configure the filter success * - ESP_ERR_INVALID_ARG: The sensor handle is NULL */ esp_err_t touch_sensor_config_filter(touch_sensor_handle_t sens_handle, const touch_sensor_filter_config_t *filter_cfg); /** * @brief Enable the touch sensor controller * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * And the touch sensor driver will be in ENABLED state after this function is called successfully. * @note Enable the touch sensor will power on the registered touch channels * * @param[in] sens_handle Touch sensor controller handle * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller has already enabled */ esp_err_t touch_sensor_enable(touch_sensor_handle_t sens_handle); /** * @brief Disable the touch sensor controller * @note This function can only be called after the touch sensor controller is enabled (i.e. ENABLED state). * And the touch sensor driver will be in INIT state after this function is called successfully. * @note Disable the touch sensor will power off the registered touch channels * * @param[in] sens_handle Touch sensor controller handle * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller has already disabled */ esp_err_t touch_sensor_disable(touch_sensor_handle_t sens_handle); /** * @brief Start the scanning of the registered touch channels continuously * @note This function can only be called after the touch sensor controller is enabled (i.e. ENABLED state). * And the touch sensor driver will be in SCANNING state after this function is called successfully. * And it can also be called in ISR/callback context. * @note The hardware FSM (Finite-State Machine) of touch sensor will be driven by * its hardware timer continuously and repeatedly. * i.e., the registered channels will be scanned one by one repeatedly. * * @param[in] sens_handle Touch sensor controller handle * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The touch sensor controller is not enabled or the continuous scanning has started */ esp_err_t touch_sensor_start_continuous_scanning(touch_sensor_handle_t sens_handle); /** * @brief Stop the continuous scanning of the registered touch channels immediately * @note This function can only be called after the continuous scanning started (i.e. SCANNING state). * And the touch sensor driver will be in ENABLED state after this function is called successfully. * And it can also be called in ISR/callback context. * @note Stop the hardware timer and reset the FSM (Finite-State Machine) of the touch sensor controller * * @param[in] sens_handle Touch sensor controller handle * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer * - ESP_ERR_INVALID_STATE The continuous scanning has stopped */ esp_err_t touch_sensor_stop_continuous_scanning(touch_sensor_handle_t sens_handle); /** * @brief Trigger an oneshot scanning for all the registered channels * @note This function can only be called after the touch sensor controller is enabled (i.e. ENABLED state). * And the touch sensor driver will be in SCANNING state after this function is called successfully, * and then switch back to ENABLED state after the scanning is done or timeout. * @note The block time of this function depends on various factors, * In common practice, recommend to set the timeout to several seconds or wait forever, * because oneshot scanning can't last for so long. * * @param[in] sens_handle Touch sensor controller handle * @param[in] timeout_ms Set a positive value or zero means scan timeout in milliseconds * Set a negative value means wait forever until finished scanning * @return * - ESP_OK On success * - ESP_ERR_TIMEOUT Timeout to finish the oneshot scanning * - ESP_ERR_INVALID_ARG Invalid argument * - ESP_ERR_INVALID_STATE The touch sensor controller is not enabled or the continuous scanning has started */ esp_err_t touch_sensor_trigger_oneshot_scanning(touch_sensor_handle_t sens_handle, int timeout_ms); /** * @brief Register the touch sensor callbacks * @note This function can be called when the touch sensor controller is NOT enabled (i.e. INIT state). * * @param[in] sens_handle Touch sensor controller handle * @param[in] callbacks Callback functions * @param[in] user_ctx User context that will be passed to the callback functions * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG NULL pointer * - ESP_ERR_INVALID_STATE Touch sensor controller has not disabled */ esp_err_t touch_sensor_register_callbacks(touch_sensor_handle_t sens_handle, const touch_event_callbacks_t *callbacks, void *user_ctx); /** * @brief Confiture the touch sensor benchmark for all the registered channels * @note This function can be called no matter the touch sensor controller is enabled or not (i.e. ENABLED or SCANNING state). * And it can also be called in ISR/callback context. * * @param[in] chan_handle Touch channel handle * @param[in] benchmark_cfg The benchmark configurations * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG NULL pointer */ esp_err_t touch_channel_config_benchmark(touch_channel_handle_t chan_handle, const touch_chan_benchmark_config_t *benchmark_cfg); /** * @brief Read the touch channel data according to the types * @note This function can be called no matter the touch sensor controller is enabled or not (i.e. ENABLED or SCANNING state). * And it can also be called in ISR/callback context. * @note Specially, `TOUCH_CHAN_DATA_TYPE_PROXIMITY` data type will be read from the cached data in the driver, * because the proximity data need to be accumulated in several scan times that specified by `touch_proximity_config_t::scan_times`. * For other data types, the data are read from the hardware registers directly (not cached in the driver). * The channel data in the register will be updated once the measurement of this channels is done, * And keep locked until the next measurement is done. * * @param[in] chan_handle Touch channel handle * @param[in] type Specify the data type to read * @param[out] data The data array pointer. If the target supports multiple sample configurations (SOC_TOUCH_SAMPLE_CFG_NUM), the array length should be equal to * the frequency hopping number that specified in `touch_sensor_config_t::sample_cfg_num`, otherwise the array length should be 1. * @return * - ESP_OK On success * - ESP_ERR_INVALID_ARG Invalid argument or NULL pointer */ esp_err_t touch_channel_read_data(touch_channel_handle_t chan_handle, touch_chan_data_type_t type, uint32_t *data); #if SOC_TOUCH_SUPPORT_WATERPROOF /** * @brief Configure the touch sensor water proof channels * @note Once waterproof is enabled, the other touch channels won't be updated unless the shield channels is activated. * * @param[in] sens_handle Touch sensor controller handle * @param[in] wp_cfg Water proof channel configurations, set NULL to disable the water proof function * @return * - ESP_OK: Configure the water proof success * - ESP_ERR_INVALID_ARG: The sensor handle is NULL * - ESP_ERR_INVALID_STATE: The touch sensor is enabled */ esp_err_t touch_sensor_config_waterproof(touch_sensor_handle_t sens_handle, const touch_waterproof_config_t *wp_cfg); #endif #if SOC_TOUCH_SUPPORT_PROX_SENSING /** * @brief Configure the touch sensor proximity sensing channels * * @param[in] sens_handle Touch sensor controller handle * @param[in] prox_cfg Proximity channels configurations, set NULL to disable the proximity sensing * @return * - ESP_OK: Configure the proximity channel success * - ESP_ERR_INVALID_ARG: The sensor handle is NULL * - ESP_ERR_INVALID_STATE: The touch sensor is enabled */ esp_err_t touch_sensor_config_proximity_sensing(touch_sensor_handle_t sens_handle, const touch_proximity_config_t *prox_cfg); #endif #if SOC_TOUCH_SUPPORT_SLEEP_WAKEUP /** * @brief Configure the touch sensor to wake-up the chip from sleep * @note Call this function to enable/disable the touch sensor wake-up the chip from deep/light sleep * To only enable the touch sensor wake-up the chip from light sleep, set the `touch_sleep_config_t::deep_slp_chan` to NULL. * During the light sleep, all enabled touch channels will keep working, and any one of them can wake-up the chip from light sleep. * To enable the touch sensor wake-up the chip from both light and deep sleep, set the `touch_sleep_config_t::deep_slp_chan` to an enabled channel. * During the deep sleep, only this specified channels can work and wake-up the chip from the deep sleep, * and other enabled channels can only wake-up the chip from light sleep. * * @param[in] sens_handle Touch sensor controller handle * @param[in] sleep_cfg Sleep wake-up configurations, set NULL to disable the touch sensor wake-up the chip from sleep * @return * - ESP_OK: Configure the sleep channel success * - ESP_ERR_INVALID_ARG: The sensor handle is NULL * - ESP_ERR_INVALID_STATE: The touch sensor is enabled */ esp_err_t touch_sensor_config_sleep_wakeup(touch_sensor_handle_t sens_handle, const touch_sleep_config_t *sleep_cfg); #endif #ifdef __cplusplus } #endif