drfhaust/led-status

readme

# LED Status Component

[![Component Registry](https://components.espressif.com/components/drfhaust/led-status/badge.svg)](https://components.espressif.com/components/drfhaust/led-status)

A flexible WS2812/SK6812 LED status indicator component for ESP-IDF. Features configurable patterns, colors, brightness control, custom callbacks, and timed displays.

## Features

- **Multiple LED Models**: WS2812, SK6812, WS2811
- **Built-in Patterns**: Solid, blink (slow/fast), double blink, pulse/breathing, chase
- **Predefined Colors**: Green, blue, red, yellow, cyan, white, purple, orange
- **Custom Patterns**: Callback support for user-defined animations
- **Timed Display**: Auto-off after specified duration
- **Flash Override**: Temporary color flash without disrupting pattern
- **Configurable Timing**: Adjust blink rates, pulse period, chase speed
- **HSV Support**: HSV to RGB conversion utility
- **Task Configuration**: Custom stack size, priority, core affinity
- **Direct Control**: Individual pixel access for advanced effects

## Installation

### ESP-IDF Component Registry

```bash
idf.py add-dependency "drfhaust/led-status"
```

### Manual Installation

Clone into your project's `components` directory:

```bash
cd components
git clone https://github.com/drfhaust/led-status.git
```

## Quick Start

### Simple Initialization

```c
#include "led_status.h"

void app_main(void)
{
    // Initialize single LED on GPIO 8
    led_status_init_simple(8, 1);

    // Set pattern
    led_status_set(LED_STATUS_PULSE, LED_COLOR_BLUE);
}
```

### Full Configuration

```c
#include "led_status.h"

void app_main(void)
{
    led_status_config_t cfg = LED_STATUS_CONFIG_DEFAULT();
    cfg.gpio_num = 8;
    cfg.num_leds = 4;
    cfg.brightness = 128;         // 50% brightness
    cfg.blink_slow_ms = 2000;     // 0.5 Hz blink
    cfg.pulse_period_ms = 3000;   // 3 second breathing cycle

    led_status_init(&cfg);

    // Chase effect on LED strip
    led_status_set(LED_STATUS_CHASE, LED_COLOR_GREEN);
}
```

## API Reference

### Initialization

```c
// Full config initialization
esp_err_t led_status_init(const led_status_config_t *config);

// Simple initialization with defaults
esp_err_t led_status_init_simple(int gpio_num, int num_leds);

// Cleanup
void led_status_deinit(void);

// Check state
bool led_status_is_initialized(void);
```

### Pattern Control

```c
// Set pattern with predefined color
void led_status_set(led_status_pattern_t pattern, led_color_t color);

// Set pattern with custom RGB
void led_status_set_rgb(led_status_pattern_t pattern, uint8_t r, uint8_t g, uint8_t b);

// Turn off
void led_status_off(void);

// Query state
led_status_pattern_t led_status_get_pattern(void);
void led_status_get_rgb(uint8_t *r, uint8_t *g, uint8_t *b);
```

### Timed Display

```c
// Show pattern then auto-off
void led_status_show_timed(led_status_pattern_t pattern, led_color_t color, uint32_t duration_ms);
void led_status_show_timed_rgb(led_status_pattern_t pattern, uint8_t r, uint8_t g, uint8_t b, uint32_t duration_ms);

// Flash briefly (non-blocking)
void led_status_flash(led_color_t color, uint32_t duration_ms);
void led_status_flash_rgb(uint8_t r, uint8_t g, uint8_t b, uint32_t duration_ms);
```

### Brightness

```c
void led_status_set_brightness(uint8_t brightness);  // 0-255
uint8_t led_status_get_brightness(void);
```

### Direct LED Control

```c
// Individual pixel control (for custom patterns)
void led_status_set_pixel(int index, uint8_t r, uint8_t g, uint8_t b);
void led_status_set_all(uint8_t r, uint8_t g, uint8_t b);
void led_status_clear(void);
void led_status_refresh(void);
```

### Custom Patterns

```c
// Set custom pattern callback
void led_status_set_custom_callback(led_status_custom_cb_t callback, void *user_ctx);

// Callback signature
typedef uint32_t (*led_status_custom_cb_t)(uint32_t tick, int num_leds, void *user_ctx);
```

### Color Utilities

```c
// HSV to RGB conversion
void led_status_hsv_to_rgb(uint16_t h, uint8_t s, uint8_t v, uint8_t *r, uint8_t *g, uint8_t *b);

// Get RGB for predefined color
void led_status_color_to_rgb(led_color_t color, uint8_t *r, uint8_t *g, uint8_t *b);
```

## Patterns

| Pattern | Description |
|---------|-------------|
| `LED_STATUS_OFF` | All LEDs off |
| `LED_STATUS_SOLID` | Constant on |
| `LED_STATUS_BLINK_SLOW` | Slow blink (configurable, default 1Hz) |
| `LED_STATUS_BLINK_FAST` | Fast blink (configurable, default 5Hz) |
| `LED_STATUS_BLINK_DOUBLE` | Double blink with pause |
| `LED_STATUS_PULSE` | Smooth breathing effect |
| `LED_STATUS_CHASE` | Chase effect (multi-LED strips) |
| `LED_STATUS_CUSTOM` | User-defined callback pattern |

## Colors

| Color | RGB Values |
|-------|------------|
| `LED_COLOR_OFF` | (0, 0, 0) |
| `LED_COLOR_GREEN` | (0, 255, 0) |
| `LED_COLOR_BLUE` | (0, 0, 255) |
| `LED_COLOR_RED` | (255, 0, 0) |
| `LED_COLOR_YELLOW` | (255, 180, 0) |
| `LED_COLOR_CYAN` | (0, 255, 255) |
| `LED_COLOR_WHITE` | (255, 255, 255) |
| `LED_COLOR_PURPLE` | (180, 0, 255) |
| `LED_COLOR_ORANGE` | (255, 100, 0) |

## Configuration Options

```c
typedef struct {
    int gpio_num;              // GPIO for LED data line (required)
    int num_leds;              // Number of LEDs (1-256, default 1)
    led_status_model_t model;  // LED model (default WS2812)
    uint8_t brightness;        // Initial brightness (0-255, default 64)

    // Timing (milliseconds)
    uint32_t blink_slow_ms;    // Slow blink period (default 1000)
    uint32_t blink_fast_ms;    // Fast blink period (default 200)
    uint32_t pulse_period_ms;  // Pulse cycle (default 2000)
    uint32_t chase_step_ms;    // Chase animation step (default 80)

    // Task configuration
    uint32_t task_stack_size;  // Stack size (default 2560)
    uint8_t task_priority;     // Priority (default 2)
    int task_core;             // Core affinity (-1 = any)

    // Custom patterns
    led_status_custom_cb_t custom_callback;
    void *custom_user_ctx;
} led_status_config_t;
```

## Custom Pattern Example

```c
// Rainbow cycle effect
uint32_t rainbow_callback(uint32_t tick, int num_leds, void *ctx)
{
    for (int i = 0; i < num_leds; i++) {
        uint16_t hue = (tick * 5 + i * 360 / num_leds) % 360;
        uint8_t r, g, b;
        led_status_hsv_to_rgb(hue, 100, 100, &r, &g, &b);
        led_status_set_pixel(i, r, g, b);
    }
    led_status_refresh();
    return 20;  // 20ms delay until next call
}

void app_main(void)
{
    led_status_config_t cfg = LED_STATUS_CONFIG_DEFAULT();
    cfg.gpio_num = 8;
    cfg.num_leds = 8;
    cfg.custom_callback = rainbow_callback;

    led_status_init(&cfg);
    led_status_set(LED_STATUS_CUSTOM, LED_COLOR_OFF);
}
```

## Usage Examples

### Status Indication

```c
// Startup: blue pulse
led_status_set(LED_STATUS_PULSE, LED_COLOR_BLUE);

// Connected: solid green
led_status_set(LED_STATUS_SOLID, LED_COLOR_GREEN);

// Error: fast red blink
led_status_set(LED_STATUS_BLINK_FAST, LED_COLOR_RED);

// Activity: flash briefly
led_status_flash(LED_COLOR_CYAN, 100);
```

### Timed Notifications

```c
// Show success for 3 seconds
led_status_show_timed(LED_STATUS_SOLID, LED_COLOR_GREEN, 3000);

// Error flash then auto-off
led_status_show_timed(LED_STATUS_BLINK_FAST, LED_COLOR_RED, 2000);
```

### LED Strip Effects

```c
// 8-LED strip with chase
led_status_config_t cfg = LED_STATUS_CONFIG_DEFAULT();
cfg.gpio_num = 8;
cfg.num_leds = 8;
cfg.chase_step_ms = 50;  // Faster chase
led_status_init(&cfg);

led_status_set(LED_STATUS_CHASE, LED_COLOR_PURPLE);
```

## Dependencies

- ESP-IDF >= 5.0
- [espressif/led_strip](https://components.espressif.com/components/espressif/led_strip) >= 2.5.4

## License

MIT License - see [LICENSE](LICENSE)

## Author

Olaifa Oluwadara Daniel ([@drfhaust](https://github.com/drfhaust))