esp32libs/led_manager
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme

Browse Source
This commit is contained in:
Andrey Aleksandrov
2025-12-30 22:07:41 +02:00
parent 0b9f6929de
commit c57ff41636
1 changed files with 861 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

861
README.md Normal file
View File

@@ -0,0 +1,861 @@
# 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
```bash
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`:
```ini
lib_deps =
git+https://home.arcoa.eu:8413/esp32libs/led_manager.git
```
## 🚀 Quick Start
### Basic Usage
```c
#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
```c
#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
```c
#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);
}
```
## 📚 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
```c
// 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
```c
// 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:**
```c
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:**
```c
// 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:**
```c
// 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:**
```c
// 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:**
```c
// 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
```
#### 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:**
```c
// 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:**
```c
// 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:**
```c
// 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
```c
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
```c
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
```c
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
```c
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
```c
#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
```c
#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
```c
#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**
```c
// 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**
```c
// 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**
```c
// 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
```c
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:
```c
// 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
```c
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](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](CHANGELOG.md) for version history and changes.
## 🆘 Support
- Create an [issue](../../issues) 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](../dht22_sensor/README.md)** - Temperature/humidity sensor
- **[wifi_manager](../wifi_manager/README.md)** - WiFi connection management
- **[mqtt_manager](../mqtt_manager/README.md)** - 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