led_manager/README.md

LED Manager Library for ESP32

A comprehensive and feature-rich LED control library for ESP32 development with ESP-IDF framework. This library provides high-level LED management with support for WS2812/NeoPixel LED strips, color control, blinking functionality, and hardware-accelerated drivers.

📋 Features

• ✅ High-level LED management - Simple API for complex LED operations
• ✅ WS2812/NeoPixel support - Compatible with popular RGB LED strips
• ✅ Hardware acceleration - RMT and SPI driver support for precise timing
• ✅ Color management - Predefined colors with easy-to-use names
• ✅ Blinking functionality - Non-blocking blinking with configurable rates
• ✅ Thread-safe operations - Uses FreeRTOS tasks for background operations
• ✅ RGB control - Full 24-bit color control (0-255 per channel)
• ✅ Multiple driver backends - RMT (recommended) and SPI implementations
• ✅ Status indication - Perfect for system status visualization
• ✅ Memory efficient - Optimized for single-LED or small strip usage

📦 Installation

Method 1: Git Submodule

cd your_project_directory/lib
git submodule add https://home.arcoa.eu:8413/esp32libs/led_manager.git

Method 2: Manual Copy

1. Clone or download this repository
2. Copy the led_manager folder to your project's lib/ or components/ directory
3. Include the header in your code: #include "led_manager.h"

Method 3: PlatformIO Library

Add to your platformio.ini:

lib_deps =
    git+https://home.arcoa.eu:8413/esp32libs/led_manager.git

🚀 Quick Start

Basic Usage

#include "led_manager.h"

void app_main(void) {
    // Initialize LED manager on GPIO 8
    esp_err_t ret = led_manager_init(GPIO_NUM_8);
    if (ret != ESP_OK) {
        printf("LED manager initialization failed: %s\n", esp_err_to_name(ret));
        return;
    }

    // Set solid green color
    led_manager_set_color_by_name("Green", false);
    vTaskDelay(pdMS_TO_TICKS(2000));

    // Set blinking red color
    led_manager_set_color_by_name("Red", true);
    vTaskDelay(pdMS_TO_TICKS(5000));

    // Clear LED and cleanup
    led_manager_clear();
    led_manager_deinit();
}

Status Indication Example

#include "led_manager.h"

typedef enum {
    STATUS_INITIALIZING,
    STATUS_CONNECTING,
    STATUS_CONNECTED,
    STATUS_ERROR
} system_status_t;

void set_system_status(system_status_t status) {
    switch (status) {
        case STATUS_INITIALIZING:
            led_manager_set_color_by_name("Blue", false);
            break;
        case STATUS_CONNECTING:
            led_manager_set_color_by_name("Orange", true);  // Blinking orange
            break;
        case STATUS_CONNECTED:
            led_manager_set_color_by_name("Green", false);  // Solid green
            break;
        case STATUS_ERROR:
            led_manager_set_color_by_name("Red", true);     // Blinking red
            break;
    }
}

void app_main(void) {
    led_manager_init(GPIO_NUM_8);

    // System startup sequence
    set_system_status(STATUS_INITIALIZING);
    vTaskDelay(pdMS_TO_TICKS(1000));

    set_system_status(STATUS_CONNECTING);
    vTaskDelay(pdMS_TO_TICKS(3000));

    set_system_status(STATUS_CONNECTED);

    // Your application logic here...
}

Advanced RGB Control

#include "led_manager.h"

void rgb_demo(void) {
    led_manager_init(GPIO_NUM_8);

    // Set custom colors using RGB values
    led_manager_set_rgb(255, 0, 128);    // Pink
    vTaskDelay(pdMS_TO_TICKS(1000));

    led_manager_set_rgb(128, 255, 0);    // Lime green
    vTaskDelay(pdMS_TO_TICKS(1000));

    led_manager_set_rgb(0, 128, 255);    // Sky blue
    vTaskDelay(pdMS_TO_TICKS(1000));

    // Use color enum for predefined colors
    led_manager_set_color(LED_COLOR_YELLOW, false);
    vTaskDelay(pdMS_TO_TICKS(1000));

    // Configure custom blink rate
    led_manager_set_blink_rate(250);     // Fast blinking (250ms)
    led_manager_set_color(LED_COLOR_RED, true);
}

