LED Strip APIs

The LedStrip component provides APIs to control LED strips. It supports various LED strip types, such as WS2812, WS2811, WS2813, SK6812, APA102, etc. You can use it directly with an SPI driver to talk to APA102 LED strips, or you can use it with a RMT driver (such as the Rmt component) to talk to WS2812, WS2811, WS2813, SK6812, etc. LED strips.

API Reference

Header File

Classes

class LedStrip : public espp::BaseComponent

Class to control LED strips.

This class is used to control LED strips. It is designed to be used with a write function that can be used to write data to the strip. This allows it to be used with different hardware interfaces (e.g. SPI, I2C, RMT, etc.).

This class is designed to be used to control various LED strips, which may be using different protocols. The following protocols are supported:

  • APA102 (via SPI)

  • WS2812 (via the RMT peripheral)

Example 1: APA102 via SPI

    // create the rmt object
    espp::Rmt rmt(espp::Rmt::Config{
        .gpio_num = NEO_BFF_IO,
        .resolution_hz = SK6805_FREQ_HZ,
        .log_level = espp::Logger::Verbosity::INFO,
    });

    // tell the RMT object to use the led_encoder (espp::RmtEncoder) that's
    // defined above
    rmt.set_encoder(std::move(led_encoder));

    // create the write function we'll use
    auto neopixel_write = [&rmt](const uint8_t *data, size_t len) {
      if (len == 0) {
        return;
      }
      // send the data to the RMT object
      rmt.transmit(data, len);
    };

    // now create the LedStrip object
    espp::LedStrip led_strip(espp::LedStrip::Config{
        .num_leds = NEO_BFF_NUM_LEDS,
        .write = neopixel_write,
        .send_brightness = false,
        .byte_order = espp::LedStrip::ByteOrder::GRB,
        .start_frame = {},
        .end_frame = {},
        .log_level = espp::Logger::Verbosity::INFO,
    });

    // Set all pixels
    led_strip.set_all(espp::Rgb(0, 0, 0));
    // And show it
    led_strip.show();

    std::this_thread::sleep_for(1s);

    // Use a task to rotate the LED through the rainbow using HSV
    auto task_fn = [&led_strip](std::mutex &m, std::condition_variable &cv) {
      static auto start = std::chrono::high_resolution_clock::now();
      auto now = std::chrono::high_resolution_clock::now();
      float t = std::chrono::duration<float>(now - start).count();
      // shift the LEDs right one
      led_strip.shift_right();
      // rotate through rainbow colors in hsv based on time, hue is 0-360
      float hue = (cos(t) * 0.5f + 0.5f) * 360.0f;
      espp::Hsv hsv(hue, 1.0f, 1.0f);
      // full brightness (1.0, default) is _really_ bright, so tone it down
      led_strip.set_pixel(0, hsv, 0.05f);
      // show the new colors
      led_strip.show();
      // NOTE: sleeping in this way allows the sleep to exit early when the
      // task is being stopped / destroyed
      {
        std::unique_lock<std::mutex> lk(m);
        cv.wait_for(lk, 50ms);
      }
      // don't want to stop the task
      return false;
    };

    auto task = espp::Task({.callback = task_fn,
                            .task_config =
                                {
                                    .name = "LedStrip Task",
                                    .stack_size_bytes = 5 * 1024,
                                },
                            .log_level = espp::Logger::Verbosity::WARN});
    task.start();

Note

This class does not handle the clock signal (if any) for the strip. It is assumed that the clock signal is handled by the hardware interface.

Note

This class does not handle the chip select signal (if any) for the strip. It is assumed that the chip select signal is handled by the hardware interface.

Note

This class does not handle the power signal (if any) for the strip.

Public Types

enum class ByteOrder

Byte order for the LEDs.

Values:

enumerator RGB

RGB byte order.

enumerator GRB

GRB byte order.

enumerator BGR

BGR byte order.

typedef std::function<void(const uint8_t *data, size_t length)> write_fn

Function to write data to the strip.

This function is used to write data to the strip. It is assumed that the function will block until the data has been written.

