Modbus-rtu/PLSR/Inc/plsr_profile.h

#ifndef PLSR_PROFILE_H
#define PLSR_PROFILE_H

#include "plsr_types.h"
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Q32.32 定点：32 位整数部分 + 32 位小数部分。
 * 频率与脉冲计数全部用定点，禁止在刷新中断中使用浮点。 */
#define PLSR_PROFILE_Q32_ONE         (UINT64_C(1) << 32U)

/* 曲线模式与 S2 参数块中的编码一致。 */
#define PLSR_PROFILE_CURVE_LINEAR    (0U)
#define PLSR_PROFILE_CURVE_S         (1U)
#define PLSR_PROFILE_CURVE_SINE      (2U)

/* 单段速度规划请求。 */
typedef struct
{
    uint32_t targetFrequencyHz;     /* 本段目标频率 */
    uint32_t startFrequencyHz;      /* 本段起始频率（后续模式衔接用） */
    uint32_t stopFrequencyHz;       /* 本段终止频率（完成模式一般为 0） */
    uint32_t maxFrequencyHz;        /* 最高速度限幅 */
    uint32_t accelSlopeHzPerMs;     /* 加速斜率 Hz/ms */
    uint32_t decelSlopeHzPerMs;     /* 减速斜率 Hz/ms */
    uint8_t curveMode;              /* 0直线 1S形 2正弦 */
} PLSR_PROFILE_REQUEST;

/* 规划结果（时间轴概览，诊断/测试用）。 */
typedef struct
{
    uint32_t accelTimeMs;
    uint32_t cruiseTimeMs;
    uint32_t decelTimeMs;
    uint32_t totalTimeMs;
    uint32_t peakFrequencyHz;
    int64_t totalPulses;
    uint8_t triangular;
} PLSR_PROFILE_PLAN;

typedef enum
{
    PLSR_PROFILE_PHASE_ACCEL = 0,
    PLSR_PROFILE_PHASE_CRUISE,
    PLSR_PROFILE_PHASE_DECEL,
    PLSR_PROFILE_PHASE_DONE
} PLSR_PROFILE_PHASE;

/* 执行状态：由 PlsrProfileStart 初始化，PlsrProfileStep 每刷新周期推进。 */
typedef struct
{
    uint32_t refreshHz;             /* 刷新率：1000=1ms，10000=0.1ms */
    PLSR_PROFILE_PHASE phase;
    uint32_t targetFrequencyHz;
    uint32_t startFrequencyHz;
    uint32_t stopFrequencyHz;
    uint32_t decelTargetHz;         /* 当前减速目标（降频时先到新目标） */
    uint32_t accelSlopeHzPerMs;
    uint32_t decelSlopeHzPerMs;
    uint8_t curveMode;
    uint64_t frequencyQ32;          /* 当前瞬时频率 Q32.32 */
    uint64_t emittedPulsesQ32;      /* 已发脉冲 Q32.32 */
    int64_t totalPulses;            /* 目标总脉冲 */
    uint64_t deltaPerStepQ32;       /* 每步频率增量 Q32.32（直线=常数） */
    uint64_t jerkPerStepQ32;        /* 每步增量变化率 Q32.32（S形用） */
    uint32_t curveStep;             /* 曲线相位计数（S形/正弦） */
    uint32_t curveStepLimit;        /* 曲线相位上限 */
    uint8_t sPhase;                 /* S形增量 0=升 1=降 */
    uint8_t started;
} PLSR_PROFILE_STATE;

PLSR_RESULT PlsrProfilePlan(const PLSR_PROFILE_REQUEST *request,
                            int64_t pulses,
                            PLSR_PROFILE_PLAN *plan);

PLSR_RESULT PlsrProfileStart(PLSR_PROFILE_STATE *state,
                             const PLSR_PROFILE_REQUEST *request,
                             int64_t pulses,
                             uint32_t refreshHz);

/* 每刷新周期推进一步。返回当前应输出频率（Hz，四舍五入）与完成标志。 */
PLSR_RESULT PlsrProfileStep(PLSR_PROFILE_STATE *state,
                            uint32_t *frequencyHz,
                            uint8_t *completed);

/* 运行中动态调频：按斜率平滑过渡到新目标频率。 */
PLSR_RESULT PlsrProfileRetarget(PLSR_PROFILE_STATE *state,
                                uint32_t newTargetFrequencyHz);

/* 从当前频率按既定减速斜率降到0，用于缓停、限位和暂停。 */
PLSR_RESULT PlsrProfileRequestStop(PLSR_PROFILE_STATE *state);

/* 虚拟发射计数校准到硬件实际计数（消除 ARPE 预装载滞后的累积偏差，
 * 保证 DONE 判定与硬件同步，段尾不再以冻结频率补发剩余脉冲）。 */
void PlsrProfileSyncPulses(PLSR_PROFILE_STATE *state, uint64_t hwPulses);

/* 线性加速起步时，按一个脉冲内的频率积分计算首周期等效频率。
 * 避免低起始频率的超长首周期吞掉整段加速过程。 */
uint32_t PlsrProfileGetInitialOutputFrequency(
    const PLSR_PROFILE_STATE *state);

/* 按距离终点的剩余脉冲数计算线性减速脉冲的等效频率。
 * 返回值已限制在终止频率与目标频率之间。 */
uint32_t PlsrProfileGetBrakingOutputFrequency(
    const PLSR_PROFILE_STATE *state,
    uint64_t pulsesRemaining);

#ifdef __cplusplus
}
#endif

#endif /* PLSR_PROFILE_H */