/**
 * @file Algorithm/pid.h
 * @brief 算法模块源文件
 * @note 本文件仅补充 Doxygen 文档注释，不改变代码逻辑。
 */

#ifndef PID_H
#define PID_H

/**
 * @brief PIDController 类或结构体
 */
class PIDController {
  public:
	PIDController(float P, float I, float D, float ramp, float limit);
	~PIDController() = default;

	float operator()(float error);
	/**
	 * @brief 设置 set_PID 对应的参数或状态
	 * @param[in] P 参数
	 * @param[in] I 参数
	 * @param[in] D 参数
	 * @return void
	 */
	void set_PID(float P, float I, float D);
	/**
	 * @brief 设置 set_P 对应的参数或状态
	 * @param[in] pp 参数
	 * @return void
	 */
	void set_P(float pp);
	/**
	 * @brief 设置 set_limit 对应的参数或状态
	 * @param[in] limit 参数
	 * @return void
	 */
	void set_limit(float limit);
	/**
	 * @brief 复位对象内部状态
	 * @return void
	 */
	void reset();  // 重置PID控制器状态
	/**
	 * @brief reset_integral 函数
	 * @return void
	 */
	void reset_integral(); // 仅清除积分项，保留输出斜坡状态

	float P; //!< 比例增益(P环增益)
	float I; //!< 积分增益（I环增益）
	float D; //!< 微分增益（D环增益）
	float output_ramp;
	float limit;

  protected:
	float error_prev;			  //!< 最后的跟踪误差值
	float output_prev;			  //!< 最后一个 pid 输出值
	float integral_prev;		  //!< 最后一个积分分量值
	unsigned long timestamp_prev; //!< 上次执行时间戳
	float integral_separation_threshold;  //!< 积分分离阈值，用于抗积分饱和
};

#endif