/**
 * bldc_pid.h — 三环 PI/P 控制器接口
 *
 * 全部 Q15 定点数运算, 无浮点
 * 支持抗积分饱和 (Anti-windup)
 */

#ifndef BLDC_PID_H
#define BLDC_PID_H

#include "bldc_hw.h"

/* ==================== PI 控制器结构体 ==================== */
typedef struct {
    int16_t kp;             /* 比例系数 (Q15) */
    int16_t ki;             /* 积分系数 (Q15) */
    int16_t integral;       /* 积分累计值 (Q15) */
    int16_t integral_max;   /* 积分限幅 (Q15) */
    int16_t out_min;        /* 输出下限 (Q15) */
    int16_t out_max;        /* 输出上限 (Q15) */
} PiController;

/* ==================== 三环控制器实例声明 ==================== */
extern PiController g_pid_current;   /* 电流环 PI */
extern PiController g_pid_speed;     /* 速度环 PI */
extern int16_t      g_pid_pos_kp;    /* 位置环 P (无积分) */

/* ==================== 函数声明 ==================== */

/* 初始化所有 PID 参数 */
void PID_Init(void);

/* PI 控制器一步运算: y = Kp*e + Ki*∫e dt */
/* 返回 Q15 值, 自动限幅 + 抗积分饱和 */
int16_t PID_Update(PiController *pid, int16_t error_q15);

/* 电流环封装: 输入 I_ref/I_fb (Q15), 输出 PWM duty */
int16_t PID_CurrentRun(int16_t i_ref_q15, int16_t i_fb_q15);

/* 速度环封装: 输入 target/actual RPM (Q15), 输出 I_ref (Q15) */
int16_t PID_SpeedRun(int16_t target_rpm_q15, int16_t actual_rpm_q15);

/* 重置 PI 积分项 */
__STATIC_INLINE void PID_ResetIntegral(PiController *pid)
{
    pid->integral = 0;
}

/* 位置环 P 控制: speed_ref = Kp * pos_error */
__STATIC_INLINE int16_t PID_PositionP(int16_t pos_error_q15, int16_t kp_q15)
{
    return Q15_MUL(kp_q15, pos_error_q15);
}

#endif /* BLDC_PID_H */