ESP32-C6 WS2812 RGB LED Control Template

A production-ready template for controlling WS2812 RGB LEDs on ESP32-C6 using ESP-IDF with non-blocking operation and robust error handling.

✨ Features

• 🚀 Non-blocking LED control - Won't freeze your application
• 🛡️ Production-ready - Comprehensive error handling and resource management
• ⚙️ Easily configurable - Simple defines for hardware customization
• 📏 Scalable design - Supports single LEDs or LED strips
• 📖 Well documented - Doxygen-style comments and examples
• 🔧 Template ready - Copy-paste into your projects

🎯 Quick Start

Prerequisites

• PlatformIO installed
• ESP32-C6 board (tested on Waveshare ESP32-C6-LCD-1.47)
• VS Code with PlatformIO extension (recommended)

Clone and Run

git clone https://github.com/yourusername/esp32-c6-ws2812-template.git
cd esp32-c6-ws2812-template
pio run --target upload --target monitor

Expected Output

I (123) WS2812_RGB: ESP32-C6 WS2812 RGB LED Demo Starting...
I (124) WS2812_RGB: Board: Waveshare ESP32-C6-LCD-1.47
I (125) WS2812_RGB: LED GPIO: 8
I (126) WS2812_RGB: WS2812 driver initialized successfully on GPIO8
I (127) WS2812_RGB: Starting color cycling demo...
I (128) WS2812_RGB: Setting color: Red (R:255 G:0 B:0)
I (1129) WS2812_RGB: Setting color: Green (R:0 G:255 B:0)
I (2130) WS2812_RGB: Setting color: Blue (R:0 G:0 B:255)

🎨 Demo Colors

The template cycles through these colors every second:

Color	RGB Values	Hex
🔴 Red	(255, 0, 0)	#FF0000
🟢 Green	(0, 255, 0)	#00FF00
🔵 Blue	(0, 0, 255)	#0000FF
🟡 Yellow	(255, 255, 0)	#FFFF00
🟣 Purple	(255, 0, 255)	#FF00FF
🔵 Cyan	(0, 255, 255)	#00FFFF
⚪ White	(255, 255, 255)	#FFFFFF
⚫ Off	(0, 0, 0)	#000000

🔧 Hardware Configuration

Default Setup (Waveshare ESP32-C6-LCD-1.47)

#define WS2812_GPIO_PIN     GPIO_NUM_8      // Onboard LED pin
#define WS2812_LED_COUNT    1               // Single LED

Custom Hardware

// For external LED strip on GPIO18
#define WS2812_GPIO_PIN     GPIO_NUM_18
#define WS2812_LED_COUNT    8               // 8-LED strip

// Color order configuration (choose the correct one for your LED)
#define WS2812_COLOR_ORDER_RGB      // Use if Red/Green are swapped
// #define WS2812_COLOR_ORDER_GRB   // Standard WS2812B (default)

💻 Usage Examples

Basic Usage

#include "main.h"  // Include the template

void my_application() {
    // Initialize driver
    esp_err_t ret = ws2812_init();
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Init failed: %s", esp_err_to_name(ret));
        return;
    }

    // Set colors (non-blocking)
    ws2812_set_color(255, 0, 0);    // Red
    do_other_work();                // Your code runs immediately

    ws2812_set_color(0, 255, 0);    // Green
    do_more_work();                 // Non-blocking operation

    // Wait for transmission if needed
    ws2812_wait_done(100);          // 100ms timeout

    // Cleanup when done
    ws2812_deinit();
}

LED Strip Control

// Modify configuration for LED strip
#define WS2812_LED_COUNT    8

// In your code - each LED needs separate control
for (int i = 0; i < WS2812_LED_COUNT; i++) {
    ws2812_set_pixel(i, 255, 0, 0);  // Set pixel i to red
}
ws2812_refresh();  // Update all LEDs

🏗️ Project Structure

esp32-c6-ws2812-template/
├── 📁 src/
│   └── 📄 main.cpp                 # Main application code
├── 📁 docs/
│   └── 📄 project-documentation.md # Detailed technical docs
├── 📄 platformio.ini               # PlatformIO configuration
├── 📄 README.md                    # This file
└── 📄 LICENSE                      # MIT License

🚀 API Reference

Core Functions

Function	Description	Returns
ws2812_init()	Initialize WS2812 driver	esp_err_t
ws2812_set_color(r, g, b)	Set LED color (non-blocking)	esp_err_t
ws2812_wait_done(timeout)	Wait for transmission	esp_err_t
ws2812_deinit()	Cleanup and free resources	void

Configuration Options

Define	Default	Description
WS2812_GPIO_PIN	GPIO_NUM_8	LED data pin
WS2812_LED_COUNT	1	Number of LEDs
WS2812_COLOR_ORDER_RGB	defined	Use RGB color order
WS2812_COLOR_ORDER_GRB	undefined	Use GRB color order (standard)
RMT_RESOLUTION_HZ	10000000	RMT timing precision
COLOR_CHANGE_INTERVAL_MS	1000	Demo color interval

🔍 Technical Details

WS2812 Protocol

• Data Format: GRB (Green-Red-Blue) 24-bit per LED
• Timing: 800kHz data rate with precise pulse widths
• Reset: 50μs+ low pulse between frames

ESP32-C6 RMT Peripheral

• Hardware-accelerated timing generation
• Non-blocking operation with DMA
• Precise timing down to 100ns resolution

Performance

• ⚡ Transmission time: ~24μs per LED
• 🧠 CPU overhead: Minimal (hardware-accelerated)
• 💾 Memory usage: 3 bytes per LED + driver overhead

🛠️ Development

Build Commands

# Build only
pio run

# Build and flash
pio run --target upload

# Flash and monitor
pio run --target upload --target monitor

# Clean build
pio run --target clean

Debugging

Enable verbose logging:

esp_log_level_set("WS2812_RGB", ESP_LOG_VERBOSE);

Integration

1. Copy the driver functions to your project
2. Modify configuration defines for your hardware
3. Include in your main application
4. Initialize once, use everywhere

🐛 Troubleshooting

LED Not Working

• ✅ Check GPIO pin number in configuration
• ✅ Verify power supply (3.3V recommended)
• ✅ Ensure ws2812_init() returns ESP_OK

Wrong Colors

• ✅ Red/Green swapped? Use #define WS2812_COLOR_ORDER_RGB
• ✅ Colors still wrong? Try #define WS2812_COLOR_ORDER_GRB
• ✅ Try lower brightness values (50 instead of 255)
• ✅ Check if LED is WS2812B variant vs clone

Build Issues

• ✅ Update to ESP-IDF 5.0+
• ✅ Check board setting in platformio.ini
• ✅ Verify all includes are available

📚 Documentation

• Project Documentation - Detailed technical guide
• ESP-IDF Programming Guide - ESP32 development
• WS2812 Datasheet - LED specifications

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Espressif for the ESP32-C6 and ESP-IDF framework
• Waveshare for the ESP32-C6-LCD-1.47 development board
• WorldSemi for the WS2812 LED design
• PlatformIO for the excellent development environment

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: your.email@example.com

---

⭐ Star this repository if you found it helpful! ⭐

Made with ❤️ for the ESP32 community