dd4a7d6c5e
* Adds the ability to set the clock source for the LEDC * feat(LEDC): Adjusting function names to more suitable * feat(LEDC): Fix clock_source to static * docs(ledc): Document ledc set and get clock source * docs(ledc): Update ledcSetClockSource description * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
341 lines
9.7 KiB
ReStructuredText
341 lines
9.7 KiB
ReStructuredText
##################
|
|
LED Control (LEDC)
|
|
##################
|
|
|
|
About
|
|
-----
|
|
The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs,
|
|
although it can also be used to generate PWM signals for other purposes.
|
|
|
|
ESP32 SoCs has from 6 to 16 channels (variates on socs, see table below) which can generate independent waveforms, that can be used for example to drive RGB LED devices.
|
|
|
|
========= =======================
|
|
ESP32 SoC Number of LEDC channels
|
|
========= =======================
|
|
ESP32 16
|
|
ESP32-S2 8
|
|
ESP32-S3 8
|
|
ESP32-C3 6
|
|
ESP32-C6 6
|
|
ESP32-H2 6
|
|
========= =======================
|
|
|
|
Arduino-ESP32 LEDC API
|
|
----------------------
|
|
|
|
ledcSetCLockSource
|
|
******************
|
|
|
|
This function is used to set the LEDC peripheral clock source. Must be called before any LEDC channel is used.
|
|
The default clock source is XTAL clock (``LEDC_USE_XTAL_CLK``) if supported by the SoC, otherwise it is AUTO clock (``LEDC_AUTO_CLK``).
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcSetClockSource(ledc_clk_cfg_t source);
|
|
|
|
* ``source`` select the clock source for LEDC peripheral.
|
|
|
|
* ``LEDC_APB_CLK`` - APB clock.
|
|
* ``LEDC_REF_CLK`` - REF clock.
|
|
|
|
This function will return ``true`` if setting the clock source is successful, otherwise it will return ``false``.
|
|
|
|
ledcGetClockSource
|
|
******************
|
|
|
|
This function is used to get the LEDC peripheral clock source.
|
|
|
|
.. code-block:: arduino
|
|
|
|
ledc_clk_cfg_t ledcGetClockSource(void);
|
|
|
|
This function will return the clock source for the LEDC peripheral.
|
|
|
|
ledcAttach
|
|
**********
|
|
|
|
This function is used to setup LEDC pin with given frequency and resolution. LEDC channel will be selected automatically.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcAttach(uint8_t pin, uint32_t freq, uint8_t resolution);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``freq`` select frequency of pwm.
|
|
* ``resolution`` select resolution for LEDC channel.
|
|
|
|
* range is 1-14 bits (1-20 bits for ESP32).
|
|
|
|
This function will return ``true`` if configuration is successful.
|
|
If ``false`` is returned, error occurs and LEDC channel was not configured.
|
|
|
|
ledcAttachChannel
|
|
*****************
|
|
|
|
This function is used to setup LEDC pin with given frequency, resolution and channel.
|
|
Attaching multiple pins to the same channel will make them share the same duty cycle. Given frequency, resolution will be ignored if channel is already configured.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcAttachChannel(uint8_t pin, uint32_t freq, uint8_t resolution, int8_t channel);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``freq`` select frequency of pwm.
|
|
* ``resolution`` select resolution for LEDC channel.
|
|
|
|
* range is 1-14 bits (1-20 bits for ESP32).
|
|
|
|
* ``channel`` select LEDC channel.
|
|
|
|
This function will return ``true`` if configuration is successful.
|
|
If ``false`` is returned, error occurs and LEDC channel was not configured.
|
|
|
|
ledcWrite
|
|
*********
|
|
|
|
This function is used to set duty for the LEDC pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcWrite(uint8_t pin, uint32_t duty);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``duty`` select duty to be set for selected LEDC pin.
|
|
|
|
This function will return ``true`` if setting duty is successful.
|
|
If ``false`` is returned, error occurs and duty was not set.
|
|
|
|
ledcWriteChannel
|
|
****************
|
|
|
|
This function is used to set duty for the LEDC channel.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcWriteChannel(uint8_t channel, uint32_t duty);
|
|
|
|
* ``channel`` select LEDC channel.
|
|
* ``duty`` select duty to be set for selected LEDC channel.
|
|
|
|
This function will return ``true`` if setting duty is successful.
|
|
If ``false`` is returned, error occurs and duty was not set.
|
|
|
|
ledcRead
|
|
********
|
|
|
|
This function is used to get configured duty for the LEDC pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
uint32_t ledcRead(uint8_t pin);
|
|
|
|
* ``pin`` select LEDC pin to read the configured LEDC duty.
|
|
|
|
This function will return ``duty`` set for selected LEDC pin.
|
|
|
|
ledcReadFreq
|
|
************
|
|
|
|
This function is used to get configured frequency for the LEDC channel.
|
|
|
|
.. code-block:: arduino
|
|
|
|
uint32_t ledcReadFreq(uint8_t pin);
|
|
|
|
* ``pin`` select LEDC pin to read the configured frequency.
|
|
|
|
This function will return ``frequency`` configured for selected LEDC pin.
|
|
|
|
ledcWriteTone
|
|
*************
|
|
|
|
This function is used to setup the LEDC pin to 50 % PWM tone on selected frequency.
|
|
|
|
.. code-block:: arduino
|
|
|
|
uint32_t ledcWriteTone(uint8_t pin, uint32_t freq);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``freq`` select frequency of pwm signal. If frequency is ``0``, duty will be set to 0.
|
|
|
|
This function will return ``frequency`` set for LEDC pin.
|
|
If ``0`` is returned, error occurs and LEDC pin was not configured.
|
|
|
|
ledcWriteNote
|
|
*************
|
|
|
|
This function is used to setup the LEDC pin to specific note.
|
|
|
|
.. code-block:: arduino
|
|
|
|
uint32_t ledcWriteNote(uint8_t pin, note_t note, uint8_t octave);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``note`` select note to be set.
|
|
|
|
======= ======= ======= ======= ======= ======
|
|
NOTE_C NOTE_Cs NOTE_D NOTE_Eb NOTE_E NOTE_F
|
|
NOTE_Fs NOTE_G NOTE_Gs NOTE_A NOTE_Bb NOTE_B
|
|
======= ======= ======= ======= ======= ======
|
|
|
|
* ``octave`` select octave for note.
|
|
|
|
This function will return ``frequency`` configured for the LEDC pin according to note and octave inputs.
|
|
If ``0`` is returned, error occurs and the LEDC channel was not configured.
|
|
|
|
ledcDetach
|
|
**********
|
|
|
|
This function is used to detach the pin from LEDC.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcDetach(uint8_t pin);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
|
|
This function returns ``true`` if detaching was successful.
|
|
If ``false`` is returned, an error occurred and the pin was not detached.
|
|
|
|
ledcChangeFrequency
|
|
*******************
|
|
|
|
This function is used to set frequency for the LEDC pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
uint32_t ledcChangeFrequency(uint8_t pin, uint32_t freq, uint8_t resolution);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``freq`` select frequency of pwm.
|
|
* ``resolution`` select resolution for LEDC channel.
|
|
|
|
* range is 1-14 bits (1-20 bits for ESP32).
|
|
|
|
This function will return ``frequency`` configured for the LEDC channel.
|
|
If ``0`` is returned, error occurs and the LEDC channel frequency was not set.
|
|
|
|
ledcOutputInvert
|
|
****************
|
|
|
|
This function is used to set inverting output for the LEDC pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcOutputInvert(uint8_t pin, bool out_invert);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``out_invert`` select, if output should be inverted (true = inverting output).
|
|
|
|
This function returns ``true`` if setting inverting output was successful.
|
|
If ``false`` is returned, an error occurred and the inverting output was not set.
|
|
|
|
ledcFade
|
|
********
|
|
|
|
This function is used to setup and start fade for the LEDC pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcFade(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``start_duty`` select starting duty of fade.
|
|
* ``target_duty`` select target duty of fade.
|
|
* ``max_fade_time_ms`` select maximum time for fade.
|
|
|
|
This function will return ``true`` if configuration is successful.
|
|
If ``false`` is returned, error occurs and LEDC fade was not configured / started.
|
|
|
|
ledcFadeWithInterrupt
|
|
*********************
|
|
|
|
This function is used to setup and start fade for the LEDC pin with interrupt.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcFadeWithInterrupt(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms, void (*userFunc)(void));
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``start_duty`` select starting duty of fade.
|
|
* ``target_duty`` select target duty of fade.
|
|
* ``max_fade_time_ms`` select maximum time for fade.
|
|
* ``userFunc`` function to be called when interrupt is triggered.
|
|
|
|
This function will return ``true`` if configuration is successful and fade start.
|
|
If ``false`` is returned, error occurs and LEDC fade was not configured / started.
|
|
|
|
ledcFadeWithInterruptArg
|
|
************************
|
|
|
|
This function is used to setup and start fade for the LEDC pin with interrupt using arguments.
|
|
|
|
.. code-block:: arduino
|
|
|
|
bool ledcFadeWithInterruptArg(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms, void (*userFunc)(void*), void * arg);
|
|
|
|
* ``pin`` select LEDC pin.
|
|
* ``start_duty`` select starting duty of fade.
|
|
* ``target_duty`` select target duty of fade.
|
|
* ``max_fade_time_ms`` select maximum time for fade.
|
|
* ``userFunc`` function to be called when interrupt is triggered.
|
|
* ``arg`` pointer to the interrupt arguments.
|
|
|
|
This function will return ``true`` if configuration is successful and fade start.
|
|
If ``false`` is returned, error occurs and LEDC fade was not configured / started.
|
|
|
|
analogWrite
|
|
***********
|
|
|
|
This function is used to write an analog value (PWM wave) on the pin.
|
|
It is compatible with Arduinos analogWrite function.
|
|
|
|
.. code-block:: arduino
|
|
|
|
void analogWrite(uint8_t pin, int value);
|
|
|
|
* ``pin`` select the GPIO pin.
|
|
* ``value`` select the duty cycle of pwm.
|
|
* range is from 0 (always off) to 255 (always on).
|
|
|
|
analogWriteResolution
|
|
*********************
|
|
|
|
This function is used to set resolution for selected analogWrite pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
void analogWriteResolution(uint8_t pin, uint8_t resolution);
|
|
|
|
* ``pin`` select the GPIO pin.
|
|
* ``resolution`` select resolution for analog channel.
|
|
|
|
analogWriteFrequency
|
|
********************
|
|
|
|
This function is used to set frequency for selected analogWrite pin.
|
|
|
|
.. code-block:: arduino
|
|
|
|
void analogWriteFrequency(uint8_t pin, uint32_t freq);
|
|
|
|
* ``pin`` select the GPIO pin.
|
|
* ``freq`` select frequency of pwm.
|
|
|
|
Example Applications
|
|
********************
|
|
|
|
LEDC fade example:
|
|
|
|
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/LEDCFade/LEDCFade.ino
|
|
:language: arduino
|
|
|
|
LEDC software fade example:
|
|
|
|
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/LEDCSoftwareFade/LEDCSoftwareFade.ino
|
|
:language: arduino
|
|
|
|
LEDC Write RGB example:
|
|
|
|
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/ledcWrite_RGB/ledcWrite_RGB.ino
|
|
:language: arduino
|