/**
 * @file device/adc.h
 * @brief 底层设备驱动与外设封装源文件
 * @note 本文件仅补充 Doxygen 文档注释，不改变代码逻辑。
 */

#ifndef _ADC_H
#define _ADC_H

#ifdef __cplusplus
extern "C" {
#endif

#include "config.h"

/**
 * @brief sampler 类或结构体
 */
class sampler {
  private:
	float vbus_samples[ADC_FILTER_SIZE];
	float currU_samples[ADC_FILTER_SIZE];
	float currV_samples[ADC_FILTER_SIZE];
	float currW_samples[ADC_FILTER_SIZE];
	float mcu_temp_samples[ADC_FILTER_SIZE];
	float drv_temp_samples[ADC_FILTER_SIZE];
	u8 current_sample_head;
	u8 temp_vbus_head;       // 环形缓冲区 head
	u8 mcu_temp_head;
	u8 drv_temp_head;

	float tempora_sample;
	float cached_mcu_temp;   // getter 缓存
	float cached_drv_temp;
	float cached_vbus;

  public:
	/**
	 * @brief 初始化对象或模块
	 * @return u8 返回值
	 */
	u8 init(void);
	/**
	 * @brief 三相电流零点配平并校验（hardware_init 在 FOC.init 之后调用）
	 * @return u8 0=成功；1=无采样帧（ADC/触发链路异常）；
	 *            2=配平值超过 CURRENT_ZERO_CAL_LIMIT（电流检测初始化错误）
	 */
	u8 zero_calibrate(void);
	/**
	 * @brief 更新 mcu_temp 相关状态
	 * @return void
	 */
	void update_mcu_temp(void);
	/**
	 * @brief 更新 drv_temp 相关状态
	 * @return void
	 */
	void update_drv_temp(void);
	/**
	 * @brief 更新 vbus_voltage 相关状态
	 * @return void
	 */
	void update_vbus_voltage(void);
	/**
	 * @brief 更新 current 相关状态
	 * @return void
	 */
	void update_current(void);

	/**
	 * @brief 获取 get_mcu_temp 对应的数据或状态
	 * @return float 返回值
	 */
	float get_mcu_temp(void);
	/**
	 * @brief 获取 get_drv_temp 对应的数据或状态
	 * @return float 返回值
	 */
	float get_drv_temp(void);
	/**
	 * @brief 获取 get_vbus_voltage 对应的数据或状态
	 * @return float 返回值
	 */
	float get_vbus_voltage(void);
	/**
	 * @brief 获取 get_current 对应的数据或状态
	 * @param[in] char 参数
	 * @return float 返回值
	 */
	float get_current(char);
};

/**
 * @brief ADC0_1_IRQHandler 中断处理函数
 * @return void
 */
void ADC0_1_IRQHandler(void);

/**
 * @brief ADC1 初始化：VBUS 连续转换模式（零等待读取）
 * @return void
 * @note ADC1 上电后即对 ch6(VBUS) 连续转换，软件触发一次后自持续，
 *       之后读取 DR 寄存器即可拿到最新完成的转换值（无需阻塞等待）。
 */
void adc1_config(void);

/**
 * @brief 零等待读取最新 VBUS 原始值（连续模式下任意时刻可调）
 * @return u16 最近一次完成转换的原始值（陈旧度约 1 个转换周期 ≈1.4μs）
 * @note 仅主循环任务上下文调用（与其他 ADC1 访问串行，无并发）。
 *       原理：读 DR 硬件清 EOC，随后下一次完成转换会刷新 DR，
 *       其间完成的转换被丢弃——每次读到的都是刚完成的样本。
 */
u16 adc1_read_vbus_latest(void);

/**
 * @brief ADC1 单次软件触发转换并等待完成（仅主循环任务上下文调用）
 * @param[in] channel ADC 通道号（如 ADC_CHANNEL_9）
 * @return u16 转换原始值
 * @note 会临时暂停 VBUS 连续模式、切到目标通道单次转换、再恢复连续，
 *       全程约 3~5μs，期间 VBUS 读数最多滞后该时长。drv 温度 1kHz 用。
 */
u16 adc1_read_raw(u8 channel);

#ifdef __cplusplus
}
#endif

#endif