alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-09-01 06:27:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/ledc_more_meaningful_parameter_names' into 'master'

Browse Source 
Provided more meaningful parameter names by renaming 'bit_num' to 'duty_resoluti…

See merge request !1440
This commit is contained in:
Jiang Jiang Jian
2017-12-01 19:33:53 +08:00
parent 7702e0f45b d488bb7bac
commit c672fc54fd
7 changed files with 109 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/api-reference/peripherals/ledc.rst
View File

@@ -38,9 +38,9 @@ Configure Timer
Setting of the timer is done by calling function :cpp:func:`ledc_timer_config`. This function should be provided with a data structure :cpp:type:`ledc_timer_config_t` that contains the following configuration settings:
* The timer number :cpp:type:`ledc_timer_t` and a speed mode :cpp:type:`ledc_mode_t`.
* The PWM signal's frequency and a "bit number". The later represents a resolution of PWM's duty value changes.
* The PWM signal's frequency and resolution of PWM's duty value changes.
The frequency and the bit values are interdependent. The higher the PWM frequency, the lower bit number is available and vice versa. This relationship may became important, if you are planning to use this API for purposes other that changing intensity of LEDs. Check section :ref:`ledc-api-supported-range-frequency-bit-number` for more details.
The frequency and the duty resolution are interdependent. The higher the PWM frequency, the lower duty resolution is available and vice versa. This relationship may became important, if you are planning to use this API for purposes other that changing intensity of LEDs. Check section :ref:`ledc-api-supported-range-frequency-duty-resolution` for more details.
.. _ledc-api-configure-channel:
@@ -70,7 +70,7 @@ Setting of the duty is done by first calling dedicated function :cpp:func:`ledc_
Another way to set the duty, and some other channel parameters as well, is by calling :cpp:func:`ledc_channel_config` discussed in the previous section.
The range of the duty value entered into functions depends on selected bit number (`` bit_num``) and should be from 0 to (2 ** bit_num) - 1. For example, if selected bit number is 10, then the duty range is from 0 to 1023. This provides the duty resolution of ~0.1%.
The range of the duty value entered into functions depends on selected ``duty_resolution`` and should be from 0 to (2 ** duty_resolution) - 1. For example, if selected duty resolution is 10, then the duty range is from 0 to 1023. This provides the resolution of ~0.1%.
Change PWM Duty with Hardware Fading
@@ -96,7 +96,7 @@ The LEDC API provides several means to change the PWM frequency "on the fly".
* One of options is to call :cpp:func:`ledc_set_freq`. There is a corresponding function :cpp:func:`ledc_get_freq` to check what frequency is currently set.
* Another option to change the frequency, and the bit number as well, is by calling :cpp:func:`ledc_bind_channel_timer` to bind other timer to the channel.
* Another option to change the frequency, and the duty resolution as well, is by calling :cpp:func:`ledc_bind_channel_timer` to bind other timer to the channel.
* Finally the channel's timer may be changed by calling :cpp:func:`ledc_channel_config`.
@@ -134,32 +134,32 @@ The advantage of the high speed mode is h/w supported, glitch-free changeover of
For additional details regarding speed modes please refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (PDF). Note that support for ``SLOW_CLOCK`` mentioned in this manual is not implemented in the LEDC API.
.. _ledc-api-supported-range-frequency-bit-number:
.. _ledc-api-supported-range-frequency-duty-resolution:
Supported Range of Frequency and Bit Number
-------------------------------------------
Supported Range of Frequency and Duty Resolution
------------------------------------------------
The LED PWM Controller is designed primarily to drive LEDs and provides wide resolution of PWM duty settings. The resolution (or granularity) of the PWM duty is determined by the "bit number". For instance for the PWM frequency at 5 kHz, the maximum bit number is 13 bits. It means that the duty may be set anywhere from 0 to 100% with resolution of ~0.012% (13 ** 2 = 8192 discrete levels of the LED intensity).
The LED PWM Controller is designed primarily to drive LEDs and provides wide resolution of PWM duty settings. For instance for the PWM frequency at 5 kHz, the maximum duty resolution is 13 bits. It means that the duty may be set anywhere from 0 to 100% with resolution of ~0.012% (13 ** 2 = 8192 discrete levels of the LED intensity).
The LEDC may be used for providing signals at much higher frequencies to clock other devices, e.g. a digital camera module. In such a case the maximum available frequency is 40 MHz with duty resolution of 1 bit. This means that duty is fixed at 50% and cannot be adjusted.
The API is designed to report an error when trying to set a frequency and a bit number that is out of the range of LEDC's hardware. For example, an attempt to set the frequency at 20 MHz and the bit number of 3 bits will result in the following error reported on a serial monitor:
The API is designed to report an error when trying to set a frequency and a duty resolution that is out of the range of LEDC's hardware. For example, an attempt to set the frequency at 20 MHz and the duty resolution of 3 bits will result in the following error reported on a serial monitor:
.. highlight:: none
::
E (196) ledc: requested frequency and bit number can not be achieved, try reducing freq_hz or bit_num. div_param=128
E (196) ledc: requested frequency and duty resolution can not be achieved, try reducing freq_hz or duty_resolution. div_param=128
In such a case either the bit number or the frequency should be reduced. For example setting the bit number at 2 will resolve this issue and provide possibility to set the duty with 25% steps, i.e. at 25%, 50% or 75%.
In such a case either the duty resolution or the frequency should be reduced. For example setting the duty resolution at 2 will resolve this issue and provide possibility to set the duty with 25% steps, i.e. at 25%, 50% or 75%.
The LEDC API will also capture and report an attempt to configure frequency / bit number combination that is below the supported minimum, e.g.:
The LEDC API will also capture and report an attempt to configure frequency / duty resolution combination that is below the supported minimum, e.g.:
::
E (196) ledc: requested frequency and bit depth can not be achieved, try increasing freq_hz or bit_num. div_param=128000000
E (196) ledc: requested frequency and duty resolution can not be achieved, try increasing freq_hz or duty_resolution. div_param=128000000
Setting of the bit number is normally done using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller bit number is required (below 10 down to 1), enter the equivalent numeric values directly.
Setting of the duty resolution is normally done using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (below 10 down to 1), enter the equivalent numeric values directly.
Application Example