HSV + Global Brightness

#include "led_manager.h"

void hsv_demo(void) {
    led_manager_init(GPIO_NUM_8);

    // Set a teal color using HSV
    led_manager_set_hsv(180, 255, 200);

    // Dim the LED globally without changing hue/saturation
    led_manager_set_brightness(64);
}

📚 API Reference

Data Types

led_color_t (Enum)

Predefined color constants for easy color selection:

Value	Color	RGB Values	Use Case
LED_COLOR_RED	Red	(200, 0, 0)	Error states, alerts
LED_COLOR_ORANGE	Orange	(200, 40, 0)	Warning states, connecting
LED_COLOR_YELLOW	Yellow	(200, 160, 0)	Caution states, processing
LED_COLOR_GREEN	Green	(0, 180, 0)	Success states, ready
LED_COLOR_BLUE	Blue	(0, 0, 160)	Information states, idle

Constants & Variables

Default Configuration Values

Constant	Value	Description
Default GPIO	User-defined	GPIO pin for LED strip connection
Default Blink Rate	500ms	Standard blinking interval
LED Count	1	Single LED configuration (configurable)
Color Depth	24-bit	Full RGB color support (8 bits per channel)

Predefined RGB Colors

// Internal color definitions (read-only)
static const struct {
    uint8_t red;        // Red component (0-255)
    uint8_t green;      // Green component (0-255)
    uint8_t blue;       // Blue component (0-255)
    const char *name;   // Color name string
    led_color_t enum_val; // Enum identifier
} rgb_colors[] = {
    {200, 0, 0, "Red", LED_COLOR_RED},
    {200, 40, 0, "Orange", LED_COLOR_ORANGE},
    {200, 160, 0, "Yellow", LED_COLOR_YELLOW},
    {0, 180, 0, "Green", LED_COLOR_GREEN},
    {0, 0, 160, "Blue", LED_COLOR_BLUE}
};

Internal State Variables

// Library state (internal use only)
static led_strip_handle_t led_strip = NULL;    // LED strip handle
static bool is_initialized = false;            // Initialization state
static TaskHandle_t blink_task_handle = NULL;  // Blinking task handle
static bool is_blinking = false;               // Blinking state
static uint8_t current_red = 0;                // Current red component
static uint8_t current_green = 0;              // Current green component
static uint8_t current_blue = 0;               // Current blue component
static uint32_t blink_rate_ms = 500;           // Current blink rate
static bool blink_state = false;               // Current blink phase

Functions

Initialization Functions

esp_err_t led_manager_init(int gpio_pin)

Initialize the LED manager with the specified GPIO pin.

Parameters:

• gpio_pin: GPIO pin number where LED strip data line is connected

Returns:

• ESP_OK: Initialization successful
• ESP_ERR_INVALID_ARG: Invalid GPIO pin
• ESP_ERR_INVALID_STATE: Already initialized
• ESP_FAIL: Hardware initialization failed

Technical Details:

• Configures RMT peripheral for precise timing
• Sets up single LED strip configuration
• Initializes internal state variables
• Clears LED to off state

Example:

esp_err_t ret = led_manager_init(GPIO_NUM_8);
if (ret != ESP_OK) {
    ESP_LOGE("APP", "LED init failed: %s", esp_err_to_name(ret));
}

esp_err_t led_manager_deinit(void)

Deinitialize the LED manager and free all resources.

Returns:

• ESP_OK: Success
• Error code on failure

Technical Details:

• Stops blinking task if running
• Clears LED strip
• Deletes RMT peripheral configuration
• Frees allocated memory

Example:

// Cleanup before restart
led_manager_clear();
led_manager_deinit();
esp_restart();

Color Setting Functions

esp_err_t led_manager_set_color_by_name(const char *color_name, bool blink)

Set LED color using string name with optional blinking.

Parameters:

• color_name: Color name string (case-insensitive matching)
  • Valid values: "Red", "Orange", "Yellow", "Green", "Blue"
