/**
 * @file htr3236.h
 * @brief HTR3236 36-Channel LED PWM Driver Driver for XMOS Platform
 * @version 1.1
 */

#ifndef HTR3236_H
#define HTR3236_H

#include <xccompat.h>
#include <stdint.h>
#include <i2c.h>

/*=========================================================================
    I2C 寄存器地址定义
    -----------------------------------------------------------------------*/
#define HTR3236_REG_SHUTDOWN         0x00  // 软件关断寄存器
#define HTR3236_REG_PWM_START         0x01  // PWM 寄存器起始地址 (OUT1)
#define HTR3236_REG_PWM_END           0x24  // PWM 寄存器结束地址 (OUT36)
#define HTR3236_REG_PWM_UPDATE        0x25  // PWM 更新寄存器
#define HTR3236_REG_LED_CTRL_START    0x26  // LED 控制寄存器起始地址 (OUT1)
#define HTR3236_REG_LED_CTRL_END      0x49  // LED 控制寄存器结束地址 (OUT36)
#define HTR3236_REG_GLOBAL_CTRL       0x4A  // 全局控制寄存器
#define HTR3236_REG_FREQ_SET          0x4B  // 频率设置寄存器
#define HTR3236_REG_RESET              0x4F  // 复位寄存器

/*=========================================================================
    寄存器位定义
    -----------------------------------------------------------------------*/
// 关断寄存器 (00h)
#define HTR3236_SHUTDOWN_MASK         0x01
#define HTR3236_SHUTDOWN_SOFT          0x00
#define HTR3236_NORMAL_OP              0x01

// LED 控制寄存器位 (26h~49h)
#define HTR3236_LED_OUT_MASK           0x01
#define HTR3236_LED_CURRENT_SHIFT      1
#define HTR3236_LED_CURRENT_MASK       (0x03 << 1)

// 全局控制寄存器 (4Ah)
#define HTR3236_GLOBAL_EN_MASK         0x01

// 频率设置寄存器 (4Bh)
// #define HTR3236_FREQ_3KHZ              0x00
// #define HTR3236_FREQ_22KHZ             0x01
// #define HTR3236_FREQ_MASK               0x01

/*=========================================================================
    数据类型定义
    -----------------------------------------------------------------------*/
typedef enum {
    HTR3236_CURRENT_FULL = 0,   // IMAX
    HTR3236_CURRENT_HALF = 1,   // IMAX/2
    HTR3236_CURRENT_THIRD = 2,  // IMAX/3
    HTR3236_CURRENT_QUARTER = 3 // IMAX/4
} htr3236_current_t;

typedef enum {
    HTR3236_FREQ_3KHZ = 0,
    HTR3236_FREQ_22KHZ = 1
} htr3236_freq_t;

typedef enum {
    HTR3236_ADDR_GND = 0x3C,  // AD = GND: 8位地址 0x78
    HTR3236_ADDR_SCL = 0x3D,  // AD = SCL: 8位地址 0x7A  
    HTR3236_ADDR_SDA = 0x3E,  // AD = SDA: 8位地址 0x7C
    HTR3236_ADDR_VCC = 0x3F   // AD = VCC: 8位地址 0x7E
} htr3236_addr_t;

/**
 * @brief HTR3236 设备结构体
 */
typedef struct {
    uint8_t i2c_addr;           // I2C 设备地址
} htr3236_t;

/*=========================================================================
    API 函数声明
    -----------------------------------------------------------------------*/

/**
 * @brief 初始化 HTR3236 设备
 * @param dev 设备结构体指针
 * @param i2c I2C 主控接口
 * @param addr I2C 设备地址
 * @param sdb_port SDB 控制端口
 * @param sdb_pin SDB 引脚号
 */
void htr3236_init(htr3236_t *dev, uint8_t addr);

/**
 * @brief 硬件使能 (SDB 拉高)
 * @param dev 设备结构体指针
 */
void htr3236_hw_enable(htr3236_t *dev);

/**
 * @brief 硬件关断 (SDB 拉低)
 * @param dev 设备结构体指针
 */
void htr3236_hw_disable(htr3236_t *dev);

/**
 * @brief 软件唤醒 (正常模式)
 * @param dev 设备结构体指针
 * @return 0:成功, -1:失败
 */
int htr3236_software_wake(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c));

/**
 * @brief 软件关断
 * @param dev 设备结构体指针
 * @return 0:成功, -1:失败
 */
int htr3236_software_shutdown(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c));

/**
 * @brief 软件复位所有寄存器
 * @param dev 设备结构体指针
 * @return 0:成功, -1:失败
 */
int htr3236_software_reset(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c));

/**
 * @brief 设置单路 PWM 亮度
 * @param dev 设备结构体指针
 * @param channel 通道号 (1-36)
 * @param brightness 亮度值 (0-255)
 * @return 0:成功, -1:失败
 */
int htr3236_set_pwm(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c), uint8_t channel, uint8_t brightness);

/**
 * @brief 批量设置多路 PWM 亮度 (使用自动地址递增)
 * @param dev 设备结构体指针
 * @param start_ch 起始通道号 (1-36)
 * @param values 亮度值数组
 * @param len 通道数量
 * @return 0:成功, -1:失败
 */
int htr3236_set_pwm_bulk(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c), uint8_t start_ch, 
                         const uint8_t *values, uint8_t len);

/**
 * @brief 设置单路 LED 电流档位和使能状态
 * @param dev 设备结构体指针
 * @param channel 通道号 (1-36)
 * @param current 电流档位
 * @param enable LED 使能 (1:开启, 0:关闭)
 * @return 0:成功, -1:失败
 */
int htr3236_set_led_config(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c), uint8_t channel,
                           htr3236_current_t current, uint8_t enable);

/**
 * @brief 批量设置多路 LED 配置
 * @param dev 设备结构体指针
 * @param start_ch 起始通道号 (1-36)
 * @param configs 配置数据数组 (每个字节: bit0=使能, bit2-1=电流档位)
 * @param len 通道数量
 * @return 0:成功, -1:失败
 */
int htr3236_set_led_config_bulk(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c), uint8_t start_ch,
                                const uint8_t *configs, uint8_t len);

/**
 * @brief 更新 PWM 和 LED 配置 (写入 25h 寄存器)
 * @param dev 设备结构体指针
 * @return 0:成功, -1:失败
 */
int htr3236_update(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c));

/**
 * @brief 全局 LED 使能控制
 * @param dev 设备结构体指针
 * @param enable 1:关闭所有LED, 0:正常模式
 * @return 0:成功, -1:失败
 */
int htr3236_global_enable(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c), uint8_t enable);

/**
 * @brief 设置 PWM 频率
 * @param dev 设备结构体指针
 * @param freq 频率 (0:3kHz, 1:22kHz)
 * @return 0:成功, -1:失败
 */
int htr3236_set_frequency(htr3236_t *dev, CLIENT_INTERFACE(i2c_master_if, i2c), htr3236_freq_t freq);

/**
 * @brief Gamma 校正查找表 (32级)
 * @param index Gamma 索引 (0-31)
 * @return PWM 值 (0-255)
 */
uint8_t htr3236_gamma_32(uint8_t index);

/**
 * @brief Gamma 校正查找表 (64级)
 * @param index Gamma 索引 (0-63)
 * @return PWM 值 (0-255)
 */
uint8_t htr3236_gamma_64(uint8_t index);

#endif /* HTR3236_H */