1 /*
2  * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /*----------------------------------------------------------------------------------
8               This file contains Deprecated ADC APIs
9 -----------------------------------------------------------------------------------*/
10 
11 #pragma once
12 #include "sdkconfig.h"
13 #include "esp_err.h"
14 #include "driver/gpio.h"
15 #include "driver/adc_types_legacy.h"
16 #include "hal/adc_types.h"
17 
18 #if !defined(__ZEPHYR__)
19 #if !CONFIG_ADC_SUPPRESS_DEPRECATE_WARN
20 #warning "legacy adc driver is deprecated, please migrate to use esp_adc/adc_oneshot.h and esp_adc/adc_continuous.h for oneshot mode and continuous mode drivers respectively"
21 #endif
22 #endif // !defined(__ZEPHYR__)
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /*---------------------------------------------------------------
29             Deprecated API
30 ---------------------------------------------------------------*/
31 /*---------------------------------------------------------------
32                     ADC Single Read Setting
33 ---------------------------------------------------------------*/
34 /**
35  * @brief Get the GPIO number of a specific ADC1 channel.
36  *
37  * @param channel Channel to get the GPIO number
38  * @param gpio_num output buffer to hold the GPIO number
39  *
40  * @return
41  *   - ESP_OK if success
42  *   - ESP_ERR_INVALID_ARG if channel not valid
43  */
44 esp_err_t adc1_pad_get_io_num(adc1_channel_t channel, gpio_num_t *gpio_num);
45 
46 /**
47  * @brief Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.
48  *
49  * The default ADC voltage is for attenuation 0 dB and listed in the table below.
50  * By setting higher attenuation it is possible to read higher voltages.
51  *
52  * Due to ADC characteristics, most accurate results are obtained within the "suggested range"
53  * shown in the following table.
54  *
55  *     +----------+-------------+-----------------+
56  *     |          | attenuation | suggested range |
57  *     |    SoC   |     (dB)    |      (mV)       |
58  *     +==========+=============+=================+
59  *     |          |       0     |    100 ~  950   |
60  *     |          +-------------+-----------------+
61  *     |          |       2.5   |    100 ~ 1250   |
62  *     |   ESP32  +-------------+-----------------+
63  *     |          |       6     |    150 ~ 1750   |
64  *     |          +-------------+-----------------+
65  *     |          |      11     |    150 ~ 2450   |
66  *     +----------+-------------+-----------------+
67  *     |          |       0     |      0 ~  750   |
68  *     |          +-------------+-----------------+
69  *     |          |       2.5   |      0 ~ 1050   |
70  *     | ESP32-S2 +-------------+-----------------+
71  *     |          |       6     |      0 ~ 1300   |
72  *     |          +-------------+-----------------+
73  *     |          |      11     |      0 ~ 2500   |
74  *     +----------+-------------+-----------------+
75  *
76  * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
77  *
78  * @note For any given channel, this function must be called before the first time ``adc1_get_raw()`` is called for that channel.
79  *
80  * @note This function can be called multiple times to configure multiple
81  *       ADC channels simultaneously. You may call ``adc1_get_raw()`` only after configuring a channel.
82  *
83  * @param channel ADC1 channel to configure
84  * @param atten  Attenuation level
85  *
86  * @return
87  *     - ESP_OK success
88  *     - ESP_ERR_INVALID_ARG Parameter error
89  */
90 esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten);
91 
92 /**
93  * @brief Configure ADC1 capture width, meanwhile enable output invert for ADC1.
94  *        The configuration is for all channels of ADC1
95  * @param width_bit Bit capture width for ADC1
96  *
97  * @return
98  *     - ESP_OK success
99  *     - ESP_ERR_INVALID_ARG Parameter error
100  */
101 esp_err_t adc1_config_width(adc_bits_width_t width_bit);
102 
103 /**
104  * @brief Take an ADC1 reading from a single channel.
105  * @note ESP32:
106  *       When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on,
107  *       the input of GPIO36 and GPIO39 will be pulled down for about 80ns.
108  *       When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39.
109  *       Please refer to section 3.11 of 'ECO_and_Workarounds_for_Bugs_in_ESP32' for the description of this issue.
110  *       As a workaround, call sar_periph_ctrl_adc_oneshot_power_acquire() in the app. This will result in higher power consumption (by ~1mA),
111  *       but will remove the glitches on GPIO36 and GPIO39.
112  *
113  * @note Call ``adc1_config_width()`` before the first time this
114  *       function is called.
115  *
116  * @note For any given channel, adc1_config_channel_atten(channel)
117  *       must be called before the first time this function is called. Configuring
118  *       a new channel does not prevent a previously configured channel from being read.
119  *
120  * @param  channel ADC1 channel to read
121  *
122  * @return
123  *     - -1: Parameter error
124  *     -  Other: ADC1 channel reading.
125  */
126 int adc1_get_raw(adc1_channel_t channel);
127 
128 #if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
129 //TODO IDF-3610, replace these with proper caps
130 /**
131  * @brief Set ADC data invert
132  * @param adc_unit ADC unit index
133  * @param inv_en whether enable data invert
134  * @return
135  *     - ESP_OK success
136  *     - ESP_ERR_INVALID_ARG Parameter error
137  */
138 esp_err_t adc_set_data_inv(adc_unit_t adc_unit, bool inv_en);
139 
140 /**
141  * @brief Set ADC source clock
142  * @param clk_div ADC clock divider, ADC clock is divided from APB clock
143  * @return
144  *     - ESP_OK success
145  */
146 esp_err_t adc_set_clk_div(uint8_t clk_div);
147 
148 /**
149  * @brief Configure ADC capture width.
150  *
151  * @param adc_unit ADC unit index
152  * @param width_bit Bit capture width for ADC unit.
153  *
154  * @return
155  *     - ESP_OK success
156  *     - ESP_ERR_INVALID_ARG Parameter error
157  */
158 esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit);
159 
160 /**
161  * @brief Configure ADC1 to be usable by the ULP
162  *
163  * This function reconfigures ADC1 to be controlled by the ULP.
164  * Effect of this function can be reverted using ``adc1_get_raw()`` function.
165  *
166  * Note that adc1_config_channel_atten, ``adc1_config_width()`` functions need
167  * to be called to configure ADC1 channels, before ADC1 is used by the ULP.
168  */
169 void adc1_ulp_enable(void);
170 #endif  //#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
171 
172 #if (SOC_ADC_PERIPH_NUM >= 2)
173 /**
174  * @brief Get the GPIO number of a specific ADC2 channel.
175  *
176  * @param channel Channel to get the GPIO number
177  *
178  * @param gpio_num output buffer to hold the GPIO number
179  *
180  * @return
181  *   - ESP_OK if success
182  *   - ESP_ERR_INVALID_ARG if channel not valid
183  */
184 esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num);
185 
186 /**
187  * @brief Configure the ADC2 channel, including setting attenuation.
188  *
189  * The default ADC voltage is for attenuation 0 dB and listed in the table below.
190  * By setting higher attenuation it is possible to read higher voltages.
191  *
192  * Due to ADC characteristics, most accurate results are obtained within the "suggested range"
193  * shown in the following table.
194  *
195  *     +----------+-------------+-----------------+
196  *     |          | attenuation | suggested range |
197  *     |    SoC   |     (dB)    |      (mV)       |
198  *     +==========+=============+=================+
199  *     |          |       0     |    100 ~  950   |
200  *     |          +-------------+-----------------+
201  *     |          |       2.5   |    100 ~ 1250   |
202  *     |   ESP32  +-------------+-----------------+
203  *     |          |       6     |    150 ~ 1750   |
204  *     |          +-------------+-----------------+
205  *     |          |      11     |    150 ~ 2450   |
206  *     +----------+-------------+-----------------+
207  *     |          |       0     |      0 ~  750   |
208  *     |          +-------------+-----------------+
209  *     |          |       2.5   |      0 ~ 1050   |
210  *     | ESP32-S2 +-------------+-----------------+
211  *     |          |       6     |      0 ~ 1300   |
212  *     |          +-------------+-----------------+
213  *     |          |      11     |      0 ~ 2500   |
214  *     +----------+-------------+-----------------+
215  *
216  * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
217  *
218  * @note This function also configures the input GPIO pin mux to
219  *       connect it to the ADC2 channel. It must be called before calling
220  *       ``adc2_get_raw()`` for this channel.
221  *
222  * @note For any given channel, this function must be called before the first time ``adc2_get_raw()`` is called for that channel.
223  *
224  * @param channel ADC2 channel to configure
225  * @param atten  Attenuation level
226  *
227  * @return
228  *     - ESP_OK success
229  *     - ESP_ERR_INVALID_ARG Parameter error
230  */
231 esp_err_t adc2_config_channel_atten(adc2_channel_t channel, adc_atten_t atten);
232 
233 /**
234  * @brief Take an ADC2 reading on a single channel
235  *
236  * @note ESP32:
237  *       When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on,
238  *       the input of GPIO36 and GPIO39 will be pulled down for about 80ns.
239  *       When enabling power for any of these peripherals, ignore input from GPIO36 and GPIO39.
240  *       Please refer to section 3.11 of 'ECO_and_Workarounds_for_Bugs_in_ESP32' for the description of this issue.
241  *       As a workaround, call sar_periph_ctrl_adc_oneshot_power_acquire() in the app. This will result in higher power consumption (by ~1mA),
242  *       but will remove the glitches on GPIO36 and GPIO39.
243  *
244  *
245  * @note ESP32:
246  *       For a given channel, ``adc2_config_channel_atten()``
247  *       must be called before the first time this function is called. If Wi-Fi is started via ``esp_wifi_start()``, this
248  *       function will always fail with ``ESP_ERR_TIMEOUT``.
249  *
250  * @note ESP32-S2:
251  *       ADC2 support hardware arbiter. The arbiter is to improve the use efficiency of ADC2. After the control right is robbed by the high priority,
252  *       the low priority controller will read the invalid ADC2 data. Default priority: Wi-Fi > RTC > Digital;
253  *
254  * @param channel ADC2 channel to read
255  * @param width_bit Bit capture width for ADC2
256  * @param raw_out the variable to hold the output data.
257  *
258  * @return
259  *     - ESP_OK if success
260  *     - ESP_ERR_TIMEOUT ADC2 is being used by other controller and the request timed out.
261  *     - ESP_ERR_INVALID_STATE The controller status is invalid. Please try again.
262  */
263 esp_err_t adc2_get_raw(adc2_channel_t channel, adc_bits_width_t width_bit, int *raw_out);
264 
265 /**
266  *  @brief Output ADC1 or ADC2's reference voltage to ``adc2_channe_t``'s IO.
267  *
268  *  This function routes the internal reference voltage of ADCn to one of
269  *  ADC2's channels. This reference voltage can then be manually measured
270  *  for calibration purposes.
271  *
272  *  @note  ESP32 only supports output of ADC2's internal reference voltage.
273  *  @param[in]  adc_unit ADC unit index
274  *  @param[in]  gpio     GPIO number (Only ADC2's channels IO are supported)
275  *
276  *  @return
277  *                  - ESP_OK: v_ref successfully routed to selected GPIO
278  *                  - ESP_ERR_INVALID_ARG: Unsupported GPIO
279  */
280 esp_err_t adc_vref_to_gpio(adc_unit_t adc_unit, gpio_num_t gpio);
281 #endif  //#if (SOC_ADC_PERIPH_NUM >= 2)
282 
283 
284 /*---------------------------------------------------------------
285             ADC DMA Read Setting
286 ---------------------------------------------------------------*/
287 #if SOC_ADC_DMA_SUPPORTED
288 /**
289  * @brief Initialize the Digital ADC.
290  *
291  * @param init_config Pointer to Digital ADC initilization config. Refer to ``adc_digi_init_config_t``.
292  *
293  * @return
294  *         - ESP_ERR_INVALID_ARG   If the combination of arguments is invalid.
295  *         - ESP_ERR_NOT_FOUND     No free interrupt found with the specified flags
296  *         - ESP_ERR_NO_MEM        If out of memory
297  *         - ESP_OK                On success
298  */
299 esp_err_t adc_digi_initialize(const adc_digi_init_config_t *init_config);
300 
301 /**
302  * @brief Read bytes from Digital ADC through DMA.
303  *
304  * @param[out] buf                 Buffer to read from ADC.
305  * @param[in]  length_max          Expected length of data read from the ADC.
306  * @param[out] out_length          Real length of data read from the ADC via this API.
307  * @param[in]  timeout_ms          Time to wait for data via this API, in millisecond.
308  *
309  * @return
310  *         - ESP_ERR_INVALID_STATE Driver state is invalid. Usually it means the ADC sampling rate is faster than the task processing rate.
311  *         - ESP_ERR_TIMEOUT       Operation timed out
312  *         - ESP_OK                On success
313  */
314 esp_err_t adc_digi_read_bytes(uint8_t *buf, uint32_t length_max, uint32_t *out_length, uint32_t timeout_ms);
315 
316 /**
317  * @brief Start the Digital ADC and DMA peripherals. After this, the hardware starts working.
318  *
319  * @return
320  *         - ESP_ERR_INVALID_STATE Driver state is invalid.
321  *         - ESP_OK                On success
322  */
323 esp_err_t adc_digi_start(void);
324 
325 /**
326  * @brief Stop the Digital ADC and DMA peripherals. After this, the hardware stops working.
327  *
328  * @return
329  *         - ESP_ERR_INVALID_STATE Driver state is invalid.
330  *         - ESP_OK                On success
331  */
332 esp_err_t adc_digi_stop(void);
333 
334 /**
335  * @brief Deinitialize the Digital ADC.
336  *
337  * @return
338  *         - ESP_ERR_INVALID_STATE Driver state is invalid.
339  *         - ESP_OK                On success
340  */
341 esp_err_t adc_digi_deinitialize(void);
342 
343 /**
344  * @brief Setting the digital controller.
345  *
346  * @param config Pointer to digital controller paramter. Refer to ``adc_digi_config_t``.
347  *
348  * @return
349  *      - ESP_ERR_INVALID_STATE Driver state is invalid.
350  *      - ESP_ERR_INVALID_ARG   If the combination of arguments is invalid.
351  *      - ESP_OK                On success
352  */
353 esp_err_t adc_digi_controller_configure(const adc_digi_configuration_t *config);
354 #endif
355 
356 #ifdef __cplusplus
357 }
358 #endif
359