docs: correct ledc duty value range (IDFGH-10254)

[jonschz]

As discussed e.g. here, the maximum value for duty in ledc_set_duty_with_hpoint is 2**duty_resolution, not 2**duty_resolution - 1. At the moment, the documentation is inconsistent; some places have the correct range, others do not.

The fact that 2**duty_resolution is correct can also be seen in the data sheet of the ESP32 (see pages 383-384): Suppose DUTY_RESOLUTION = 10 and HPOINT = 0. If DUTY = 1023, the PWM output goes high when the counter starts at 0, then it goes low when the counter reaches 1023, and goes back up high one tick later when the counter rolls back to 0. Therefore, a value of DUTY=1023 corresponds to an output that is high 99.90 % of the time. To get an output that is high permanently, we need to set DUTY=1024.

[CLAassistant]

All committers have signed the CLA.

[songruo]

Thanks for the contribution. I am aware of the issue, it might take some time to confirm the hardware behavior on all chips, and to check whether anything need to be changed in the driver. I will come back to this PR once I confirm!

[jonschz]

Just for reference: The implementation of analogWrite() is aware of this issue and maps an input of 2**duty_resolution - 1 to 2**duty_resolution:

https://github.com/espressif/arduino-esp32/blob/72c41d09538663ebef80d29eb986cd5bc3395c2d/cores/esp32/esp32-hal-ledc.c#L89-L94C1

Maybe this is another reason for the confusion.

[songruo]

Hi forks,

Sorry for the long wait. I have confirmed that 2**duty_resolution (i.e. 100% duty cycle) is a feasible duty in most circumstances. The case where this duty value would cause problem is when the binded timer is selecting its maximum duty resolution.

For example, on ESP32C3, the maximum duty resolution for the LEDC timer is 14 bits. Therefore, you won't be enable to set duty to (2**14). Otherwise, the duty calculation in the hardware will be messed up.

This is caused by a hardware bug which exists on all existing chips. The bug is planned to be fixed for the new chips.

So please be aware of this restriction while setting duty values. Fix and modification to the IDF is on the way, it should be merged to master shortly.

[jonschz]

Thank you for checking. Will this PR be obsolete then?

[songruo]

@jonschz This PR will be automatically closed when the changes are synced to Github. Still, thanks for raising the discussion and submitting the PR!