dcl_pi.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2023-2025 Texas Instruments Incorporated
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *    Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 *    Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the
 *    distribution.
 *
 *    Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */ 
#ifndef _DCL_PI_H_
#define _DCL_PI_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "../dcl_common.h"
 
//--- Linear PI controller ---------------------------------------------------
 
typedef struct dcl_pi_sps
{
    float32_t Kp;       
    float32_t Ki;       
    float32_t Umax;     
    float32_t Umin;     
    float32_t Imax;     
    float32_t Imin;     
} DCL_PI_SPS;
 
#define PI_SPS_DEFAULTS { 1.0f, 0.0f, 1.0f, -1.0f, 1.0f, -1.0f }
 
typedef _DCL_VOLATILE struct dcl_pi
{
    /* controller parameter */
    float32_t Kp;       
    float32_t Ki;       
    float32_t Umax;     
    float32_t Umin;     
    float32_t Imax;     
    float32_t Imin;     
 
    /* internal storage */ 
    float32_t i6;       
    float32_t i10;      
    float32_t i11;      
    
    /* miscellaneous */
    DCL_PI_SPS *sps;    
    DCL_CSS *css;       
} DCL_PI;
 
#define PI_DEFAULTS { 1.0f, 0.0f, 1.0f, -1.0f, 1.0f, -1.0f, 1.0f, 0.0f, 0.0f, \
                    &(DCL_PI_SPS)PI_SPS_DEFAULTS, &(DCL_CSS)DCL_CSS_DEFAULTS }
 
#define PI_INT_DEFAULTS .i6=1.0f, .i10=0.0f, .i11=0.0f, \
.sps=&(DCL_PI_SPS)PI_SPS_DEFAULTS, .css=&(DCL_CSS)DCL_CSS_DEFAULTS           
 
#define DCL_initPI() &(DCL_PI)PI_DEFAULTS
 
#define DCL_initPIasParam(kp,ki,umax,umin) &(DCL_PI){ .Kp=kp, .Ki=ki, \
                                .Umax=umax, .Umin=umin, PI_INT_DEFAULTS }
 
#define DCL_initPIasSPS(pi_ptr,sps_ptr)                                                    \
({                                                                                         \
    DCL_PI* new_pi = (pi_ptr) ? pi_ptr : DCL_initPI();                                     \
    DCL_PI_SPS* new_sps = (sps_ptr) ? sps_ptr : &(DCL_PI_SPS)PI_SPS_DEFAULTS;              \
    if(sps_ptr)                                                                            \
    {                                                                                      \
        *new_pi = (DCL_PI){ (new_sps)->Kp, (new_sps)->Ki, (new_sps)->Umax, (new_sps)->Umin,\
        (new_sps)->Imax, (new_sps)->Imin, 1.0f, 0.0f, 0.0f,                                \
        (DCL_PI_SPS*)new_sps, &(DCL_CSS)DCL_CSS_DEFAULTS };                                \
    }                                                                                      \
    new_pi;                                                                                \
})
 
_DCL_CODE_ACCESS
void DCL_resetPI(DCL_PI *pi)
{
    dcl_interrupt_t ints;
    
    ints = DCL_disableInts();
    pi->i6 = 1.0f;
    pi->i10 = pi->i11 = 0.0f;
    DCL_restoreInts(ints);
}
 
_DCL_CODE_ACCESS
void DCL_forceUpdatePI(DCL_PI *pi)
{
 
#ifdef DCL_ERROR_HANDLING_ENABLED
    uint32_t err_code = dcl_none;
    err_code |= (pi->sps->Umax <= pi->sps->Umin) ? dcl_param_invalid_err : dcl_none;
    err_code |= (pi->css->T <= 0.0f) ? dcl_param_range_err : dcl_none;
    err_code |= (pi->sps->Kp < 0.0f) ? dcl_param_range_err : dcl_none;
    err_code |= (pi->sps->Ki < 0.0f) ? dcl_param_range_err : dcl_none;
    if (err_code)
    {
        DCL_setError(pi,err_code);
        DCL_getErrorInfo(pi);
        DCL_runErrorHandler(pi);
    }
#endif
 
    pi->Kp = pi->sps->Kp;
    pi->Ki = pi->sps->Ki;
    pi->Umax = pi->sps->Umax;
    pi->Umin = pi->sps->Umin;
    pi->Imax = pi->sps->Imax;
    pi->Imin = pi->sps->Imin;
}
 
_DCL_CODE_ACCESS
void DCL_updatePINoCheck(DCL_PI *pi)
{
    dcl_interrupt_t ints;
 
    ints = DCL_disableInts();
    DCL_forceUpdatePI(pi);
    DCL_restoreInts(ints);
}
 
_DCL_CODE_ACCESS
bool DCL_updatePI(DCL_PI *pi)
{
    if (DCL_getUpdateStatus(pi))
    {
        DCL_updatePINoCheck(pi);
        DCL_clearUpdateStatus(pi);
        return true;
    }
    return false;
}
 
