LED Control¶
Overview¶
The LED control module is primarily designed to control the intensity of LEDs, although it can be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used to drive e.g. RGB LED devices. For maximum flexibility, the high-speed as well as the low-speed channels can be driven from one of four high-speed/low-speed timers. The PWM controller also has the ability to automatically increase or decrease the duty cycle gradually, allowing for fades without any processor interference.
Application Example¶
LEDC change duty cycle and fading control example: peripherals/ledc.
API Reference¶
Header File¶
Functions¶
-
esp_err_t
ledc_channel_config
(const ledc_channel_config_t *ledc_conf)¶ LEDC channel configuration Configure LEDC channel with the given channel/output gpio_num/interrupt/source timer/frequency(Hz)/LEDC depth.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
ledc_conf
: Pointer of LEDC channel configure struct
-
esp_err_t
ledc_timer_config
(const ledc_timer_config_t *timer_conf)¶ LEDC timer configuration Configure LEDC timer with the given source timer/frequency(Hz)/bit_num.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current bit_num.
- Parameters
timer_conf
: Pointer of LEDC timer configure struct
-
esp_err_t
ledc_update_duty
(ledc_mode_t speed_mode, ledc_channel_t channel)¶ LEDC update channel parameters Call this function to activate the LEDC updated parameters. After ledc_set_duty, ledc_set_fade, we need to call this function to update the settings.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed mode,channel
: LEDC channel(0-7), select from ledc_channel_t
-
esp_err_t
ledc_stop
(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t idle_level)¶ LEDC stop. Disable LEDC output, and set idle level.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modechannel
: LEDC channel(0-7), select from ledc_channel_tidle_level
: Set output idle level after LEDC stops.
-
esp_err_t
ledc_set_freq
(ledc_mode_t speed_mode, ledc_timer_t timer_num, uint32_t freq_hz)¶ LEDC set channel frequency(Hz)
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current bit_num.
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modetimer_num
: LEDC timer index(0-3), select from ledc_timer_tfreq_hz
: Set the LEDC frequency
-
uint32_t
ledc_get_freq
(ledc_mode_t speed_mode, ledc_timer_t timer_num)¶ LEDC get channel frequency(Hz)
- Return
- 0 error
- Others Current LEDC frequency
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modetimer_num
: LEDC timer index(0-3), select from ledc_timer_t
-
esp_err_t
ledc_set_duty
(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty)¶ LEDC set duty Only after calling ledc_update_duty will the duty update.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modechannel
: LEDC channel(0-7), select from ledc_channel_tduty
: Set the LEDC duty, the duty range is [0, (2**bit_num) - 1]
-
int
ledc_get_duty
(ledc_mode_t speed_mode, ledc_channel_t channel)¶ LEDC get duty.
- Return
- (-1) parameter error
- Others Current LEDC duty
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modechannel
: LEDC channel(0-7), select from ledc_channel_t
-
esp_err_t
ledc_set_fade
(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty, ledc_duty_direction_t gradule_direction, uint32_t step_num, uint32_t duty_cyle_num, uint32_t duty_scale)¶ LEDC set gradient Set LEDC gradient, After the function calls the ledc_update_duty function, the function can take effect.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modechannel
: LEDC channel(0-7), select from ledc_channel_tduty
: Set the start of the gradient duty, the duty range is [0, (2**bit_num) - 1]gradule_direction
: Set the direction of the gradientstep_num
: Set the number of the gradientduty_cyle_num
: Set how many LEDC tick each time the gradient lastsduty_scale
: Set gradient change amplitude
-
esp_err_t
ledc_isr_register
(void (*fn)(void *), void *arg, int intr_alloc_flags, ledc_isr_handle_t *handle, )¶ Register LEDC interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Function pointer error.
- Parameters
fn
: Interrupt handler function.arg
: User-supplied argument passed to the handler function.intr_alloc_flags
: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.arg
: Parameter for handler functionhandle
: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
-
esp_err_t
ledc_timer_set
(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t div_num, uint32_t bit_num, ledc_clk_src_t clk_src)¶ Configure LEDC settings.
- Return
- (-1) Parameter error
- Other Current LEDC duty
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modetimer_sel
: Timer index(0-3), there are 4 timers in LEDC modulediv_num
: Timer clock divide number, the timer clock is divided from the selected clock sourcebit_num
: The count number of one period, counter range is 0 ~ ((2 ** bit_num) - 1)clk_src
: Select LEDC source clock.
-
esp_err_t
ledc_timer_rst
(ledc_mode_t speed_mode, uint32_t timer_sel)¶ Reset LEDC timer.
- Return
- ESP_ERR_INVALID_ARG Parameter error
- ESP_OK Success
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modetimer_sel
: LEDC timer index(0-3), select from ledc_timer_t
-
esp_err_t
ledc_timer_pause
(ledc_mode_t speed_mode, uint32_t timer_sel)¶ Pause LEDC timer counter.
- Return
- ESP_ERR_INVALID_ARG Parameter error
- ESP_OK Success
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modetimer_sel
: LEDC timer index(0-3), select from ledc_timer_t
-
esp_err_t
ledc_timer_resume
(ledc_mode_t speed_mode, uint32_t timer_sel)¶ Resume LEDC timer.
- Return
- ESP_ERR_INVALID_ARG Parameter error
- ESP_OK Success
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modetimer_sel
: LEDC timer index(0-3), select from ledc_timer_t
-
esp_err_t
ledc_bind_channel_timer
(ledc_mode_t speed_mode, uint32_t channel, uint32_t timer_idx)¶ Bind LEDC channel with the selected timer.
- Return
- ESP_ERR_INVALID_ARG Parameter error
- ESP_OK Success
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modechannel
: LEDC channel index(0-7), select from ledc_channel_ttimer_idx
: LEDC timer index(0-3), select from ledc_timer_t
-
esp_err_t
ledc_set_fade_with_step
(ledc_mode_t speed_mode, ledc_channel_t channel, int target_duty, int scale, int cycle_num)¶ Set LEDC fade function. Should call ledc_fade_func_install() before calling this function. Call ledc_fade_start() after this to start fading.
- Return
- ESP_ERR_INVALID_ARG Parameter error
- ESP_OK Success
- ESP_ERR_INVALID_STATE Fade function not installed.
- ESP_FAIL Fade function init error
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed mode,channel
: LEDC channel index(0-7), select from ledc_channel_ttarget_duty
: Target duty of fading.( 0 - (2 ** bit_num - 1)))scale
: Controls the increase or decrease step scale.cycle_num
: increase or decrease the duty every cycle_num cycles
-
esp_err_t
ledc_set_fade_with_time
(ledc_mode_t speed_mode, ledc_channel_t channel, int target_duty, int max_fade_time_ms)¶ Set LEDC fade function, with a limited time. Should call ledc_fade_func_install() before calling this function. Call ledc_fade_start() after this to start fading.
- Return
- ESP_ERR_INVALID_ARG Parameter error
- ESP_OK Success
- ESP_ERR_INVALID_STATE Fade function not installed.
- ESP_FAIL Fade function init error
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed mode,channel
: LEDC channel index(0-7), select from ledc_channel_ttarget_duty
: Target duty of fading.( 0 - (2 ** bit_num - 1)))max_fade_time_ms
: The maximum time of the fading ( ms ).
-
esp_err_t
ledc_fade_func_install
(int intr_alloc_flags)¶ Install ledc fade function. This function will occupy interrupt of LEDC module.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_STATE Fade function already installed.
- Parameters
intr_alloc_flags
: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
-
void
ledc_fade_func_uninstall
()¶ Uninstall LEDC fade function.
-
esp_err_t
ledc_fade_start
(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_fade_mode_t wait_done)¶ Start LEDC fading.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_STATE Fade function not installed.
- ESP_ERR_INVALID_ARG Parameter error.
- Parameters
speed_mode
: Select the LEDC speed_mode, high-speed mode and low-speed modechannel
: LEDC channel numberwait_done
: Whether to block until fading done.
Structures¶
-
struct
ledc_channel_config_t
¶ Configuration parameters of LEDC channel for ledc_channel_config function.
Public Members
-
int
gpio_num
¶ the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16
-
ledc_mode_t
speed_mode
¶ LEDC speed speed_mode, high-speed mode or low-speed mode
-
ledc_channel_t
channel
¶ LEDC channel(0 - 7)
-
ledc_intr_type_t
intr_type
¶ configure interrupt, Fade interrupt enable or Fade interrupt disable
-
ledc_timer_t
timer_sel
¶ Select the timer source of channel (0 - 3)
-
uint32_t
duty
¶ LEDC channel duty, the duty range is [0, (2**bit_num) - 1],
-
int
-
struct
ledc_timer_config_t
¶ Configuration parameters of LEDC Timer timer for ledc_timer_config function.
Public Members
-
ledc_mode_t
speed_mode
¶ LEDC speed speed_mode, high-speed mode or low-speed mode
-
ledc_timer_bit_t
bit_num
¶ LEDC channel duty depth
-
ledc_timer_t
timer_num
¶ The timer source of channel (0 - 3)
-
uint32_t
freq_hz
¶ LEDC timer frequency(Hz)
-
ledc_mode_t
Type Definitions¶
-
typedef intr_handle_t
ledc_isr_handle_t
¶
Enumerations¶
-
enum
ledc_mode_t
¶ Values:
-
LEDC_HIGH_SPEED_MODE
= 0¶ LEDC high speed speed_mode
-
LEDC_LOW_SPEED_MODE
¶ LEDC low speed speed_mode
-
LEDC_SPEED_MODE_MAX
¶ LEDC speed limit
-
-
enum
ledc_intr_type_t
¶ Values:
-
LEDC_INTR_DISABLE
= 0¶ Disable LEDC interrupt
-
LEDC_INTR_FADE_END
¶ Enable LEDC interrupt
-
-
enum
ledc_duty_direction_t
¶ Values:
-
LEDC_DUTY_DIR_DECREASE
= 0¶ LEDC duty decrease direction
-
LEDC_DUTY_DIR_INCREASE
= 1¶ LEDC duty increase direction
-
-
enum
ledc_clk_src_t
¶ Values:
-
LEDC_REF_TICK
= 0¶ LEDC timer clock divided from reference tick(1Mhz)
-
LEDC_APB_CLK
¶ LEDC timer clock divided from APB clock(80Mhz)
-
-
enum
ledc_timer_t
¶ Values:
-
LEDC_TIMER_0
= 0¶ LEDC source timer TIMER0
-
LEDC_TIMER_1
¶ LEDC source timer TIMER1
-
LEDC_TIMER_2
¶ LEDC source timer TIMER2
-
LEDC_TIMER_3
¶ LEDC source timer TIMER3
-
-
enum
ledc_channel_t
¶ Values:
-
LEDC_CHANNEL_0
= 0¶ LEDC channel 0
-
LEDC_CHANNEL_1
¶ LEDC channel 1
-
LEDC_CHANNEL_2
¶ LEDC channel 2
-
LEDC_CHANNEL_3
¶ LEDC channel 3
-
LEDC_CHANNEL_4
¶ LEDC channel 4
-
LEDC_CHANNEL_5
¶ LEDC channel 5
-
LEDC_CHANNEL_6
¶ LEDC channel 6
-
LEDC_CHANNEL_7
¶ LEDC channel 7
-
LEDC_CHANNEL_MAX
¶
-
-
enum
ledc_timer_bit_t
¶ Values:
-
LEDC_TIMER_10_BIT
= 10¶ LEDC PWM depth 10Bit
-
LEDC_TIMER_11_BIT
= 11¶ LEDC PWM depth 11Bit
-
LEDC_TIMER_12_BIT
= 12¶ LEDC PWM depth 12Bit
-
LEDC_TIMER_13_BIT
= 13¶ LEDC PWM depth 13Bit
-
LEDC_TIMER_14_BIT
= 14¶ LEDC PWM depth 14Bit
-
LEDC_TIMER_15_BIT
= 15¶ LEDC PWM depth 15Bit
-