HF-WS2812 Driver

ESP32 RMT-based driver for WS2812 / NeoPixel addressable RGB(W) LED strips

📚 Table of Contents

1. Overview
2. Features
3. Quick Start
4. Installation
5. API Reference
6. Examples
7. Documentation
8. Contributing
9. License

📦 Overview

📖 📚🌐 Live Complete Documentation - Interactive guides, examples, and step-by-step tutorials

HF-WS2812 is an ESP32-specific driver for WS2812 and compatible addressable RGB(W) LED strips (commonly known as NeoPixels). The driver uses the ESP32’s RMT (Remote Control) peripheral to generate the precise timing signals required by WS2812 LEDs, providing hardware-accelerated LED control with minimal CPU overhead.

The driver supports both C and C++ APIs, includes built-in animation effects, and is fully configurable via ESP-IDF’s Kconfig system. It’s compatible with WS2812, WS2812B, WS2813, SK6812, and other WS2812-compatible LED variants.

✨ Features

• ✅ Hardware-Accelerated: Uses ESP32 RMT peripheral for precise timing
• ✅ Dual API: Both C and C++ interfaces available
• ✅ Animation Effects: Built-in effects library (rainbow, chase, fade, etc.)
• ✅ RGB and RGBW Support: 24-bit RGB and 32-bit RGBW LED types
• ✅ Configurable Timing: Adjustable timing parameters for different LED variants
• ✅ Brightness Control: Global brightness scaling (0-255)
• ✅ Kconfig Integration: Full ESP-IDF Kconfig configuration support
• ✅ Zero CPU Overhead: RMT handles signal generation automatically

🚀 Quick Start

#include "ws2812_cpp.hpp"
#include "ws2812_effects.hpp"

// Create strip: GPIO, RMT channel, LED count, LED type
WS2812Strip strip(GPIO_NUM_18, 0, 30, LedType::RGB);
WS2812Animator anim(strip);

void app_main(void) {
    strip.begin();
    anim.setEffect(WS2812Animator::Effect::Rainbow);
    
    while (true) {
        anim.tick();
        vTaskDelay(pdMS_TO_TICKS(50));
    }
}

For detailed setup, see Installation and Quick Start Guide.

🔧 Installation

1. Add as ESP-IDF component to your project
2. Configure via Kconfig: Run idf.py menuconfig → Component Config → HF-ESP32-WS2812-RMT
3. Include the header in your code:

   #include "ws2812_cpp.hpp"  // C++ API
   // or
   #include "ws2812_control.h"  // C API
   

For detailed installation instructions, see docs/installation.md.

📖 API Reference

Method	Description
begin()	Initialize the LED strip
setPixel()	Set color of a single LED
show()	Send colors to LED strip
setBrightness()	Set global brightness
setEffect()	Set animation effect

For complete API documentation, see docs/api_reference.md.

📊 Examples

For ESP32 examples, see the examples/esp32 directory.

Detailed example walkthroughs are available in docs/examples.md.

📚 Documentation

For complete documentation, see the docs directory.

🤝 Contributing

Pull requests and suggestions are welcome! Please follow the existing code style and include tests for new features.

📄 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

---

Table of contents

• 📚 Documentation