docs/en/api/ledc.rst
################## LED Control (LEDC) ##################
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 ========= =======================
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.
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.
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.
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.
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