/**
 * @file    led_driver.h
 * @brief   LED 驱动 — OOPC 不透明指针模式（Opaque Pointer）
 *
 * 设计原则（来自 oopc_architecture.md）:
 *   - .h 中仅放前向声明 typedef struct LedDriver_S LedDriver_S;
 *   - 外部调用者拿到 LedDriver_S* 指针，无法解引用访问内部字段
 *   - 所有操作必须通过公开 API 函数
 *   - 静态内存池，无 malloc
 *
 * UML 状态图:
 *   [*] --> OFF
 *   OFF --> ON        : Led_On()
 *   ON  --> OFF       : Led_Off()
 *   ON  --> BLINK     : Led_SetBlink(period_ms)
 *   OFF --> BLINK     : Led_SetBlink(period_ms)
 *   BLINK --> ON      : Led_On()
 *   BLINK --> OFF     : Led_Off()
 *   ON  --> BREATHING : Led_SetBreathing()
 *   OFF --> BREATHING : Led_SetBreathing()
 *   BLINK --> BREATHING : Led_SetBreathing()
 *   BREATHING --> OFF : Led_Off()
 */
#ifndef LED_DRIVER_H
#define LED_DRIVER_H

#include <stdint.h>
#include "hal_gpio.h"

/* ======== 前向声明 — 外部永远看不到结构体真身 ======== */
typedef struct LedDriver_S LedDriver_S;

/* ======== LED 工作状态枚举 ======== */
typedef enum {
    LED_STATE_OFF       = 0,
    LED_STATE_ON        = 1,
    LED_STATE_BLINK     = 2,
    LED_STATE_BREATHING = 3
} LedState_E;

/* ======== 公开 API ======== */

/**
 * @brief  创建 LED 驱动实例（静态内存池分配）
 * @param  port     GPIO 端口
 * @param  pin      GPIO 引脚
 * @param  active_low  1=低电平点亮, 0=高电平点亮
 * @return LedDriver_S* 实例指针, NULL=无可用槽位
 */
LedDriver_S* Led_Create(GPIO_Port_TypeDef port, GPIO_Pin_TypeDef pin, uint8_t active_low);

/**
 * @brief  销毁实例（归还到内存池）
 */
void Led_Destroy(LedDriver_S* me);

/**
 * @brief  点亮 LED（立即）
 */
void Led_On(LedDriver_S* me);

/**
 * @brief  熄灭 LED（立即）
 */
void Led_Off(LedDriver_S* me);

/**
 * @brief  设置闪烁模式
 * @param  period_ms  闪烁周期（亮+灭各 period_ms/2）
 */
void Led_SetBlink(LedDriver_S* me, uint16_t period_ms);

/**
 * @brief  设置呼吸灯模式（PWM 渐变）
 */
void Led_SetBreathing(LedDriver_S* me);

/**
 * @brief  周期性轮询（必须在主循环或定时器中调用）
 * @param  now_ms  当前系统时间戳
 * @note   内部根据当前 state 执行闪烁/呼吸逻辑
 */
void Led_Poll(LedDriver_S* me, uint32_t now_ms);

/**
 * @brief  获取当前状态
 */
LedState_E Led_GetState(const LedDriver_S* me);

/**
 * @brief  获取当前亮度（0-100%）
 */
uint8_t Led_GetBrightness(const LedDriver_S* me);

/* ======== 配置宏 ======== */
#define LED_MAX_INSTANCES   4   /* 最多同时管理 4 个 LED */

#endif /* LED_DRIVER_H */