• blink: Enable blinking (true) or solid color (false)

Returns:

• ESP_OK: Color set successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized
• ESP_ERR_INVALID_ARG: Invalid color name or NULL pointer

Technical Details:

• Performs case-insensitive string matching
• Automatically stops existing blinking when setting new color
• Creates FreeRTOS task for blinking if enabled

Example:

// Status indication
led_manager_set_color_by_name("Green", false);    // Connected
led_manager_set_color_by_name("Orange", true);    // Connecting
led_manager_set_color_by_name("Red", true);       // Error

esp_err_t led_manager_set_color(led_color_t color, bool blink)

Set LED color using color enum with optional blinking.

Parameters:

• color: Color enum value from led_color_t
• blink: Enable blinking (true) or solid color (false)

Returns:

• Same as led_manager_set_color_by_name()

Technical Details:

• More efficient than string-based function
• Direct enum-to-RGB lookup
• Fallback to red color for invalid enum values

Example:

// Using enum for better performance
led_manager_set_color(LED_COLOR_GREEN, false);
led_manager_set_color(LED_COLOR_RED, true);

esp_err_t led_manager_set_rgb(uint8_t red, uint8_t green, uint8_t blue)

Set LED color using direct RGB values.

Parameters:

• red: Red component (0-255)
• green: Green component (0-255)
• blue: Blue component (0-255)

Returns:

• ESP_OK: Color set successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized
• Hardware error codes on failure

Technical Details:

• Direct RGB control for custom colors
• Stops blinking and sets solid color
• Updates internal color state variables

Example:

// Custom colors
led_manager_set_rgb(255, 0, 128);    // Pink
led_manager_set_rgb(128, 255, 0);    // Lime
led_manager_set_rgb(255, 165, 0);    // Orange variant
led_manager_set_rgb(75, 0, 130);     // Indigo

esp_err_t led_manager_set_hsv(uint16_t hue, uint8_t saturation, uint8_t value)

Set LED color using HSV values.

Parameters:

• hue: Hue component (0-360)
• saturation: Saturation component (0-255)
• value: Value/brightness component (0-255)

Returns:

• ESP_OK: Color set successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized
• Hardware error codes on failure

Technical Details:

• Stores HSV as the current color for blinking
• Global brightness scales the value component
• If blinking is active, color updates take effect on the next blink cycle

Example:

// Teal-ish color
led_manager_set_hsv(180, 255, 200);

esp_err_t led_manager_set_brightness(uint8_t brightness)

Set global brightness without changing the current hue/saturation.

Parameters:

• brightness: Brightness value (0-255)

Returns:

• ESP_OK: Brightness updated successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized
• Hardware error codes on failure

Technical Details:

• Scales the current HSV value when pushing to the LED
• If blinking is active, brightness applies to subsequent blink updates

Example:

// Dim to 25%
led_manager_set_brightness(64);

Control Functions

esp_err_t led_manager_clear(void)

Turn off the LED (set to black/off state).

Returns:

• ESP_OK: LED cleared successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized
• Hardware error codes on failure

Technical Details:

• Sets RGB values to (0, 0, 0)
• Does not stop blinking task (use led_manager_stop_blinking() first)
• Immediate effect

Example:

// Turn off LED completely
led_manager_clear();

// Or stop blinking first, then clear
led_manager_stop_blinking();
led_manager_clear();

esp_err_t led_manager_stop_blinking(void)

Stop blinking and maintain current solid color.

Returns:

• ESP_OK: Blinking stopped successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized

Technical Details:

• Stops FreeRTOS blinking task
• Restores solid color using current RGB values
• Graceful task termination with cleanup

Example:

// Stop blinking but keep current color
led_manager_set_color_by_name("Red", true);   // Start blinking red
vTaskDelay(pdMS_TO_TICKS(5000));              // Blink for 5 seconds
led_manager_stop_blinking();                  // Stop blinking, keep red

esp_err_t led_manager_set_blink_rate(uint32_t rate_ms)

Configure the blinking rate for future blink operations.

