#ifndef DEVICE_ADC_H
#define DEVICE_ADC_H

#include <stdint.h>

/**
 * @brief ADC 采样结果结构体。
 * @note 同时保存内部温度与内部参考电压的原始值及换算后的工程值。
 */
typedef struct {
    uint16_t temp_raw;   /**< @brief 内部温度通道原始 ADC 数值。 */
    uint16_t vref_raw;   /**< @brief 内部参考电压通道原始 ADC 数值。 */
    float vdda;          /**< @brief 根据内部参考电压换算得到的 MCU 供电电压，单位 V。 */
    float temperature;   /**< @brief 根据温度通道换算得到的芯片温度，单位 ℃。 */
} adc_sample_t;

/**
 * @brief 初始化 ADC 硬件及内部温度/VREF 通道。
 * @param[in] 无。
 * @param[out] 无。
 * @retval 无返回值。
 * @note 该函数完成 ADC 时钟、模式、校准以及内部通道使能。
 */
void adc_hw_init(void);

/**
 * @brief 执行指定通道的一次 ADC 单次采样。
 * @param[in] channel 待采样的 ADC 通道号。
 * @param[out] 无。
 * @retval uint16_t 指定通道的原始 ADC 采样值。
 * @note 函数内部会阻塞等待本次转换完成。
 */
uint16_t adc_single_read(uint8_t channel);

/**
 * @brief 读取内部参考电压通道的原始 ADC 值。
 * @param[in] 无。
 * @param[out] 无。
 * @retval uint16_t 内部参考电压通道的原始 ADC 值。
 */
uint16_t adc_read_vref_raw(void);

/**
 * @brief 读取内部温度通道的原始 ADC 值。
 * @param[in] 无。
 * @param[out] 无。
 * @retval uint16_t 内部温度通道的原始 ADC 值。
 */
uint16_t adc_read_temp_raw(void);

/**
 * @brief 根据内部参考电压原始值计算实际 VDDA。
 * @param[in] vref_raw 内部参考电压通道原始 ADC 数值。
 * @param[out] 无。
 * @retval float 换算得到的 VDDA 电压值，单位 V。
 * @note 当输入为 0 时返回默认 3.3V，避免除零异常。
 */
float adc_calculate_vdda(uint16_t vref_raw);

/**
 * @brief 根据温度原始值与 VDDA 计算芯片温度。
 * @param[in] temp_raw 内部温度通道原始 ADC 数值。
 * @param[in] vdda 当前供电电压，单位 V。
 * @param[out] 无。
 * @retval float 换算得到的芯片温度，单位 ℃。
 */
float adc_calculate_temperature(uint16_t temp_raw, float vdda);

/**
 * @brief 采集一组完整 ADC 样本并完成工程值换算。
 * @param[in] sample 指向输出样本结构体的指针；允许为空。
 * @param[out] sample 当指针非空时，写入温度/VREF 原始值与换算结果。
 * @retval 无返回值。
 * @note 当 sample 为 NULL 时函数直接返回，不执行写操作。
 */
void adc_collect_sample(adc_sample_t *sample);

#endif /* DEVICE_ADC_H */