feat(neopixel): Add simple neopixel class wrapping RMT led encoding (#374)

* feat(neopixel): Add simple neopixel class wrapping RMT led encoding

* update code format

* update readme

Author: finger563

.github/workflows/build.yml

@@ -107,6 +107,8 @@ jobs:
           target: esp32s3
         - path: 'components/mt6701/example'
           target: esp32s3
+        - path: 'components/neopixel/example'
+          target: esp32s3
         - path: 'components/nvs/example'
           target: esp32s3
         - path: 'components/pid/example'

components/led_strip/example/CMakeLists.txt

@@ -16,6 +16,6 @@ set(
   "List of components to include"
   )
 
-project(apa102_example)
+project(led_strip_example)
 
 set(CMAKE_CXX_STANDARD 20)

components/led_strip/include/led_strip.hpp

@@ -139,7 +139,7 @@ class LedStrip : public BaseComponent {
   /// \note The index is zero-based.
   /// \sa Hsv for more information on the HSV color space
   /// \sa show
-  void set_pixel(int index, Hsv hsv, float brightness = 1.0f) {
+  void set_pixel(int index, const Hsv &hsv, float brightness = 1.0f) {
     set_pixel(index, hsv.rgb(), brightness);
   }
 
@@ -150,7 +150,7 @@ class LedStrip : public BaseComponent {
   /// \note The index is zero-based.
   /// \sa Rgb for more information on the RGB color space
   /// \sa show
-  void set_pixel(int index, Rgb rgb, float brightness = 1.0f) {
+  void set_pixel(int index, const Rgb &rgb, float brightness = 1.0f) {
     uint8_t brightness_byte = std::clamp<uint8_t>(brightness * 31.0f, 0, 31);
     uint8_t r, g, b;
     r = std::clamp<uint8_t>(rgb.r * 255.0f, 0, 255);
@@ -209,14 +209,14 @@ class LedStrip : public BaseComponent {
   /// \note The index is zero-based.
   /// \sa set_pixel
   /// \sa show
-  void set_all(Hsv hsv, float brightness = 1.0f) { set_all(hsv.rgb(), brightness); }
+  void set_all(const Hsv &hsv, float brightness = 1.0f) { set_all(hsv.rgb(), brightness); }
 
   /// \brief Set the color of all the LEDs
   /// \param rgb Color to set the LEDs to
   /// \param brightness Brightness of the LEDs
   /// \sa set_pixel
   /// \sa show
-  void set_all(Rgb rgb, float brightness = 1.0f) {
+  void set_all(const Rgb &rgb, float brightness = 1.0f) {
     uint8_t brightness_byte = std::clamp<uint8_t>(brightness * 255.0f, 0, 255);
     set_all(rgb.r, rgb.g, rgb.b, brightness_byte);
   }

components/neopixel/CMakeLists.txt

@@ -0,0 +1,5 @@
+idf_component_register(
+  INCLUDE_DIRS "include"
+  SRC_DIRS "src"
+  REQUIRES base_component color rmt
+  )

components/neopixel/example/CMakeLists.txt

@@ -0,0 +1,21 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# add the component directories that we want to use
+set(EXTRA_COMPONENT_DIRS
+  "../../../components/"
+)
+
+set(
+  COMPONENTS
+  "main esptool_py logger task neopixel"
+  CACHE STRING
+  "List of components to include"
+  )
+
+project(neopixel_example)
+
+set(CMAKE_CXX_STANDARD 20)

components/neopixel/example/README.md

@@ -0,0 +1,32 @@
+# Neopixel Example 
+
+This example shows the use of the `Neopixel` class to control a an RGB
+LED (WS2812).
+
+## How to use example
+
+### Hardware Required
+
+This example is designed to be run on a [QtPy
+ESP32-S3](https://www.adafruit.com/product/5426). It uses the QtPy's on-board
+neopixel.
+
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+![CleanShot 2025-02-18 at 14 45 15](https://github.com/user-attachments/assets/6c0661b7-26c2-40c9-9b66-f8f528d22d7f)
+

components/neopixel/example/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRC_DIRS "."
+                       INCLUDE_DIRS ".")

components/neopixel/example/main/neopixel_example.cpp

@@ -0,0 +1,84 @@
+#include <chrono>
+#include <vector>
+
+#include "neopixel.hpp"
+#include "task.hpp"
+
+using namespace std::chrono_literals;
+
+extern "C" void app_main(void) {
+  // create a logger
+  espp::Logger logger({.tag = "Neopixel example", .level = espp::Logger::Verbosity::INFO});
+  {
+    logger.info("starting example");
+
+    //! [neopixel ex1]
+    espp::Neopixel led({
+        .data_gpio = 39,  // Neopixel data pin on QtPy ESP32s3
+        .power_gpio = 38, // Neopixel power pin on QtPy ESP32s3
+    });
+
+    logger.info("Turning LED off for 1 second");
+    led.set_color(espp::Rgb(0.0f, 0.0f, 0.0f));
+    led.show();
+    std::this_thread::sleep_for(1s);
+
+    logger.info("Setting LED to red for 1 second");
+    led.set_color(espp::Rgb(1.0f, 0.0f, 0.0f));
+    led.show();
+    std::this_thread::sleep_for(1s);
+
+    logger.info("Setting LED to green for 1 second");
+    led.set_color(espp::Rgb(0.0f, 1.0f, 0.0f));
+    led.show();
+    std::this_thread::sleep_for(1s);
+
+    logger.info("Setting LED to blue for 1 second");
+    led.set_color(espp::Rgb(0.0f, 0.0f, 1.0f));
+    led.show();
+    std::this_thread::sleep_for(1s);
+
+    // Use a task to rotate the LED through the rainbow using HSV
+    auto task_fn = [&led](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();
+      // 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.set_color(hsv);
+      // show the new colors
+      led.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;
+    };
+
+    logger.info("Starting task to rotate LED through rainbow colors");
+    auto task = espp::Task({.callback = task_fn,
+                            .task_config =
+                                {
+                                    .name = "Neopixel Task",
+                                    .stack_size_bytes = 5 * 1024,
+                                },
+                            .log_level = espp::Logger::Verbosity::WARN});
+    task.start();
+    //! [neopixel ex1]
+
+    while (true) {
+      std::this_thread::sleep_for(100ms);
+    }
+  }
+
+  logger.info("example complete!");
+
+  while (true) {
+    std::this_thread::sleep_for(1s);
+  }
+}

components/neopixel/example/sdkconfig.defaults

@@ -0,0 +1,16 @@
+CONFIG_IDF_TARGET="esp32s3"
+
+CONFIG_FREERTOS_HZ=1000
+
+# ESP32-specific
+#
+CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
+CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ=240
+
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+CONFIG_ESPTOOLPY_FLASHSIZE="4MB"
+
+# Common ESP-related
+#
+CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192

components/neopixel/include/neopixel.hpp

@@ -0,0 +1,81 @@
+#pragma once
+
+#include <mutex>
+
+#include <driver/gpio.h>
+
+#include "base_component.hpp"
+#include "color.hpp"
+#include "logger.hpp"
+#include "rmt.hpp"
+
+namespace espp {
+/// \brief A class for controlling a Neopixel strip.
+/// \details This class provides a simple interface for controlling a Neopixel
+/// strip. It uses the RMT peripheral to send the data to the strip.
+///
+/// \section neopixel_ex1 Example 1: QtPy ESP32S3 Neopixel
+/// \snippet neopixel_example.cpp neopixel ex1
+class Neopixel {
+public:
+  /// The configuration structure for the Neopixel.
+  struct Config {
+    int data_gpio;      ///< The GPIO pin for the data line
+    int power_gpio{-1}; ///< The GPIO pin for the power line (optional)
+    size_t num_leds{1}; ///< The number of LEDs in the strip
+    espp::Logger::Verbosity log_level{
+        espp::Logger::Verbosity::WARN}; ///< Verbosity for the neopixel logger
+  };
+
+  /// Constructor for the Neopixel.
+  /// \param config The configuration structure for the Neopixel.
+  explicit Neopixel(const espp::Neopixel::Config &config);
+
+  /// Get the number of LEDs in the strip.
+  /// \return The number of LEDs in the strip.
+  std::size_t num_leds() const { return config_.num_leds; }
+
+  /// Set the color of a single pixel.
+  /// \param rgb The color to set the pixel to.
+  /// \param index The index of the pixel to set.
+  void set_color(const espp::Rgb &rgb, std::size_t index = 0);
+
+  /// Set the color of a single pixel.
+  /// \param hsv The color to set the pixel to.
+  /// \param index The index of the pixel to set.
+  void set_color(const espp::Hsv &hsv, std::size_t index = 0) { set_color(hsv.rgb(), index); }
+
+  /// Set the color of all pixels.
+  /// \param rgb The color to set all pixels to.
+  void set_all(const espp::Rgb &rgb);
+
+  /// Set the color of all pixels.
+  /// \param hsv The color to set all pixels to.
+  void set_all(const espp::Hsv &hsv) { set_all(hsv.rgb()); }
+
+  /// Show the current pixel data.
+  void show();
+
+  /// Set the power state of the strip.
+  /// \param on The power state to set.
+  /// \details If the power GPIO is set, this function will set the power
+  ///          state of the strip. If the power GPIO is not set, this function
+  ///          will do nothing.
+  void set_power(bool on);
+
+protected:
+  static constexpr int WS2812_FREQ_HZ = 10'000'000;
+  static constexpr int MICROS_PER_SEC = 1'000'000;
+
+  std::size_t encode(rmt_channel_handle_t channel, rmt_encoder_t *copy_encoder,
+                     rmt_encoder_t *bytes_encoder, const void *data, std::size_t data_size,
+                     rmt_encode_state_t *ret_state);
+
+  void configure_power_pin();
+
+  Config config_;
+  std::shared_ptr<espp::Rmt> rmt_;
+  int led_encoder_state_{0};
+  std::vector<uint8_t> led_data_;
+}; // class Neopixel
+} // namespace espp