ESP32-C3: ADC documentation issues (IDFGH-11205)

[cyberhuman]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

General issue report

When checking in the ESP-IDF Programming Guide documentation for ADC, I noticed two issues:

1. Here the programming guide mentions 11 dB attenuation:

enumerator ADC_ATTEN_DB_11
The input voltage of ADC will be attenuated extending the range of measurement by about 11 dB (3.55 x)

However, the TRM mentions 12 dB instead:

So which one is correct?

2. Here the programming guide mentions bit widths ranging from 9 to 13, but the TRM only mentions 12 bit and the formula has a fixed value of 4095:

Are bit widths other than 12 supported (emulated?) by ESP-IDF?

[Icarus113]

@cyberhuman

About the attenuation, both of them are wrong. Should be 10dB. We'll give a commit to fix this to ADC_ATTEN_DB_10 in the code.

We'll update the TRM as well.

About the bitwidth, there's check when using the ADC driver, other enums (except for ADC_BITWIDTH_12) are left for extensibility. ESP32C3 only supports 12bit.

[cyberhuman]

@Icarus113 I'm sorry but can you please confirm that the attenuation is indeed 10dB? I'm asking because I made some measurements and they don't quite match the provided number.

I have a battery-powered ESP32-C3 (via a voltage regulator of course). The battery output is connected to ADC1 channel 4 via a voltage divider, 2:1. The attenuation is set to ADC_ATTEN_DB_11. The reading I get in the one-shot mode is 2872. Using the formula, 2×1.1V×10^(10÷20)×2872÷4095=4.88V but my voltmeter shows 4.09V (all expected since it's a nearly charged LiPo battery).

Going backwards from the measured values, the attenuation is 20log(4.09V÷(2×1.1V×2872÷4095))=8.47. Even trying with Vref=1.0 or 1.2 the value is between 7.7dB and 9.3dB.

Are my calculations wrong, or am I missing something?

[Icarus113]

@cyberhuman Hi, sorry for the late update here. The condition is:

By design, when using the ADC_ATTEN_DB_11, the hardware will try to attenuate the input signal to its 1/4. This means by design the attenuation is 12dB. But in reality there are some errors there, so the code says it's attenuation is 1/3.55. This error is different among chips.

Besides, the 2×1.1V×10^(10÷20)×2872÷4095 is not a recommended way as 2872 is the raw result from the adc oneshot mode. ESP-IDF provided a calibration scheme to help you get real voltage number, see this adc_cali_raw_to_voltage API and this example.

Therefore you can select an attenuation based on this data in the C3 datasheet:

About the plan, as by design we expect the attenuation to be 12dB, we'll update the code to ADC_ATTEN_DB_12 later. And we'll try to give an attenuation error in the datasheet.

[cyberhuman]

@Icarus113 thank you for the explanation!
I saw the adc_cali_raw_to_voltage API but I was scared off from using it by unclear documentation. Some high-level description of how it is supposed to work is missing (or I just didn't manage to find it). Specifically, the ADC Calibration Driver documentation mentions the call adc_cali_create_scheme_curve_fitting may fail because "the calibration scheme required eFuse bits are not burnt on your board". The example you referred to also mentions it in the Troubleshooting section but it is not explained what needs to be done to use this functionality.
It would be great if the documentation explained it.

[cyberhuman]

@Icarus113 I went ahead with the ADC calibration driver and it worked out of the box. Thank you!
Still, more clarity in the documentation would still be greatly appreciated.

[Icarus113]

@cyberhuman

Thanks for the feedback. So you're confused because the lack of the description about failures due to ADC calibration related efuse bits, am I understanding this correctly?

The ADC calibration related doc is here by the way.

[cyberhuman]

@Icarus113 yes I was looking at that documentation page, and yes

confused because the lack of the description about failures due to ADC calibration related efuse bits

Especially, when the function return ESP_ERR_NOT_SUPPORTED, this means the calibration scheme required eFuse bits are not burnt on your board.

=> without the high level understanding of how the calibration works raises questions like

1. which exactly eFuse bits?
2. do I have to burn them myself? how?
   etc...

[Icarus113]

Hi @cyberhuman

Thanks for letting us know.

ESP-IDF provided ADC calibration scheme is based on the values in certain ADC calibration related on-chip eFuse bits. Espressif guarantees these bits during module manufacturing, so you don't have to burn theses eFuses bits yourself.

I will add some notes in the doc clarifying this, as well an official link to contact us.

[Icarus113]

Rename and deprecation commit: 0c81f41