Parameters:

• rate_ms: Blink interval in milliseconds (recommended: 100-2000ms)

Returns:

• ESP_OK: Blink rate set successfully
• ESP_ERR_INVALID_STATE: LED manager not initialized

Technical Details:

• Affects all subsequent blinking operations
• Does not change currently running blink rate
• Minimum recommended value: 50ms
• Maximum recommended value: 5000ms

Example:

// Configure different blink speeds
led_manager_set_blink_rate(1000);             // Slow blink (1 second)
led_manager_set_color_by_name("Blue", true);

led_manager_set_blink_rate(200);              // Fast blink (200ms)
led_manager_set_color_by_name("Red", true);

🔧 Hardware Setup

Supported LED Types

• WS2812 - Most common RGB LED strip
• WS2812B - Improved version with better timing
• SK6812 - RGBW variant support
• NeoPixel - Adafruit brand WS2812-based LEDs

Wiring Diagram

WS2812 LED Strip    ESP32
-----------------   -----
VCC (5V/3.3V) ----  5V/3.3V Power Supply
GND           ----  GND
DIN (Data)    ----  GPIO_NUM_X

GPIO Recommendations

Compatible GPIO pins:

• ESP32: GPIO 2, 4, 5, 16, 17, 18, 19, 21, 22, 23
• ESP32-C3/C6: GPIO 0-10, 18-21 (avoid USB pins 18,19 when using serial)
• ESP32-S2/S3: GPIO 1-17, 21, 26-45

Recommended pins:

• GPIO 8 - Primary recommendation for ESP32-C6
• GPIO 2 - Built-in LED pin on many boards
• GPIO 16, 17 - Good alternatives for ESP32

Power Considerations

• Single LED: ~20mA @ 3.3V (60mA max at full white)
• Short strips: ESP32 can power 5-10 LEDs directly
• Longer strips: External 5V power supply required
• Data voltage: 3.3V logic levels work with most LED strips

Pull-up Resistor

Most LED strips work without additional components, but for reliability:

ESP32 GPIO ----[330Ω]---- LED Strip Data

📖 Usage Patterns

System Status Indication

void system_status_demo(void) {
    led_manager_init(GPIO_NUM_8);

    // Boot sequence
    led_manager_set_color_by_name("Blue", false);     // System starting

    // WiFi connection
    led_manager_set_color_by_name("Orange", true);    // Connecting to WiFi

    // Connected successfully
    led_manager_set_color_by_name("Green", false);    // All systems go

    // Error occurred
    led_manager_set_color_by_name("Red", true);       // Alert user
}

Custom Color Schemes

void custom_color_demo(void) {
    led_manager_init(GPIO_NUM_8);

    // Pastel colors
    led_manager_set_rgb(255, 182, 193);  // Light pink
    vTaskDelay(pdMS_TO_TICKS(1000));

    led_manager_set_rgb(173, 216, 230);  // Light blue
    vTaskDelay(pdMS_TO_TICKS(1000));

    led_manager_set_rgb(144, 238, 144);  // Light green
    vTaskDelay(pdMS_TO_TICKS(1000));

    // High-intensity colors
    led_manager_set_rgb(255, 0, 0);      // Pure red
    led_manager_set_rgb(0, 255, 0);      // Pure green
    led_manager_set_rgb(0, 0, 255);      // Pure blue
}

Breathing Effect Simulation

void breathing_effect_demo(void) {
    led_manager_init(GPIO_NUM_8);

    // Simulate breathing with different blink rates
    led_manager_set_blink_rate(2000);    // Very slow blink
    led_manager_set_color_by_name("Blue", true);
    vTaskDelay(pdMS_TO_TICKS(10000));

    led_manager_set_blink_rate(1000);    // Medium blink
    led_manager_set_color_by_name("Green", true);
    vTaskDelay(pdMS_TO_TICKS(10000));

    led_manager_set_blink_rate(500);     // Fast blink
    led_manager_set_color_by_name("Red", true);
}

Multi-State Application

