LED APIs

LED

The LED provides a convenient and thread-safe wrapper around the ESP-IDF LEDC perhipheral.

It allows for both instant and hardware-based timed changing (fading) of duty cycle (in floating point percent [0,100]).

LED Example
- How to use example
  - Hardware Required
  - Build and Flash
- Example Output

API Reference

Header File

components/led/include/led.hpp

Classes

class Led : public espp::BaseComponent 

Provides a wrapper around the LEDC peripheral in ESP-IDF which allows for thread-safe control over one or more channels of LEDs using a simpler API.

Linear LED Example

    float num_seconds_to_run = 10.0f;
    logger.info("Starting linear led example for {:.1f}s!", num_seconds_to_run);
    int led_fade_time_ms = 1000;
    std::vector<espp::Led::ChannelConfig> led_channels{{
        .gpio = 2,
        .channel = LEDC_CHANNEL_5,
        .timer = LEDC_TIMER_2,
    }};
    espp::Led led(espp::Led::Config{
        .timer = LEDC_TIMER_2,
        .frequency_hz = 5000,
        .channels = led_channels,
        .duty_resolution = LEDC_TIMER_10_BIT,
    });
    auto led_channel = led_channels[0].channel;
    auto start = std::chrono::high_resolution_clock::now();
    auto now = std::chrono::high_resolution_clock::now();
    float elapsed = std::chrono::duration<float>(now - start).count();
    while (elapsed < num_seconds_to_run) {
      // if we can change the led, the previous fade is done
      if (led.can_change(led_channel)) {
        auto maybe_duty = led.get_duty(led_channel);
        if (maybe_duty.has_value()) {
          auto current_duty = maybe_duty.value();
          float new_duty = (current_duty < 50.0f) ? 100.0f : 0.0f;
          // start a new fade to the opposite duty cycle
          led.set_fade_with_time(led_channel, new_duty, led_fade_time_ms);
        }
      }
      // sleep for a little bit
      std::this_thread::sleep_for(100ms);
      // update our elapsed time
      now = std::chrono::high_resolution_clock::now();
      elapsed = std::chrono::duration<float>(now - start).count();
    }

Breathing LED Example

    float breathing_period = 3.5f; // seconds
    float num_periods_to_run = 2.0f;
    float num_seconds_to_run = num_periods_to_run * breathing_period;
    logger.info("Starting gaussian led example for {:.1f}s!", num_seconds_to_run);
    std::vector<espp::Led::ChannelConfig> led_channels{{
        .gpio = 2,
        .channel = LEDC_CHANNEL_5,
        .timer = LEDC_TIMER_2,
    }};
    espp::Led led(espp::Led::Config{
        .timer = LEDC_TIMER_2,
        .frequency_hz = 5000,
        .channels = led_channels,
        .duty_resolution = LEDC_TIMER_10_BIT,
        .clock_config = LEDC_USE_RC_FAST_CLK,
    });
    espp::Gaussian gaussian({.gamma = 0.1f, .alpha = 1.0f, .beta = 0.5f});
    auto breathe = [&gaussian, &breathing_period]() -> float {
      static auto breathing_start = std::chrono::high_resolution_clock::now();
      auto now = std::chrono::high_resolution_clock::now();
      auto elapsed = std::chrono::duration<float>(now - breathing_start).count();
      float t = std::fmod(elapsed, breathing_period) / breathing_period;
      return gaussian(t);
    };
    auto led_callback = [&breathe, &led, &led_channels](auto &m, auto &cv) -> bool {
      led.set_duty(led_channels[0].channel, 100.0f * breathe());
      std::unique_lock<std::mutex> lk(m);
      cv.wait_for(lk, 10ms);
      return false;
    };
    auto led_task =
        espp::Task::make_unique({.callback = led_callback, .task_config = {.name = "breathe"}});
    led_task->start();
    logger.debug("Sleeping for {:.1f}s...", num_seconds_to_run);
    std::this_thread::sleep_for(num_seconds_to_run * 1.0s);

Public Functions

explicit Led(const Config &config) noexcept

Initialize the LEDC subsystem according to the configuration.

Parameters:: config – The configuration structure for the LEDC subsystem.

~Led(): Stop the LEDC subsystem and free memory.

bool can_change(ledc_channel_t channel)

Can the LED settings can be changed for the channel? If this function returns true, then (threaded race conditions aside), the set_duty() and set_fade_with_time() functions should not block.

