alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-20 00:36:01 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'refactor/add_description_to_touch_pad_set_meas_time' into 'master'

Browse Source 
touch_sensor: add description to distinguish the API on different target

Closes IDFGH-7499

See merge request espressif/esp-idf!18341
This commit is contained in:
Kevin (Lao Kaiyao) 2022-06-28 20:00:02 +08:00
commit 47266d7736
14 changed files with 379 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
components/driver/esp32/include/driver/touch_sensor.h
View File

@ -117,22 +117,73 @@ esp_err_t touch_pad_set_filter_read_cb(filter_cb_t read_cb);
*/
esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg);
/**
* @brief Set the clock cycles of each measurement
* @note This function will specify the clock cycles of each measurement
* and the clock is sourced from SOC_MOD_CLK_RTC_FAST, its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX
* The touch sensor will record the charge and discharge times during these clock cycles as the final result (raw value)
* @note If clock cyles is too small, it may lead to inaccurate results.
*
* @param clock_cycle The clock cycles of each measurement
* measure_time = clock_cycle / SOC_CLK_RC_FAST_FREQ_APPROX, the maximum measure time is 0xffff / SOC_CLK_RC_FAST_FREQ_APPROX
* @return
* - ESP_OK Set the clock cycle success
*/
esp_err_t touch_pad_set_measurement_clock_cycles(uint16_t clock_cycle);
/**
* @brief Get the clock cycles of each measurement
*
* @param clock_cycle The clock cycles of each measurement
* @return
* - ESP_OK Get the clock cycle success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_measurement_clock_cycles(uint16_t *clock_cycle);
/**
* @brief Set the interval between two measurements
* @note The touch sensor will sleep between two mesurements
* This function is to set the interval cycle
* And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX
*
* @param interval_cycle The interval between two measurements
* sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX.
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @return
* - ESP_OK Set interval cycle success
*/
esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle);
/**
* @brief Get the interval between two measurements
*
* @param interval_cycle The interval between two measurements
* @return
* - ESP_OK Get interval cycle success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle);
/**
* @brief Set touch sensor measurement and sleep time.
* Excessive total time will slow down the touch response.
* Too small measurement time will not be sampled enough, resulting in inaccurate measurements.
*
* @note The touch sensor will count the number of charge/discharge cycles over a fixed period of time (specified as the second parameter).
* That means the number of cycles (raw value) will decrease as the capacity of the touch pad is increasing.
* @note The greater the duty cycle of the measurement time, the more system power is consumed.
*
* @param sleep_cycle The touch sensor will sleep after each measurement.
* sleep_cycle decide the interval between each measurement.
* t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency).
* t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX.
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @param meas_cycle The duration of the touch sensor measurement.
* t_meas = meas_cycle / 8M, the maximum measure time is 0xffff / 8M = 8.19 ms
* t_meas = meas_cycle / SOC_CLK_RC_FAST_FREQ_APPROX, the maximum measure time is 0xffff / SOC_CLK_RC_FAST_FREQ_APPROX
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle);
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle)
__attribute__((deprecated("please use 'touch_pad_set_measurement_clock_cycles' and 'touch_pad_set_measurement_interval' instead")));
/**
* @brief Get touch sensor measurement and sleep time
@ -140,8 +191,10 @@ esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle);
* @param meas_cycle Pointer to accept measurement cycle count.
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle);
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle)
__attribute__((deprecated("please use 'touch_pad_get_measurement_clock_cycles' and 'touch_pad_get_measurement_interval' instead")));
/**
* @brief Trigger a touch sensor measurement, only support in SW mode of FSM

50
components/driver/esp32/touch_sensor.c
View File

@ -124,25 +124,55 @@ static void touch_pad_filter_cb(void *arg)
}
}
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle)
esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle)
{
TOUCH_ENTER_CRITICAL();
touch_hal_set_meas_time(meas_cycle);
touch_hal_set_sleep_time(sleep_cycle);
touch_hal_set_sleep_time(interval_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle)
{
TOUCH_NULL_POINTER_CHECK(interval_cycle, "interval_cycle");
TOUCH_ENTER_CRITICAL();
touch_hal_get_sleep_time(interval_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_set_measurement_clock_cycles(uint16_t clock_cycle)
{
TOUCH_ENTER_CRITICAL();
touch_hal_set_meas_time(clock_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_get_measurement_clock_cycles(uint16_t *clock_cycle)
{
TOUCH_NULL_POINTER_CHECK(clock_cycle, "clock_cycle");
TOUCH_ENTER_CRITICAL();
touch_hal_get_meas_time(clock_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle)
{
touch_pad_set_measurement_clock_cycles(meas_cycle);
touch_pad_set_measurement_interval(sleep_cycle);
return ESP_OK;
}
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle)
{
TOUCH_NULL_POINTER_CHECK(sleep_cycle, "sleep_cycle");
TOUCH_NULL_POINTER_CHECK(meas_cycle, "meas_cycle");
TOUCH_ENTER_CRITICAL();
touch_hal_get_meas_time(meas_cycle);
touch_hal_get_sleep_time(sleep_cycle);
TOUCH_EXIT_CRITICAL();
touch_pad_get_measurement_interval(sleep_cycle);
touch_pad_get_measurement_clock_cycles(meas_cycle);
return ESP_OK;
}
@ -268,7 +298,9 @@ esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold)
uint32_t wait_tick = 0;
uint32_t rtc_clk_freq = rtc_clk_slow_freq_get_hz();
touch_pad_set_group_mask((1 << touch_num), (1 << touch_num), (1 << touch_num));
touch_pad_get_meas_time(&sleep_time, &meas_cycle);
touch_pad_get_measurement_interval(&sleep_time);
touch_pad_get_measurement_clock_cycles(&meas_cycle);
//If the FSM mode is 'TOUCH_FSM_MODE_TIMER', The data will be ready after one measurement cycle
//after this function is executed, otherwise, the "touch_value" by "touch_pad_read" is 0.
wait_time_ms = sleep_time / (rtc_clk_freq / 1000) + meas_cycle / (SOC_CLK_RC_FAST_FREQ_APPROX / 1000);

67
components/driver/esp32s2/include/driver/touch_sensor.h
View File

@ -35,23 +35,75 @@ esp_err_t touch_pad_fsm_stop(void);
*/
esp_err_t touch_pad_sw_start(void);
/**
* @brief Set charge and discharge times of each measurement
* @note This function will specify the charge and discharge times in each measurement period
* The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX
* The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value)
* @note If the charge and discharge times is too small, it may lead to inaccurate results.
*
* @param charge_discharge_times Charge and discharge times, range: 0 ~ 0xffff.
* No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches,
* but suggest adjusting this value to make the measurement time around 1 ms.
* @return
* - ESP_OK Set charge and discharge times success
*/
esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times);
/**
* @brief Get charge and discharge times of each measurement
*
* @param charge_discharge_times Charge and discharge times
* @return
* - ESP_OK Get charge_discharge_times success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times);
/**
* @brief Set the interval between two measurements
* @note The touch sensor will sleep between two mesurements
* This function is to set the interval cycle
* And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX
*
* @param interval_cycle The interval between two measurements
* sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX.
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @return
* - ESP_OK Set interval cycle success
*/
esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle);
/**
* @brief Get the interval between two measurements
*
* @param interval_cycle The interval between two measurements
* @return
* - ESP_OK Get interval cycle success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle);
/**
* @brief Set touch sensor times of charge and discharge and sleep time.
* Excessive total time will slow down the touch response.
* Too small measurement time will not be sampled enough, resulting in inaccurate measurements.
*
* @note The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter).
* That means the time (raw value) will increase as the capacity of the touch pad is increasing.
* The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default
* @note The greater the duty cycle of the measurement time, the more system power is consumed.
*
* @param sleep_cycle The touch sensor will sleep after each measurement.
* sleep_cycle decide the interval between each measurement.
* t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency).
* t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX.
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @param meas_times The times of charge and discharge in each measure process of touch channels.
* The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
* Recommended typical value: Modify this value to make the measurement time around 1ms.
* @param meas_times The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff.
* Recommended typical value: Modify this value to make the measurement time around 1 ms.
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)
__attribute__((deprecated("please use 'touch_pad_set_charge_discharge_times' and 'touch_pad_set_measurement_interval' instead")));
/**
* @brief Get touch sensor times of charge and discharge and sleep time
@ -60,7 +112,8 @@ esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times);
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times)
__attribute__((deprecated("please use 'touch_pad_get_charge_discharge_times' and 'touch_pad_get_measurement_interval' instead")));
/**
* @brief Set connection type of touch channel in idle status.

44
components/driver/esp32s2/touch_sensor.c
View File

@ -116,26 +116,58 @@ esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_ma
return ret;
}
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)
esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle)
{
TOUCH_ENTER_CRITICAL();
touch_hal_set_meas_times(meas_times);
touch_hal_set_sleep_time(sleep_cycle);
touch_hal_set_sleep_time(interval_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle)
{
TOUCH_NULL_POINTER_CHECK(interval_cycle, "interval_cycle");
TOUCH_ENTER_CRITICAL();
touch_hal_get_sleep_time(interval_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times)
{
TOUCH_ENTER_CRITICAL();
touch_hal_set_meas_times(charge_discharge_times);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times)
esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times)
{
TOUCH_NULL_POINTER_CHECK(charge_discharge_times, "charge_discharge_times");
TOUCH_ENTER_CRITICAL();
touch_hal_get_measure_times(meas_times);
touch_hal_get_sleep_time(sleep_cycle);
touch_hal_get_measure_times(charge_discharge_times);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)
{
touch_pad_set_charge_discharge_times(meas_times);
touch_pad_set_measurement_interval(sleep_cycle);
return ESP_OK;
}
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times)
{
TOUCH_NULL_POINTER_CHECK(sleep_cycle, "sleep_cycle");
TOUCH_NULL_POINTER_CHECK(meas_times, "meas_times");
touch_pad_get_measurement_interval(sleep_cycle);
touch_pad_get_charge_discharge_times(meas_times);
return ESP_OK;
}
esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type)
{
ESP_RETURN_ON_FALSE(type < TOUCH_PAD_CONN_MAX, ESP_ERR_INVALID_ARG, TOUCH_TAG, TOUCH_PARAM_CHECK_STR("type"));

67
components/driver/esp32s3/include/driver/touch_sensor.h
View File

@ -35,23 +35,75 @@ esp_err_t touch_pad_fsm_stop(void);
*/
esp_err_t touch_pad_sw_start(void);
/**
* @brief Set charge and discharge times of each measurement
* @note This function will specify the charge and discharge times in each measurement period
* The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX
* The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value)
* @note If the charge and discharge times is too small, it may lead to inaccurate results.
*
* @param charge_discharge_times Charge and discharge times, range: 0 ~ 0xffff.
* No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches,
* but suggest adjusting this value to make the measurement time around 1 ms.
* @return
* - ESP_OK Set charge and discharge times success
*/
esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times);
/**
* @brief Get charge and discharge times of each measurement
*
* @param charge_discharge_times Charge and discharge times
* @return
* - ESP_OK Get charge_discharge_times success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times);
/**
* @brief Set the interval between two measurements
* @note The touch sensor will sleep between two mesurements
* This function is to set the interval cycle
* And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX
*
* @param interval_cycle The interval between two measurements
* sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX.
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @return
* - ESP_OK Set interval cycle success
*/
esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle);
/**
* @brief Get the interval between two measurements
*
* @param interval_cycle The interval between two measurements
* @return
* - ESP_OK Get interval cycle success
* - ESP_ERR_INVALID_ARG The input parameter is NULL
*/
esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle);
/**
* @brief Set touch sensor times of charge and discharge and sleep time.
* Excessive total time will slow down the touch response.
* Too small measurement time will not be sampled enough, resulting in inaccurate measurements.
*
* @note The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter).
* That means the time (raw value) will increase as the capacity of the touch pad is increasing.
* The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default
* @note The greater the duty cycle of the measurement time, the more system power is consumed.
*
* @param sleep_cycle The touch sensor will sleep after each measurement.
* sleep_cycle decide the interval between each measurement.
* t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency).
* t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX.
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @param meas_times The times of charge and discharge in each measure process of touch channels.
* The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
* Recommended typical value: Modify this value to make the measurement time around 1ms.
* @param meas_times The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff.
* Recommended typical value: Modify this value to make the measurement time around 1 ms.
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)
__attribute__((deprecated("please use 'touch_pad_set_charge_discharge_times' and 'touch_pad_set_measurement_interval' instead")));
/**
* @brief Get touch sensor times of charge and discharge and sleep time
@ -60,7 +112,8 @@ esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times);
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times)
__attribute__((deprecated("please use 'touch_pad_get_charge_discharge_times' and 'touch_pad_get_measurement_interval' instead")));
/**
* @brief Set connection type of touch channel in idle status.

46
components/driver/esp32s3/touch_sensor.c
View File

@ -90,25 +90,55 @@ esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_ma
return ret;
}
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)
esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle)
{
TOUCH_ENTER_CRITICAL();
touch_hal_set_meas_times(meas_times);
touch_hal_set_sleep_time(sleep_cycle);
touch_hal_set_sleep_time(interval_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle)
{
TOUCH_NULL_POINTER_CHECK(interval_cycle, "interval_cycle");
TOUCH_ENTER_CRITICAL();
touch_hal_get_sleep_time(interval_cycle);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times)
{
TOUCH_ENTER_CRITICAL();
touch_hal_set_meas_times(charge_discharge_times);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times)
{
TOUCH_NULL_POINTER_CHECK(charge_discharge_times, "charge_discharge_times");
TOUCH_ENTER_CRITICAL();
touch_hal_get_measure_times(charge_discharge_times);
TOUCH_EXIT_CRITICAL();
return ESP_OK;
}
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)
{
touch_pad_set_charge_discharge_times(meas_times);
touch_pad_set_measurement_interval(sleep_cycle);
return ESP_OK;
}
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times)
{
TOUCH_NULL_POINTER_CHECK(sleep_cycle, "sleep_cycle");
TOUCH_NULL_POINTER_CHECK(meas_times, "meas_times");
TOUCH_ENTER_CRITICAL();
touch_hal_get_measure_times(meas_times);
touch_hal_get_sleep_time(sleep_cycle);
TOUCH_EXIT_CRITICAL();
touch_pad_get_measurement_interval(sleep_cycle);
touch_pad_get_charge_discharge_times(meas_times);
return ESP_OK;
}

3
components/driver/test/touch_sensor_test/test_touch_v1.c
View File

@ -222,7 +222,8 @@ static int test_touch_parameter(touch_pad_t pad_num, int meas_time, int slp_time
TEST_ESP_OK( touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER) );
TEST_ESP_OK( touch_pad_config(pad_num, TOUCH_READ_INVALID_VAL) );
touch_pad_set_meas_time(slp_time, meas_time);
touch_pad_set_measurement_interval(slp_time);
touch_pad_set_measurement_clock_cycles(meas_time);
touch_pad_set_voltage(vol_h, vol_l, vol_a);
touch_pad_set_cnt_mode(pad_num, slope, TOUCH_PAD_TIE_OPT_DEFAULT);

6
components/driver/test/touch_sensor_test/test_touch_v2.c
View File

@ -434,7 +434,8 @@ int test_touch_base_parameter(touch_pad_t pad_num, int meas_time, int slp_time,
}
TEST_ESP_OK( touch_pad_set_cnt_mode(pad_num, slope, TOUCH_PAD_TIE_OPT_DEFAULT) );
TEST_ESP_OK( touch_pad_set_meas_time(slp_time, meas_time) );
TEST_ESP_OK( touch_pad_set_measurement_interval(slp_time) );
TEST_ESP_OK( touch_pad_set_charge_discharge_times(meas_time) );
TEST_ESP_OK( touch_pad_set_voltage(vol_h, vol_l, vol_a) );
TEST_ESP_OK( touch_pad_set_idle_channel_connect(is_conn_gnd) );
ESP_LOGI(TAG, "meas_time[%d]_slp_time[%d]_vol_h[%d]_vol_l[%d]_vol_a[%d]_slope[%d]_is_conn_gnd[%d]",
@ -1984,7 +1985,8 @@ TEST_CASE("Touch Sensor sleep pad wakeup deep sleep test", "[touch][ignore]")
test_deep_sleep_init();
/* Change the work duty of touch sensor to reduce current. */
touch_pad_set_meas_time(100, TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_measurement_interval(100);
touch_pad_set_charge_discharge_times(TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
/* Close PD current in deep sleep. */
RTCCNTL.bias_conf.pd_cur_deep_slp = 1;

22
components/touch_element/touch_element.c
View File

@ -1,16 +1,8 @@
// 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.
/*
* SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <string.h>
#include "freertos/FreeRTOS.h"
@ -599,7 +591,9 @@ static esp_err_t te_hw_init(const touch_elem_hw_config_t *hardware_init)
TE_CHECK(ret == ESP_OK, ret);
ret = touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER);
TE_CHECK(ret == ESP_OK, ret);
ret = touch_pad_set_meas_time(hardware_init->sleep_cycle, hardware_init->sample_count);
ret = touch_pad_set_measurement_interval(hardware_init->sleep_cycle);
TE_CHECK(ret == ESP_OK, ret);
ret = touch_pad_set_charge_discharge_times(hardware_init->sample_count);
TE_CHECK(ret == ESP_OK, ret);
ret = touch_pad_set_voltage(hardware_init->upper_voltage, hardware_init->lower_voltage,
hardware_init->voltage_attenuation);

35
docs/en/api-reference/peripherals/touch_pad.rst
View File

@ -84,12 +84,37 @@ Touch State Measurements
For the demonstration of how to read the touch pad data, check the application example :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_read`.
Method of Measurements
^^^^^^^^^^^^^^^^^^^^^^
.. only:: SOC_TOUCH_VERSION_1
The touch sensor will count the number of charge/discharge cycles over a fixed period of time (specified by :cpp:func:`touch_pad_set_measurement_clock_cycles`). The count result is the raw data that read from :cpp:func:`touch_pad_read_raw_data`. After finishing one measurement, the touch sensor will sleep until the next measurement start, this interval between two measurements can be set by :cpp:func:`touch_pad_set_measurement_interval`.
.. note::
If the specified clock cycles for measurement is too samll, the result may be inaccurate, but increasing clock cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the inverval and measurement is too long.
.. only:: SOC_TOUCH_VERSION_2
The touch sensor will record the period of time (i.e. the number of clock cycles) over a fixed charge/discharge cycles (specified by :cpp:func:`touch_pad_set_charge_discharge_times`). The count result is the raw data that read from :cpp:func:`touch_pad_read_raw_data`. After finishing one measurement, the touch sensor will sleep until the next measurement start, this interval between two measurements can be set by :cpp:func:`touch_pad_set_measurement_interval`.
.. note::
If the specified charge and discharge cycles for measurement is too samll, the result may be inaccurate, but increasing charge and discharge cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the inverval and measurement is too long.
Optimization of Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A touch sensor has several configurable parameters to match the characteristics of a particular touch pad design. For instance, to sense smaller capacity changes, it is possible to narrow down the reference voltage range within which the touch pads are charged / discharged. The high and low reference voltages are set using the function :cpp:func:`touch_pad_set_voltage`.
Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with :cpp:func:`touch_pad_set_meas_time`.
.. only:: SOC_TOUCH_VERSION_1
Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with :cpp:func:`touch_pad_set_measurement_clock_cycles`.
.. only:: SOC_TOUCH_VERSION_2
Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with :cpp:func:`touch_pad_set_charge_discharge_times`.
The following list summarizes available measurement parameters and corresponding 'set' functions:
@ -98,7 +123,13 @@ The following list summarizes available measurement parameters and corresponding
* voltage range: :cpp:func:`touch_pad_set_voltage`
* speed (slope): :cpp:func:`touch_pad_set_cnt_mode`
* Measurement time: :cpp:func:`touch_pad_set_meas_time`
.. only:: SOC_TOUCH_VERSION_1
* Clock cycles of one measurement: :cpp:func:`touch_pad_set_measurement_clock_cycles`
.. only:: SOC_TOUCH_VERSION_2
* Charge and discharge times of one measurement: :cpp:func:`touch_pad_set_charge_discharge_times`
Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown in the figure below.

35
docs/zh_CN/api-reference/peripherals/touch_pad.rst
View File

@ -84,12 +84,37 @@
请参考应用示例 :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_read`，查看如何使用读取触摸传感器数据。
测量方式
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. only:: SOC_TOUCH_VERSION_1
触摸传感器会统计固定时间内的充放电次数，其计数结果即为原始数据，可由 :cpp:func:`touch_pad_read_raw_data` 读出。上述固定时间可通过 :cpp:func:`touch_pad_set_measurement_clock_cycles` 设置。完成一次测量后，触摸传感器会在下次测量开始前保持睡眠状态。两次测量之前的间隔时间可由 :cpp:func:`touch_pad_set_measurement_interval` 进行设置。
.. note::
若设置的计数时间太短（即测量持续的时钟周期数太小），则可能导致结果不准确，但是过大的计数时间也会造成功耗上升。另外，若睡眠时间加测量时间的总时间过长，则会造成触摸传感器响应变慢。
.. only:: SOC_TOUCH_VERSION_2
触摸传感器会统计固定充放电次数所需的时间（即所需时钟周期数），其结果即为原始数据，可由 :cpp:func:`touch_pad_read_raw_data` 读出。上述固定的充放电次数可通过 :cpp:func:`touch_pad_set_charge_discharge_times` 设置。完成一次测量后，触摸传感器会在下次测量开始前保持睡眠状态。两次测量之前的间隔时间可由 :cpp:func:`touch_pad_set_measurement_interval` 进行设置。
.. note::
若设置的充放电次数太少，则可能导致结果不准确，但是充放电次数过多也会造成功耗上升。另外，若睡眠时间加测量时间的总时间过长，则会造成触摸传感器响应变慢。
优化测量
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
触摸传感器设有数个可配置参数，以适应触摸传感器设计特点。例如，如果需要感知较细微的电容变化，则可以缩小触摸传感器充放电的参考电压范围。用户可以使用 :cpp:func:`touch_pad_set_voltage` 函数设置电压参考低值和参考高值。
优化测量除了可以识别细微的电容变化之外，还可以降低应用程序功耗，但可能会增加测量噪声干扰。如果得到的动态读数范围结果比较理想，则可以调用 :cpp:func:`touch_pad_set_meas_time` 函数来减少测量时间，从而进一步降低功耗。
.. only:: SOC_TOUCH_VERSION_1
优化测量除了可以识别细微的电容变化之外，还可以降低应用程序功耗，但可能会增加测量噪声干扰。如果得到的动态读数范围结果比较理想，则可以调用 :cpp:func:`touch_pad_set_measurement_clock_cycles` 函数来减少测量时间，从而进一步降低功耗。
.. only:: SOC_TOUCH_VERSION_2
优化测量除了可以识别细微的电容变化之外，还可以降低应用程序功耗，但可能会增加测量噪声干扰。如果得到的动态读数范围结果比较理想，则可以调用 :cpp:func:`touch_pad_set_charge_discharge_times` 函数来减少测量时间，从而进一步降低功耗。
可用的测量参数及相应的 'set' 函数总结如下：
@ -98,7 +123,13 @@
* 电压门限：:cpp:func:`touch_pad_set_voltage`
* 速率（斜率） :cpp:func:`touch_pad_set_cnt_mode`
* 测量时间：:cpp:func:`touch_pad_set_meas_time`
.. only:: SOC_TOUCH_VERSION_1
* 单次测量所用的时钟周期：:cpp:func:`touch_pad_set_measurement_clock_cycles`
.. only:: SOC_TOUCH_VERSION_2
* 单次测量所需充放电次数：:cpp:func:`touch_pad_set_charge_discharge_times`
电压门限（参考低值/参考高值）、速率（斜率）与测量时间的关系如下图所示：

3
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt/main/tp_interrupt_main.c
View File

@ -159,7 +159,8 @@ void app_main(void)
#if TOUCH_CHANGE_CONFIG
/* If you want change the touch sensor default setting, please write here(after initialize). There are examples: */
touch_pad_set_meas_time(TOUCH_PAD_SLEEP_CYCLE_DEFAULT, TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_measurement_interval(TOUCH_PAD_SLEEP_CYCLE_DEFAULT);
touch_pad_set_charge_discharge_times(TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_voltage(TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD, TOUCH_PAD_LOW_VOLTAGE_THRESHOLD, TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD);
touch_pad_set_idle_channel_connect(TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT);
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {

3
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_read/main/tp_read_main.c
View File

@ -62,7 +62,8 @@ void app_main(void)
}
#if TOUCH_CHANGE_CONFIG
/* If you want change the touch sensor default setting, please write here(after initialize). There are examples: */
touch_pad_set_meas_time(TOUCH_PAD_SLEEP_CYCLE_DEFAULT, TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_measurement_interval(TOUCH_PAD_SLEEP_CYCLE_DEFAULT);
touch_pad_set_charge_discharge_times(TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_voltage(TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD, TOUCH_PAD_LOW_VOLTAGE_THRESHOLD, TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD);
touch_pad_set_idle_channel_connect(TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT);
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {

1
tools/ci/check_copyright_ignore.txt
View File

@ -1461,7 +1461,6 @@ components/touch_element/test/test_touch_element.c
components/touch_element/test/test_touch_matrix.c
components/touch_element/test/test_touch_slider.c
components/touch_element/touch_button.c
components/touch_element/touch_element.c
components/touch_element/touch_matrix.c
components/touch_element/touch_slider.c
components/ulp/esp32ulp_mapgen.py