esp_adc: added adc filter doc, and filter migration guides

components/esp_adc/adc_filter.c

@@ -85,8 +85,6 @@ static esp_err_t s_adc_filter_free(adc_iir_filter_t *filter_ctx)
 #endif
 
 
-
-
 esp_err_t adc_new_continuous_iir_filter(adc_continuous_handle_t handle, const adc_continuous_iir_filter_config_t *config, adc_iir_filter_handle_t *ret_hdl)
 {
     esp_err_t ret = ESP_FAIL;

components/esp_adc/include/esp_adc/adc_filter.h

@@ -33,7 +33,7 @@ typedef struct {
 
 
 /**
- * @brief New a ADC continuous mode IIR filter
+ * @brief New an ADC continuous mode IIR filter
  *
  * @param[in]   handle   ADC continuous mode driver handle
  * @param[in]   config   Filter configuration

docs/en/api-reference/peripherals/adc_continuous.rst

@@ -71,6 +71,26 @@ After setting up above configurations for the ADC, call :cpp:func:`adc_continuou
 If the ADC continuous mode driver is no longer used, you should deinitialize the driver by calling :cpp:func:`adc_continuous_deinit`.
 
 
+.. only:: SOC_ADC_DIG_IIR_FILTER_SUPPORTED
+
+    Two IIR filters are available when ADC is working under continuous mode. To create an ADC IIR filter, you should set up the :cpp:type:`adc_continuous_iir_filter_config_t`, and call :cpp:func:`adc_new_continuous_iir_filter`.
+
+    - :cpp:member:`adc_digi_filter_config_t::unit`, ADC  unit.
+    - :cpp:member:`adc_digi_filter_config_t::channel`, ADC channel to be filtered.
+    - :cpp:member:`adc_digi_filter_config_t::coeff`, filter coefficient.
+
+    .. only:: SOC_ADC_DIG_IIR_FILTER_UNIT_BINDED
+
+            On ESP32S2, the filter is per ADC unit. Once a filter is enabled, all the enabled ADC channels in this ADC unit will be filtered. However, we suggest only enabling one ADC channel per unit, when using the filter feature. Because the filtered results depend on the previous filtered result. So you should not enable multiple ADC channels, to avoid mixing the filtered results.
+
+    To recycle a filter, you should call :cpp:func:`adc_del_continuous_iir_filter`.
+
+    .. only:: not SOC_ADC_DIG_IIR_FILTER_UNIT_BINDED
+
+        .. note::
+
+            If you use both the filters on a same ADC channel, then only the first one will take effect.
+
 Initialize the ADC Continuous Mode Driver
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -120,6 +140,10 @@ This API may fail due to reasons like :c:macro:`ESP_ERR_INVALID_ARG`. When it re
 See ADC continuous mode example :example:`peripherals/adc/continuous_read` to see configuration codes.
 
 
+.. only:: SOC_ADC_DIG_IIR_FILTER_SUPPORTED
+
+    To enable / disable the ADC IIR filter, you should call :cpp:func:`adc_continuous_iir_filter_enable` / :cpp:func:`adc_continuous_iir_filter_disable`.
+
 ADC Control
 ^^^^^^^^^^^
 

docs/en/migration-guides/release-5.x/5.0/peripherals.rst

@@ -70,6 +70,7 @@ API Changes
 
 - API ``hall_sensor_read`` on ESP32 has been removed. Hall sensor is no longer supported on ESP32.
 - API ``adc_set_i2s_data_source`` and ``adc_i2s_mode_init`` have been deprecated. Related enum ``adc_i2s_source_t`` has been deprecated. Please migrate to use ``esp_adc/adc_continuous.h``.
+- API ``adc_digi_filter_reset``, ``adc_digi_filter_set_config``, ``adc_digi_filter_get_config`` and ``adc_digi_filter_enable`` have been removed. These APIs behaviours are not guaranteed. Enum ``adc_digi_filter_idx_t``, ``adc_digi_filter_mode_t`` and structure ``adc_digi_iir_filter_t`` have been removed as well.
 
 GPIO
 ----

docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst

@@ -70,6 +70,7 @@ API 更新
 
 - ESP32 中的 API ``hall_sensor_read`` 已被删除，因此 ESP32 不再支持霍尔传感器。
 - API ``adc_set_i2s_data_source`` 和 ``adc_i2s_mode_init`` 已被弃用，相关的枚举 ``adc_i2s_source_t`` 也已被弃用，请使用 ``esp_adc/adc_continuous.h`` 进行迁移。
+- API ``adc_digi_filter_reset`` ， ``adc_digi_filter_set_config`` ， ``adc_digi_filter_get_config`` 和 ``adc_digi_filter_enable`` 已被移除. 这些接口的行为不被保证。 枚举 ``adc_digi_filter_idx_t`` ， ``adc_digi_filter_mode_t`` 和结构体 ``adc_digi_iir_filter_t`` 已被移除。
 
 GPIO
 ----------