Parameters:: channel – The channel to check
Returns:: True if the channel settings can be changed, false otherwise

std::optional<float> get_duty(ledc_channel_t channel) const

Get the current duty cycle this channel has.

Parameters:: channel – The channel in question
Returns:: The duty percentage [0.0f, 100.0f] if the channel is managed, std::nullopt otherwise

bool set_duty(ledc_channel_t channel, float duty_percent)

Set the duty cycle for this channel.

Note

This function will block until until a current fade process completes (if there is one).

Parameters:

channel – The channel to set the duty cycle for.
duty_percent – The new duty percentage, [0.0, 100.0].

Returns:

True if the duty cycle was set successfully, false otherwise.

std::optional<size_t> get_frequency(ledc_channel_t channel) const

Get the frequency of the LEDC channel.

Parameters:: channel – The channel in question
Returns:: The frequency in Hz if the channel is managed, std::nullopt otherwise

bool set_frequency(ledc_channel_t channel, size_t frequency_hz)

Set the frequency of the LEDC channel.

Note

This function will block until until a current fade process completes (if there is one).

Parameters:

channel – The channel to set the frequency for.
frequency_hz – The new frequency in Hz.

Returns:

True if the frequency was set successfully, false otherwise.

bool set_pwm(ledc_channel_t channel, size_t frequency_hz, float duty_percent)

Set the PWM frequency and duty cycle for this channel.

Note

This function will block until until a current fade process completes (if there is one).

Parameters:

channel – The channel to set the frequency and duty cycle for.
frequency_hz – The new frequency in Hz.
duty_percent – The new duty percentage, [0.0, 100.0].

Returns:

True if the frequency and duty cycle were set successfully, false otherwise.

bool set_fade_with_time(ledc_channel_t channel, float duty_percent, uint32_t fade_time_ms)

Set the duty cycle for this channel, fading from the current duty cycle to the new duty cycle over fade_time_ms milliseconds.

Note

This function will block until until a current fade process completes (if there is one).

Parameters:

channel – The channel to fade.
duty_percent – The new duty percentage to fade to, [0.0, 100.0].
fade_time_ms – The number of milliseconds for which to fade.

Returns:

True if the fade was set successfully, false otherwise.

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:: rate_limit – The rate limit to use for the logger

Public Static Functions

static void uninstall_isr(): Uninstall the fade service. This should be called if you want to stop the fade service and free up the ISR.

Note

This function should only be called if you are sure that no other Led objects are using the fade service.

struct ChannelConfig

Represents one LED channel.

Public Members

size_t gpio: The GPIO pin the LED is connected to.

ledc_channel_t channel: The LEDC channel that you want associated with this LED.

ledc_timer_t timer: The LEDC timer that you want associated with this LED channel.

float duty{0}: The starting duty cycle (%) [0, 100] that you want the LED channel to have.

ledc_mode_t speed_mode{LEDC_LOW_SPEED_MODE}: The LEDC speed mode you want for this LED channel.

bool output_invert = {false}: Whether to invert the GPIO output for this LED channel.

ledc_sleep_mode_t sleep_mode{LEDC_SLEEP_MODE_KEEP_ALIVE}: The LEDC sleep mode you want for this LED channel. Default is LEDC_SLEEP_MODE_KEEP_ALIVE which will keep the LEDC output when the system enters light sleep. Note that this is only useful if the LED’s clock_config is set to a clock source which supports light sleep.

struct Config

Configuration Struct for the LEDC subsystem including the different LED channels that should be associated.

Public Members

int isr_core_id = -1: The core to install the LEDC fade function (interrupt) on. If -1, then the LEDC interrupt is installed on the core that this constructor is called on. If 0 or 1, then the LEDC interrupt is installed on the specified core.

ledc_timer_t timer: The LEDC timer that you want associated with the LEDs.

size_t frequency_hz: The frequency that you want to run the PWM hardawre for the LEDs at.

Note

this is inversely related to the duty resolution configuration.

std::vector<ChannelConfig> channels: The LED channels that you want to control.

ledc_timer_bit_t duty_resolution{LEDC_TIMER_13_BIT}: The resolution of the duty cycle for these LEDs.

Note

this is inversely related to the frequency configuration.

ledc_clk_cfg_t clock_config{LEDC_AUTO_CLK}: The LEDC clock configuration you want for these LED channels.

ledc_mode_t speed_mode{LEDC_LOW_SPEED_MODE}: The LEDC speed mode you want for these LED channels.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}: Log verbosity for the task.