_DCL_CODE_ACCESS
void DCL_loadSeriesPIasZPK(DCL_PI *pi, DCL_ZPK3 *zpk) 
{
#ifdef DCL_ERROR_HANDLING_ENABLED
    uint32_t err_code = dcl_none;
    err_code |= (zpk->K < 0.0f) ? dcl_param_range_err : dcl_none;
    err_code |= (crealf(zpk->z1) > (1.0f / (2.0f * pi->css->T))) ? dcl_param_warn_err : dcl_none;
    if (err_code)
    {
        DCL_setError(pi,err_code);
        DCL_getErrorInfo(pi);
        DCL_runErrorHandler(pi);
    }
#endif
 
    float32_t T = pi->css->T;
    float32_t z1 = (float32_t) crealf(zpk->z1);
    pi->sps->Kp = zpk->K * (1.0f + (T * z1) / 2.0f);
    pi->sps->Ki = (-2.0f * T * z1) / (2.0f + (T * z1));
 
}
 
_DCL_CODE_ACCESS
void DCL_loadParallelPIasZPK(DCL_PI *pi, DCL_ZPK3 *zpk)
{
#ifdef DCL_ERROR_HANDLING_ENABLED
    uint32_t err_code = dcl_none;
    err_code |= (zpk->K < 0.0f) ? dcl_param_range_err : dcl_none;
    err_code |= (crealf(zpk->z1) > (1.0f / (2.0f * pi->css->T))) ? dcl_param_warn_err : dcl_none;
    if (err_code)
    {
        DCL_setError(pi,err_code);
        DCL_getErrorInfo(pi);
        DCL_runErrorHandler(pi);
    }
#endif
    
    float32_t T = pi->css->T;
    float32_t z1 = (float32_t) crealf(zpk->z1);
    pi->sps->Kp = zpk->K * (1.0f + (T * z1) / 2.0f);
    pi->sps->Ki = -zpk->K * T * z1;
}
 
_DCL_CRIT_ACCESS
float32_t DCL_runPISeries(DCL_PI *pi, float32_t rk, float32_t yk)
{
    float32_t v2, v4, v5, v9;
 
    v2 = pi->Kp * (rk - yk);
    v4 = pi->i10 + (pi->Ki * pi->i6 * v2);
    v5 = v2 + v4;
    v9 = DCL_runSat(v5, pi->Umax, pi->Umin);
    pi->i6 = (v5 == v9) ? 1.0f : 0.0f;
    pi->i10 = v4;  
 
#ifdef DCL_TESTPOINTS_ENABLED
    pi->css->tpt = v5;
#endif
 
    return(v9);
}
 
_DCL_CRIT_ACCESS
float32_t DCL_runPIParallel(DCL_PI *pi, float32_t rk, float32_t yk)
{
    float32_t v1, v2, v4, v5, v9;
 
    v1 = rk - yk;
    v2 = pi->Kp * v1;
    v4 = (v1 * pi->Ki * pi->i6) + pi->i10;
    pi->i10 = v4;
    v5 = v2 + v4;
    v9 = DCL_runSat(v5, pi->Umax, pi->Umin);
    pi->i6 = (v5 == v9) ? 1.0f : 0.0f;
 
#ifdef DCL_TESTPOINTS_ENABLED
    pi->css->tpt = v5;
#endif
 
    return(v9);
}
 
_DCL_CRIT_ACCESS
float32_t DCL_runPIParallelEnhanced(DCL_PI *pi, float32_t rk, float32_t yk)
{
    float32_t v1, v5, v7, v8;
    bool l11, l14, l17, l18, l19;
 
    v1 = rk - yk;
    v5 = (v1 * pi->Ki * pi->i6) + pi->i10;
    pi->i10 = v5;
    v7 = (v1 * pi->Kp) + v5;
    v8 = DCL_runSat(v7, pi->Umax, pi->Umin);
    l17 = (v7 == v8) ? true : false;
    l11 = (DCL_runSat(v5, pi->Imax, pi->Imin) == v5) ? true : false;
    l19 = (v5 > 0) ? true : false;
    l14 = (v1 > 0) ? true : false;
    l18 = l17 && (!l11 || (l19 ^ l14));
    pi->i6 = (l18) ? 1.0f : 0.0f;
 
#ifdef DCL_TESTPOINTS_ENABLED
    pi->css->tpt = v7;
#endif
 
    return(v8);
}
 
_DCL_CRIT_ACCESS
float32_t DCL_runPISeriesTustin(DCL_PI *pi, float32_t rk, float32_t yk)
{
    float32_t v2, v4, v5, v8, v9;
 
    v2 = (rk - yk) * pi->Kp;
    v8 = v2 * pi->Ki * pi->i6;
    v4 = v8 + pi->i11 + pi->i10;
    v5 = v2 + v4;
    pi->i10 = v4;
    pi->i11 = v8;
    v9 = DCL_runSat(v5, pi->Umax, pi->Umin);
    pi->i6 = (v5 == v9) ? 1.0f : 0.0f;
 
#ifdef DCL_TESTPOINTS_ENABLED
    pi->css->tpt = v4;
#endif
 
    return(v9);
}
 
#ifdef __cplusplus
}
#endif // extern "C"
 
#endif // _DCL_PI_H_