typedef enum {
    APP_STATE_IDLE,
    APP_STATE_WORKING,
    APP_STATE_SUCCESS,
    APP_STATE_WARNING,
    APP_STATE_ERROR
} app_state_t;

void set_led_for_state(app_state_t state) {
    switch (state) {
        case APP_STATE_IDLE:
            led_manager_set_color(LED_COLOR_BLUE, false);
            break;

        case APP_STATE_WORKING:
            led_manager_set_blink_rate(500);
            led_manager_set_color(LED_COLOR_YELLOW, true);
            break;

        case APP_STATE_SUCCESS:
            led_manager_stop_blinking();
            led_manager_set_color(LED_COLOR_GREEN, false);
            break;

        case APP_STATE_WARNING:
            led_manager_set_blink_rate(1000);
            led_manager_set_color(LED_COLOR_ORANGE, true);
            break;

        case APP_STATE_ERROR:
            led_manager_set_blink_rate(250);  // Fast blinking for urgent attention
            led_manager_set_color(LED_COLOR_RED, true);
            break;
    }
}

🧩 Integration Examples

With WiFi Manager

#include "led_manager.h"
#include "wifi_manager.h"

void wifi_status_indication(void) {
    led_manager_init(GPIO_NUM_8);

    // WiFi connecting
    led_manager_set_color_by_name("Orange", true);

    wifi_manager_config_t config = {
        .ssid = "YourSSID",
        .password = "YourPassword"
    };

    esp_err_t ret = wifi_manager_init(&config);

    if (ret == ESP_OK) {
        // Connected successfully
        led_manager_set_color_by_name("Green", false);
    } else {
        // Connection failed
        led_manager_set_color_by_name("Red", true);
    }
}

With MQTT Manager

#include "led_manager.h"
#include "mqtt_manager.h"

void mqtt_status_callback(mqtt_event_t event) {
    switch (event) {
        case MQTT_EVENT_CONNECTING:
            led_manager_set_color_by_name("Orange", true);
            break;

        case MQTT_EVENT_CONNECTED:
            led_manager_set_color_by_name("Green", false);
            break;

        case MQTT_EVENT_DISCONNECTED:
            led_manager_set_color_by_name("Red", true);
            break;

        case MQTT_EVENT_DATA:
            // Brief flash to indicate data received
            led_manager_set_color_by_name("Blue", false);
            vTaskDelay(pdMS_TO_TICKS(100));
            led_manager_set_color_by_name("Green", false);
            break;
    }
}

With Sensor Readings

#include "led_manager.h"
#include "dht22_sensor.h"

void sensor_status_indication(void) {
    led_manager_init(GPIO_NUM_8);
    dht22_init(GPIO_NUM_4);

    while (1) {
        float temperature, humidity;
        dht22_result_t result = dht22_read(&temperature, &humidity);

        if (result == DHT22_OK) {
            // Good reading - brief green flash
            led_manager_set_color_by_name("Green", false);
            vTaskDelay(pdMS_TO_TICKS(100));
            led_manager_clear();

            // Check for warning conditions
            if (temperature > 35.0 || humidity > 80.0) {
                led_manager_set_color_by_name("Yellow", true);  // Warning
            } else if (temperature > 40.0 || humidity > 90.0) {
                led_manager_set_color_by_name("Red", true);     // Critical
            }
        } else {
            // Sensor error
            led_manager_set_color_by_name("Red", true);
        }

        vTaskDelay(pdMS_TO_TICKS(5000));  // Check every 5 seconds
    }
}

🔍 Troubleshooting

Common Issues

1. LED not lighting up

   // Check initialization
   esp_err_t ret = led_manager_init(GPIO_NUM_8);
   if (ret != ESP_OK) {
       ESP_LOGE("LED", "Init failed: %s", esp_err_to_name(ret));
   }
   
   // Verify GPIO pin is correct
   // Try basic RGB test
   led_manager_set_rgb(255, 0, 0);  // Should show red
   

2. Colors appear wrong

   // LED strip may have different color order (GRB vs RGB)
   // Try each primary color individually:
   led_manager_set_rgb(255, 0, 0);    // Should be red
   led_manager_set_rgb(0, 255, 0);    // Should be green
   led_manager_set_rgb(0, 0, 255);    // Should be blue
   