Note

The data is not guaranteed to be valid after the function returns.

Note

The length of the data is guaranteed to be at least 4 bytes.

Note

The data is guaranteed to be 4-byte aligned.

Note

The data is guaranteed to be in the order of the bytes in the strip (i.e. the first byte in the data is the first byte in the strip).

Param data:

Pointer to the data to write

Param length:

Length of the data to write

Public Functions

inline explicit LedStrip(const Config &config)

Constructor.

Parameters:

config – Configuration for the LedStrip class

inline size_t num_leds() const

Get the number of LEDs in the strip.

Returns:

Number of LEDs in the strip

inline ByteOrder byte_order() const

Get the byte order for the LEDs.

Returns:

Byte order for the LEDs

inline void shift_left(int shift_by = 1)

Shift the LEDs to the left.

Note

A negative value for shift_by will shift the LEDs to the right

Parameters:

shift_by – Number of LEDs to shift by

inline void shift_right(int shift_by = 1)

Shift the LEDs to the right.

Note

A negative value for shift_by will shift the LEDs to the left

Parameters:

shift_by – Number of LEDs to shift by

inline void set_pixel(int index, const Hsv &hsv, float brightness = 1.0f)

Set the color of a single LED.

See also

Hsv for more information on the HSV color space

See also

show

Note

The index is zero-based.

Parameters:

  • index – Index of the LED to set

  • hsv – Color to set the LED to

  • brightness – Brightness of the LED

inline void set_pixel(int index, const Rgb &rgb, float brightness = 1.0f)

Set the color of a single LED.

See also

Rgb for more information on the RGB color space

See also

show

Note

The index is zero-based.

Parameters:

  • index – Index of the LED to set

  • rgb – Color to set the LED to

  • brightness – Brightness of the LED

inline void set_pixel(int index, uint8_t r, uint8_t g, uint8_t b, uint8_t brightness = 0b11111)

Set the color of a single LED.

See also

show

Note

The index is zero-based.

Parameters:

  • index – Index of the LED to set

  • r – Red component of the color to set the LED to [0-255]

  • g – Green component of the color to set the LED to [0-255]

  • b – Blue component of the color to set the LED to [0-255]

  • brightness – Brightness of the LED [0-31]

inline void set_all(const Hsv &hsv, float brightness = 1.0f)

Set the color of all the LEDs.

See also

set_pixel

See also

show

Note

The index is zero-based.

Parameters:

  • hsv – Color to set the LEDs to

  • brightness – Brightness of the LEDs

inline void set_all(const Rgb &rgb, float brightness = 1.0f)

Set the color of all the LEDs.

See also

set_pixel

See also

show

Parameters:

  • rgb – Color to set the LEDs to

  • brightness – Brightness of the LEDs

inline void set_all(uint8_t r, uint8_t g, uint8_t b, uint8_t brightness = 0xff)

Set the color of all the LEDs.

See also

set_pixel

See also

show

Parameters:

  • r – Red component of the color to set the LEDs to

  • g – Green component of the color to set the LEDs to

  • b – Blue component of the color to set the LEDs to

  • brightness – Brightness of the LEDs

inline void show()

Show the colors on the strip.

This function writes the colors to the strip. It should be called after setting the colors of the LEDs.

See also

set_pixel

See also

set_all

Note

This function blocks until the colors have been written to the strip.

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 Attributes

static const std::vector<uint8_t> APA102_START_FRAME

Start frame for the APA102 protocol.

struct Config

Configuration for the LedStrip class.

Public Members

size_t num_leds

Number of LEDs in the strip.

write_fn write

Function to write data to the strip.

bool send_brightness = {true}

Whether to use the brightness value for the LEDs.

ByteOrder byte_order = {ByteOrder::RGB}

Byte order for the LEDs.

std::vector<uint8_t> start_frame = {}

Start frame for the strip. Optional - will be sent before the first LED if not empty.

std::vector<uint8_t> end_frame = {}

End frame for the strip. Optional - will be sent after the last LED if not empty.

Logger::Verbosity log_level

Log level for this class.