ESP32 LEDC Output

The LEDC output component exposes a LEDC PWMchannel of the ESP32 as an output component.

The frequency range of LEDC is from 10Hz to 40MHz - however, higher frequencies require a smaller bit depth which means the output is not that accurate for frequencies above ~300kHz.

Configuration variables

pin (Required, Pin): Must be an output pin.
id (Required, ID): The id to use for this output component.
frequency (Optional, frequency): At which frequency to run the LEDC channel’s timer. Defaults to 1kHz.
All other options from Output.

Advanced options:

phase_angle (Optional, float): Set a phase angle to the other channel of this timer. Range 0-360°, defaults to 0°
channel (Optional, int): Manually set the LEDC channel to use. Defaults to an automatic selection. The valid channel range depends on the ESP32 variant:

ESP32 variant	Valid channels
ESP32	`0`-`15`
ESP32-S2, ESP32-S3, ESP32-P4	`0`-`7`
ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2	`0`-`5`

NOTE

Two adjacent channels share the same hardware timer. They can still use different duty cycles (light output can differ) and use different phases, but not different PWM frequencies. If you need light channels to use different frequencies, manually assign them to unused LEDC outputs, and avoid selecting adjacent channel pairs, such as 0/1, 2/3 and so on.

Example Usage For a Light

# Example configuration entry
output:
  - platform: ledc
    pin: GPIOXX
    id: gpio_

# Example usage in a light
light:
  - platform: monochromatic
    output: gpio_19
    name: "Kitchen Light"

Example Usage For a Piezo Buzzer

# Configure the output
output:
  - platform: ledc
    ######################################################
    # One buzzer leg connected to GPIO12, the other to GND
    ######################################################
    pin: GPIO12
    id: buzzer

# Example usage in an automation
on_press:
    then:
    ######################################################
    # Must be turned on before setting frequency & level
    ######################################################
    - output.turn_on: buzzer
    ######################################################
    # Frequency sets the wave size
    ######################################################
    - output.ledc.set_frequency:
        id: buzzer
        frequency: "1kHz"
    ######################################################
    # level sets the %age time the PWM is on
    ######################################################
    - output.set_level:
        id: buzzer
        level: "50%"

Recommended frequencies

To get the highest available frequency while still getting the same bit depth it is recommended to pick one of the following frequencies.

Higher bit depth means that the light has more steps available to change from one value to another. This is especially noticeable when the light is below 10% and takes a long transition, e.g. turning slowly off.

Frequency	Bit depth	Available steps for transitions
1220Hz	16 / 14*	65536 / 16384*
2441Hz	15 / 14*	32768 / 16384*
4882Hz	14	16384
9765Hz	13	8192
19531Hz	12	4096

* ESP32-S2, ESP32-S3, ESP32-C2, and ESP32-C3 support only 14-bit LEDC timers. The original ESP32, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, and ESP32-P4 support 20-bit LEDC timers, which results in up to 16-bit resolution in the useful LED PWM range as shown above.

The ESP8266 for instance has usually a frequency of 1000Hz with a resolution of 10 bits. This means that there are only 4 steps between each value.

`output.ledc.set_frequency` Action

This Action allows you to manually change the frequency of an LEDC channel at runtime. Use cases include controlling a passive buzzer (for pitch control).

on_...:
  - output.ledc.set_frequency:
      id: ledc_output
      frequency: 100Hz

Configuration variables:

id (Required, ID): The ID of the LEDC output to change.
frequency (Required, templatable, frequency): The frequency to set in Hz.