3. Blinking not working

   // Check if blinking task is created
   led_manager_set_color_by_name("Red", true);
   
   // Verify FreeRTOS configuration allows task creation
   // Check available heap memory
   

4. Intermittent operation

   • Check power supply stability
   • Verify wiring connections
   • Add pull-up resistor to data line
   • Check for electromagnetic interference

Hardware Troubleshooting

Power Issues:

• Ensure adequate power supply (5V/1A for 10+ LEDs)
• Check voltage levels with multimeter
• Verify ground connections

Signal Issues:

• Add 330Ω resistor in series with data line
• Keep wiring short (< 1 meter for reliable operation)
• Use twisted pair or shielded cable for longer runs

Performance Issues:

• Monitor FreeRTOS heap usage
• Check for task stack overflow
• Verify GPIO pin capabilities

Debug Functions

void led_debug_sequence(void) {
    ESP_LOGI("LED", "Starting LED debug sequence");

    // Test all predefined colors
    const char* colors[] = {"Red", "Orange", "Yellow", "Green", "Blue"};
    for (int i = 0; i < 5; i++) {
        ESP_LOGI("LED", "Testing color: %s", colors[i]);
        led_manager_set_color_by_name(colors[i], false);
        vTaskDelay(pdMS_TO_TICKS(1000));
    }

    // Test blinking
    ESP_LOGI("LED", "Testing blinking");
    led_manager_set_color_by_name("Red", true);
    vTaskDelay(pdMS_TO_TICKS(3000));

    // Test RGB values
    ESP_LOGI("LED", "Testing RGB values");
    led_manager_set_rgb(255, 128, 64);  // Custom orange
    vTaskDelay(pdMS_TO_TICKS(1000));

    led_manager_clear();
    ESP_LOGI("LED", "Debug sequence complete");
}

⚙️ Configuration

Compile-time Configuration

The library uses default configurations that work for most applications. Advanced users can modify the source code for specific requirements:

// In led_manager.c - modify these values if needed:
#define LED_STRIP_LED_COUNT     1        // Number of LEDs
#define LED_STRIP_RMT_RESOLUTION 10000000 // 10MHz resolution
#define LED_STRIP_TASK_PRIORITY  5       // Blinking task priority
#define LED_STRIP_TASK_STACK_SIZE 2048   // Task stack size

Runtime Configuration

void configure_led_advanced(void) {
    // Initialize with custom settings
    led_manager_init(GPIO_NUM_8);

    // Set custom blink rates for different scenarios
    led_manager_set_blink_rate(1000);    // Slow for warnings
    led_manager_set_blink_rate(200);     // Fast for alerts
    led_manager_set_blink_rate(2000);    // Very slow for info

    // Custom color intensity (dimmer colors)
    led_manager_set_rgb(100, 0, 0);      // Dim red
    led_manager_set_rgb(0, 100, 0);      // Dim green
}

📄 License

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

🤝 Contributing

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

📈 Version History

See CHANGELOG.md for version history and changes.

🆘 Support

• Create an issue for bug reports or feature requests
• Check existing issues for known problems and solutions

⚡ Performance Notes

• Memory usage: ~500 bytes RAM (including task stack)
• CPU impact: Minimal, hardware-accelerated timing
• Task overhead: Single FreeRTOS task for blinking (when enabled)
• Response time: Immediate color changes, ~1ms update time
• Power consumption:
  • Single LED: 0-60mA depending on color and brightness
  • ESP32 overhead: ~2mA for library management
  • Blinking task: ~1% CPU usage

🔗 Related Libraries

• dht22_sensor - Temperature/humidity sensor
• wifi_manager - WiFi connection management
• mqtt_manager - MQTT communication

🎯 Use Cases

• IoT Status Indication - Visual feedback for device states
• Debugging Aid - Color-coded debug information
• User Interface - Simple visual feedback system
• Ambient Lighting - Mood lighting and notification system
• Industrial Monitoring - Equipment status visualization
• Home Automation - Status displays for smart devices