/******************************************************************************
 * File:        HAL_LED.h
 * Component:   HAL_LED
 * Description: Public interface for the LED abstraction layer.
 *              Manages a pixel buffer for WS2812-style addressable LEDs
 *              and pushes color data through MCU_PIO. Supports indexed
 *              LED strips with per-pixel intensity scaling.
 *
 *              SetColor sets one LED's color and immediately pushes the
 *              entire strip to the hardware — no separate Update call needed.
 *
 * Layer:       HAL (hardware abstraction, one level above MCU drivers)
 *****************************************************************************/

#ifndef HAL_LED_H
#define HAL_LED_H

#include "STD_TYPES.h"

/* ------------------------------------------------------------------------ */
/*                      CONFIGURATION STRUCTURE                             */
/* ------------------------------------------------------------------------ */

/**
 * @brief  Per-instance LED strip/array configuration.
 *
 * One entry per LED strip, stored in HAL_LED_astrConfig[].
 * The array index is the instance parameter in all public API calls.
 */
typedef struct
{
    u8  u8NumLeds;       /**< Number of LEDs in this strip (1 for single LED) */
    u8  u8PioInstance;   /**< MCU_PIO config index for the data output        */
} HAL_LED_tstrConfig;

/* ------------------------------------------------------------------------ */
/*                            PUBLIC API                                    */
/* ------------------------------------------------------------------------ */

/**
 * @brief  Initialize the LED abstraction layer.
 *
 * Clears the internal pixel buffer to all-off (black). Does NOT init
 * MCU_PIO — SYS_ECU must call MCU_PIO_enuInit() before this.
 *
 * @return STD_OK on success.
 */
STD_tenuResult HAL_LED_enuInit(void);

/**
 * @brief  Set the color of a single LED and push the entire strip.
 *
 * Scales each color channel by u8Intensity (0-255), stores the result
 * in the internal pixel buffer, then immediately pushes all LEDs in
 * this strip to the PIO state machine.
 *
 * @param  u8Instance   HAL_LED config instance.
 * @param  u8LedIndex   LED position in the strip (0-based).
 * @param  u8Red        Red intensity (0-255, before scaling).
 * @param  u8Green      Green intensity (0-255, before scaling).
 * @param  u8Blue       Blue intensity (0-255, before scaling).
 * @param  u8Intensity  Global brightness scaler (0-255). 255 = full.
 * @return STD_OK                        on success,
 *         STD_INDEX_OUT_OF_RANGE_ERROR  if u8LedIndex >= u8NumLeds.
 */
STD_tenuResult HAL_LED_enuSetColor(u8 u8Instance, u8 u8LedIndex,
                                   u8 u8Red, u8 u8Green, u8 u8Blue,
                                   u8 u8Intensity);

#endif /* HAL_LED_H */