A flexible WS2812/SK6812 LED status indicator component for ESP-IDF. Features configurable patterns, colors, brightness control, custom callbacks, and timed displays.
- 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
idf.py add-dependency "drfhaust/led-status"Clone into your project's components directory:
cd components
git clone https://github.com/drfhaust/led-status.git#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);
}#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);
}// 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);// 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);// 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);void led_status_set_brightness(uint8_t brightness); // 0-255
uint8_t led_status_get_brightness(void);// 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);// 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);// 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);| 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 |
| 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) |
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;// 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);
}// 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);// 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);// 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);- ESP-IDF >= 5.0
- espressif/led_strip >= 2.5.4
MIT License - see LICENSE
Olaifa Oluwadara Daniel (@drfhaust)