/**
 * @file LEDIndicator.h
 * @brief WS2812 RGB LED status indicators
 * 
 * Provides visual feedback using two WS2812 LEDs:
 * - LED 0: Power status (Green = ON, Red = OFF)
 * - LED 1: Mode indicator (Blue = DCC, Yellow = Analog)
 * 
 * @author Locomotive Test Bench Project
 * @date 2025
 */

#ifndef LED_INDICATOR_H
#define LED_INDICATOR_H

#include <Arduino.h>
#include <FastLED.h>

// Pin definition for WS2812 LEDs
#define LED_DATA_PIN 4        ///< Data pin for WS2812 strip
#define NUM_LEDS 2            ///< Number of LEDs (Power + Mode)

// LED indices
#define LED_POWER 0           ///< Power status indicator
#define LED_MODE 1            ///< Mode indicator (DCC/Analog)

/**
 * @class LEDIndicator
 * @brief Manages WS2812 RGB LED status displays
 * 
 * Controls two LEDs for system status indication:
 * - Power LED: Shows system power state with boot animation
 * - Mode LED: Shows control mode with pulsing effect
 */
class LEDIndicator {
public:
    /**
     * @brief Constructor
     */
    LEDIndicator();
    
    /**
     * @brief Initialize LED hardware
     * 
     * Configures FastLED library and sets LEDs to off state.
     */
    void begin();
    
    /**
     * @brief Update LED display
     * 
     * Must be called regularly from main loop to update
     * pulsing effects and animations.
     */
    void update();
    
    /**
     * @brief Set power status
     * @param on true = power on (green), false = off (red)
     */
    void setPowerOn(bool on);
    
    /**
     * @brief Set operating mode
     * @param isDCC true = DCC mode (blue), false = Analog (yellow)
     */
    void setMode(bool isDCC);
    
    /**
     * @brief Set LED brightness
     * @param brightness Brightness level (0-255)
     */
    void setBrightness(uint8_t brightness);
    
    /**
     * @brief Play power-on animation sequence
     * 
     * Shows 3-flash boot sequence on power LED.
     */
    void powerOnSequence();
    
    /**
     * @brief Play mode change animation
     * 
     * Smooth fade transition when switching modes.
     */
    void modeChangeEffect();
    
private:
    CRGB leds[NUM_LEDS];        ///< LED array
    bool powerOn;               ///< Power status flag
    bool dccMode;               ///< Mode flag (DCC/Analog)
    uint8_t brightness;         ///< Current brightness level
    unsigned long lastUpdate;   ///< Last update timestamp
    uint8_t pulsePhase;         ///< Pulse animation phase
    
    // LED color definitions
    static constexpr CRGB COLOR_POWER_ON = CRGB::Green;   ///< Power ON color
    static constexpr CRGB COLOR_POWER_OFF = CRGB::Red;    ///< Power OFF color
    static constexpr CRGB COLOR_DCC = CRGB::Blue;         ///< DCC mode color
    static constexpr CRGB COLOR_ANALOG = CRGB::Yellow;    ///< Analog mode color
    static constexpr CRGB COLOR_OFF = CRGB::Black;        ///< LED off state
};

#endif