readme
This commit is contained in:
Andrey Aleksandrov
861
README.md
Normal file
861
README.md
Normal 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
|
||||
Reference in New Issue
Block a user