npnz16b.h

/* *********************************************************************************
 * PowerSmart™ Digital Control Library Designer, Version 0.9.14.676
 * *********************************************************************************
 * Generic library header for z-domain compensation filter assembly functions
 * CGS Version: 3.0.8
 * CGS Date:    03/12/2021
 * ********************************************************************************/
// This is a guard condition so that contents of this file are not included
// more than once.
#ifndef __SPECIAL_FUNCTION_LAYER_LIB_NPNZ16B_H__
#define __SPECIAL_FUNCTION_LAYER_LIB_NPNZ16B_H__

#include <xc.h>                                   // include processor files - each processor file is guarded
#include <dsp.h>                                  // include DSP data types (e.g. fractional)
#include <stdint.h>                               // include standard integer number data types
#include <stddef.h>                               // include standard definition data types
#include <stdbool.h>                              // include standard boolean data types (true/false)

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-macros
 * @def   __PSDCLD_VERSION
 * @brief Generic macro allowing to identify the file version of 'npnz16b.h'
 *
 * @details
 * This version key represents the product version of PS-DCLD as integer number
 * of the form [MAJOR][MINOR][REVISION] => version 0.9.3.xxx would be shown as 903.
 * User code can check if the file version is compliant with the proprietary user
 * code by using pre-compiler directives such as
 *
 * @code{.c}
 * #if (__PSDCLD_VERSION > 908)
 *  #pragma message "This code has not been tested with the recently included version of npnz16b.h"
 * #endif
 * @endcode
 *
 ***************************************************************************************************/

#ifndef __PSDCLD_VERSION
    #define __PSDCLD_VERSION    914
#endif

/***************************************************************************************************
 * @enum    NPNZ_STATUS_FLAGS_e
 * @brief   Common Controller Status and Control Flag Bits
 * @details
 * The 16-bit wide NPNZ_STATUS_s data object holds status and control bits for
 * monitoring and control of the NPNZ16b_s controller during runtime. The lower 8 bit
 * of the status word are used for status indication while the upper 8 bit are used
 * by control bits.
 * For enhanced programming convenience, definitions of status and control flags are
 * provided in single bit and full word format. All available flags are consolidated
 * in the npnzFlagList object.
 ***************************************************************************************************/

enum NPNZ_STATUS_FLAGS_e
{
    NPNZ_STATUS_CLEAR            = 0b0000000000000000,
    NPNZ_STATUS_SATUATION_MSK    = 0b0000000000000011,
    NPNZ_STATUS_LSAT_ACTIVE      = 0b0000000000000001,
    NPNZ_STATUS_LSAT_CLEAR       = 0b0000000000000000,
    NPNZ_STATUS_USAT_ACTIVE      = 0b0000000000000010,
    NPNZ_STATUS_USAT_CLEAR       = 0b0000000000000000,
    NPNZ_STATUS_AGC_DISABLE      = 0b0000000000000000,
    NPNZ_STATUS_AGC_ENABLED      = 0b0000100000000000,
    NPNZ_STATUS_TARGET_DEFAULT   = 0b0000000000000000,
    NPNZ_STATUS_TARGET_SWAPED    = 0b0001000000000000,
    NPNZ_STATUS_SOURCE_DEFAULT   = 0b0000000000000000,
    NPNZ_STATUS_SOURCE_SWAPED    = 0b0010000000000000,
    NPNZ_STATUS_INV_INPUT_OFF    = 0b0000000000000000,
    NPNZ_STATUS_INV_INPUT_ON     = 0b0100000000000000,
    NPNZ_STATUS_ENABLE_OFF       = 0b0000000000000000,
    NPNZ_STATUS_ENABLE_ON        = 0b1000000000000000
};                                                
typedef enum NPNZ_STATUS_FLAGS_e NPNZ_STATUS_FLAGS_t; 

/***************************************************************************************************
 * @enum    NPNZ_STATUS_SATURATION_e
 * @brief   Enumeration of control loop saturation status bits
 **************************************************************************************************/
enum NPNZ_STATUS_SATURATION_e{
    NPNZ_SAT_CLEAR  = 0b0,                        
    NPNZ_SAT_ACTIVE = 0b1                         
};                                                
typedef enum NPNZ_STATUS_SATURATION_e NPNZ_STATUS_SATURATION_t; 
extern volatile enum NPNZ_STATUS_SATURATION_e npnzEnumControlStatusSaturation; 

/* Control flags (bit-field) */
/***************************************************************************************************
 * @enum    NPNZ_STATUS_AGC_ENABLE_e
 * @brief   Enumeration of Adaptive Gain Modulation enable/disable control bits
 **************************************************************************************************/
enum NPNZ_STATUS_AGC_ENABLE_e{
    NPNZ_AGC_DISABLED = 0b0,                      
    NPNZ_AGC_ENABLED  = 0b1                       
};                                                
typedef enum NPNZ_STATUS_AGC_ENABLE_e NPNZ_STATUS_AGC_ENABLE_t; 
extern volatile enum NPNZ_STATUS_AGC_ENABLE_e npnzEnumControlAgcEnable; 

/***************************************************************************************************
 * @enum    NPNZ_STATUS_SOURCE_SWAP_e
 * @brief   Enumeration of control input port swap control bits
 **************************************************************************************************/
enum NPNZ_STATUS_SOURCE_SWAP_e{
    NPNZ_SOURCE_DEFAULT = 0b0,                    
    NPNZ_SOURCE_SWAPED  = 0b1                     
};                                                
typedef enum NPNZ_STATUS_SOURCE_SWAP_e NPNZ_STATUS_SOURCE_SWAP_t; 
extern volatile enum NPNZ_STATUS_SOURCE_SWAP_e npnzEnumControlSourceSwap; 

/***************************************************************************************************
 * @enum    NPNZ_STATUS_TARGET_SWAP_e
 * @brief   Enumeration of control output port swap control bits
 **************************************************************************************************/
enum NPNZ_STATUS_TARGET_SWAP_e{
    NPNZ_TARGET_DEFAULT = 0b0,                    
    NPNZ_TARGET_SWAPED  = 0b1                     
};                                                
typedef enum NPNZ_STATUS_TARGET_SWAP_e NPNZ_STATUS_TARGET_SWAP_t; 
extern volatile enum NPNZ_STATUS_TARGET_SWAP_e npnzEnumControlTargetSwap; 

/***************************************************************************************************
 * @enum    NPNZ_STATUS_INPUT_INV_e
 * @brief   Enumeration of input value inversion control bits
 **************************************************************************************************/
enum NPNZ_STATUS_INPUT_INV_e{
    NPNZ_INPUT_DEFAULT  = 0b0,                    
    NPNZ_INPUT_INVERTED = 0b1                     
};                                                
typedef enum NPNZ_STATUS_INPUT_INV_e NPNZ_STATUS_INPUT_INV_t; 
extern volatile enum NPNZ_STATUS_INPUT_INV_e npnzEnumControlInputInversion; 

/***************************************************************************************************
 * @enum    NPNZ_STATUS_ENABLE_e
 * @brief   Enumeration of control loop enable/disable control bits
 **************************************************************************************************/
enum NPNZ_STATUS_ENABLE_e{
    NPNZ_DISABLED = 0b0,                          
    NPNZ_ENABLED  = 0b1                           
};                                                
typedef enum NPNZ_STATUS_ENABLE_e NPNZ_STATUS_ENABLE_t; 
extern volatile enum NPNZ_STATUS_ENABLE_e npnzEnumControlEnable; 

/****************************************************************************************************
 * @struct  NPNZ_FLAGS_s
 * @brief   Structure providing all public enumerated lists of constants
 **************************************************************************************************** */
struct NPNZ_FLAGS_s
{
    volatile enum NPNZ_STATUS_FLAGS_e       StatusWordFlags; 
    volatile enum NPNZ_STATUS_SATURATION_e  flagSaturation; 
    volatile enum NPNZ_STATUS_AGC_ENABLE_e  flagAgcControl; 
    volatile enum NPNZ_STATUS_SOURCE_SWAP_e flagSourceSwap; 
    volatile enum NPNZ_STATUS_TARGET_SWAP_e flagTargetSwap; 
    volatile enum NPNZ_STATUS_INPUT_INV_e   flagCtrlInputInversion; 
    volatile enum NPNZ_STATUS_ENABLE_e      flagControlEnable; 
};                                                
typedef struct NPNZ_FLAGS_s NPNZ_FLAGS_t;         
extern volatile struct NPNZ_FLAGS_s npnzFlagList; 

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_STATUS_s
 * @brief   NPNZ16b controller object status and control word
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ16b_s status word is providing status flag bits for monitoring and controlling the
 * NPNZ16b control library code execution from outside the library module.
 *
 * 1) Status Byte
 * The low byte of the NPNZ16b_s status word is used for READ ONLY status flags, set and cleared
 * automatically by the control loop library routine.
 *
 * 2) Control Byte
 * The high byte of the status word is used for control flags, through which users can control
 * the control loop execution. This includes enabling/disabling the control loop execution,
 * switch between different input and output sources, invert input values or enable/disable
 * advanced functions.
 *
 ***************************************************************************************************/

/* Controller status data structure */
struct NPNZ_STATUS_s {
    union {
    struct {
        volatile bool lower_saturation_event : 1; 
        volatile bool upper_saturation_event : 1; 
        volatile unsigned : 1;                    
        volatile unsigned : 1;                    
        volatile unsigned : 1;                    
        volatile unsigned : 1;                    
        volatile unsigned : 1;                    
        volatile unsigned : 1;                    

        volatile unsigned : 1;                    
        volatile unsigned : 1;                    
        volatile unsigned : 1;                    
        volatile bool agc_enabled: 1;             
        volatile bool swap_target: 1;             
        volatile bool swap_source: 1;             
        volatile bool invert_input: 1;            
        volatile bool enabled : 1;                
    } __attribute__((packed))bits;                
    volatile uint16_t value;                      
    };
} __attribute__((packed));                        
typedef struct NPNZ_STATUS_s NPNZ_STATUS_t;       

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_PORT_s
 * @brief   Data Input/Output Port declaration of memory addresses, signal offsets and normalization settings
 * @extends NPNZ_PORTS_s
 *
 * @details
 * The NPNZ_PORT_s data object defines the basic parameters required to read data from or write
 * data to user-defined memory addresses as well as offers data fields for additional settings
 * such as normalization scaling factors or signal offsets, which can be used to compensate analog
 * offsets and normalize raw ADC data to other ADC input values and their respective physical
 * struct NPNZ_PORT_t declares its individual source/target memory address, normalization
 * quantity.
 *
 ***************************************************************************************************/

/* Controller Input/Output Port */
struct NPNZ_PORT_s{

    volatile uint16_t* ptrAddress;                
    volatile int16_t   NormScaler;                
    volatile fractional NormFactor;               
    volatile int16_t   Offset;                    

} __attribute__((packed));                        
typedef struct NPNZ_PORT_s NPNZ_PORT_t;           

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_PORTS_s
 * @brief   Filter Coefficient Arrays, Number Format Handling and Input/Output History Parameters
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_PORTS_t data object holds a list of nested NPNZ_PORT_t data objects, each
 * defining an individual controller input or output port. The NPNZ16b_s data objects defines
 * up to two input and two output ports of type struct NPNZ_PORT_t and one additional
 * pointer to an external, user-defined 16-bit reference source variable. Each port of type
 * struct NPNZ_PORT_t declares its individual source/target memory address, normalization
 * scaler and offset:
 *
 *  - Primary Source:   common feedback input object
 *  - Alternate Source: additional, alternate feedback input object (optional)
 *  - Primary Target:   common control output target object
 *  - Alternate Target: additional, alternate control output target object (optional)
 *  - Control Reference: pointer to external 16-bit reference source variable
 *
 ***************************************************************************************************/

/* List of Controller Input/Output Ports */
struct NPNZ_PORTS_s{

    volatile struct NPNZ_PORT_s Source;           
    volatile struct NPNZ_PORT_s AltSource;        
    volatile struct NPNZ_PORT_s Target;           
    volatile struct NPNZ_PORT_s AltTarget;        
    volatile uint16_t* ptrControlReference;       

} __attribute__((packed));                        
typedef struct NPNZ_PORTS_s NPNZ_PORTS_t;         

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_FILTER_PARAMS_s
 * @brief   Filter Coefficient Arrays, Number Format Handling and Input/Output History Parameters
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_FILTER_PARAMS_t data object holds all configuration parameters of the compensation
 * filter. These parameters include pointers to external arrays of filter coefficients, error
 * and control history as well as number format normalization parameters like pre- and post-
 * scalers.
 *
 ***************************************************************************************************/

struct NPNZ_FILTER_PARAMS_s{

    volatile int32_t* ptrACoefficients;           
    volatile int32_t* ptrBCoefficients;           
    volatile fractional* ptrControlHistory;       
    volatile fractional* ptrErrorHistory;         

    // Array size information
    volatile uint16_t ACoefficientsArraySize;     
    volatile uint16_t BCoefficientsArraySize;     
    volatile uint16_t ControlHistoryArraySize;    
    volatile uint16_t ErrorHistoryArraySize;      

    // Feedback scaling Input/Output Normalization
    volatile int16_t normPreShift;                
    volatile int16_t normPostShiftA;              
    volatile int16_t normPostShiftB;              
    volatile int16_t normPostScaler;              

    // P-Term Coefficients (for plant measurements only)
    volatile int16_t PTermScaler;                 
    volatile int16_t PTermFactor;                 

} __attribute__((packed));                        
typedef struct NPNZ_FILTER_PARAMS_s NPNZ_FILTER_PARAMS_t; 

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_LIMITS_s
 * @brief   System Anti-Windup (Output Clamping) Thresholds
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_LIMITS_t data object holds all parameters required to automatically clamp the
 * most recent control output to user-defined thresholds. This data type allows the
 * definition of individual minimum and maximum output values for the NPNZ controller primary
 * and alternate output port.
 *
 * This feature is optional and needs to be enabled, configured and managed manually in
 * user code.
 *
 ***************************************************************************************************/

struct NPNZ_LIMITS_s{

    volatile int16_t MinOutput;                   
    volatile int16_t MaxOutput;                   
    volatile int16_t AltMinOutput;                
    volatile int16_t AltMaxOutput;                

} __attribute__((packed));                        
typedef struct NPNZ_LIMITS_s  NPNZ_LIMITS_t;      

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_ADC_TRGCTRL_s
 * @brief   Automated ADC Trigger handling
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_ADC_TRGCTRL_t data object holds all parameters required to automatically position
 * ADC triggers based on the most recent control output. This feature is used in voltage or
 * average current mode control to automatically track average values in triangular feedback
 * signal waveforms.
 *
 * This feature is optional and needs to be enabled, configured and managed manually in
 * user code.
 *
 ***************************************************************************************************/

struct NPNZ_ADC_TRGCTRL_s{

    volatile uint16_t* ptrADCTriggerARegister;    
    volatile uint16_t ADCTriggerAOffset;          
    volatile uint16_t* ptrADCTriggerBRegister;    
    volatile uint16_t ADCTriggerBOffset;          

} __attribute__((packed));                        
typedef struct NPNZ_ADC_TRGCTRL_s NPNZ_ADC_TRGCTRL_t; 

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_DATA_PROVIDERS_s
 * @brief   Data Provider Target Memory Addresses
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_DATA_PROVIDERS_t data object holds pointers to external, user-defined, global
 * variables allowing the NPNZ controller to push internal data to external, user-defined,
 * global variables during the execution of the NPNZ controller, resulting in an automated
 * updated of user-code variable values during runtime.
 *
 * This feature is optional and needs to be enabled, configured and managed manually in
 * user code.
 *
 ***************************************************************************************************/

struct NPNZ_DATA_PROVIDERS_s{

    volatile uint16_t* ptrDProvControlInput;      
    volatile uint16_t* ptrDProvControlInputCompensated; 
    volatile uint16_t* ptrDProvControlError;      
    volatile uint16_t* ptrDProvControlOutput;     

} __attribute__((packed));                        
typedef struct NPNZ_DATA_PROVIDERS_s NPNZ_DATA_PROVIDERS_t; 

/**************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_EXTENSION_HOOKS_s
 * @brief   User Extension Function Call Parameters
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_EXTENSION_HOOKS_s data object holds all parameters required to call user-defined extension
 * functions supporting advanced use cases, which are not covered by the standard functions provided.
 * When enabled, the NPNZ controller can automatically call user-defined functions at specific points
 * within the control loop execution flow. Each function pointer is supporting function calls with one
 * additional, 16-bit wide function parameter for each extension call. These parameters can either be
 * variables or pointers to variables including start addresses of user defined data structures.
 *
 * Each extension function call is optional and needs to be enabled, configured and managed manually
 * in user code.
 *
 ***************************************************************************************************/

struct NPNZ_EXTENSION_HOOKS_s{

    volatile uint16_t ptrExtHookStartFunction;    
    volatile uint16_t ExtHookStartFunctionParam;  

    volatile uint16_t ptrExtHookSourceFunction;   
    volatile uint16_t ExtHookSourceFunctionParam; 

    volatile uint16_t ptrExtHookPreAntiWindupFunction; 
    volatile uint16_t ExtHookPreAntiWindupFunctionParam; 

    volatile uint16_t ptrExtHookPreTargetWriteFunction; 
    volatile uint16_t ExtHookPreTargetWriteFunctionParam; 

    volatile uint16_t ptrExtHookEndOfLoopFunction; 
    volatile uint16_t ExtHookEndOfLoopFunctionParam; 

    volatile uint16_t ptrExtHookExitFunction;     
    volatile uint16_t ExtHookExitFunctionParam;   

} __attribute__((packed));                        
typedef struct NPNZ_EXTENSION_HOOKS_s NPNZ_EXTENSION_HOOKS_t; 

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_GAIN_CONTROL_s
 * @brief   Adaptive Gain Control Modulation Parameters
 * @extends NPNZ16b_s
 *
 * @details
 * The NPNZ_GAIN_CONTROL_t data object holds all parameters required to perform real-time
 * gain modulation of the z-domain feedback loop. The loop gain is modulated by multiplying
 * the result of the NPNZ controller B-term with an additional scaling factor. This scaling
 * factor is represented by a fast floating point number, consisting of a factional factor
 * <AgcFactor> between -1 and 1 and an integer bit-shift scaler <AgcScaler>.
 *
 * This feature is optional and needs to be enabled, configured and managed manually in
 * user code.
 *
 ***************************************************************************************************/

struct NPNZ_GAIN_CONTROL_s{

    volatile uint16_t AgcScaler;                  
    volatile fractional AgcFactor;                
    volatile fractional AgcMedian;                
    volatile uint16_t ptrAgcObserverFunction;     

} __attribute__((packed));                        
typedef struct NPNZ_GAIN_CONTROL_s NPNZ_GAIN_CONTROL_t; 

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-object-members
 * @struct  NPNZ_USER_DATA_BUFFER_s
 * @brief   User Data Space for Advanced Control Functions
 * @extends NPNZ16b_s

 * @details
 * The NPNZ_USER_DATA_BUFFER_t data object reserves four word of additional data space for
 * user parameters. These parameters may be handled by user code and are not assigned to any
 * specific, pre-defined functions.
 *
 ***************************************************************************************************/

struct NPNZ_USER_DATA_BUFFER_s{

    volatile uint16_t usrParam0;                  
    volatile uint16_t usrParam1;                  
    volatile uint16_t usrParam2;                  
    volatile uint16_t usrParam3;                  
    volatile uint16_t usrParam4;                  
    volatile uint16_t usrParam5;                  
    volatile uint16_t usrParam6;                  
    volatile uint16_t usrParam7;                  

} __attribute__((packed));                        
typedef struct NPNZ_USER_DATA_BUFFER_s NPNZ_USER_DATA_BUFFER_t; 

/***************************************************************************************************
 * @ingroup special-function-layer-npnz16-data-objects
 * @struct  NPNZ16b_s
 * @brief   Global NPNZ controller data object
 *
 * @details
 * The NPNZ16b_s data object holds all configuration, status, control and monitoring values
 * of a z-domain lead-lag compensator based controller. All data types of this data object,
 * including floating, are scaled to a 16 bit number space, optimized for code execution on
 * Microchip dsPIC33 family of devices. Please refer to the description of nested data
 * structures above for more information about nested data objects.
 *
 ***************************************************************************************************/

struct NPNZ16b_s {

    volatile struct NPNZ_STATUS_s status;         
    volatile struct NPNZ_PORTS_s Ports;           
    volatile struct NPNZ_FILTER_PARAMS_s Filter;  
    volatile struct NPNZ_GAIN_CONTROL_s GainControl; 
    volatile struct NPNZ_LIMITS_s Limits;         
    volatile struct NPNZ_ADC_TRGCTRL_s ADCTriggerControl; 
    volatile struct NPNZ_DATA_PROVIDERS_s DataProviders; 
    volatile struct NPNZ_EXTENSION_HOOKS_s ExtensionHooks; 
    volatile struct NPNZ_USER_DATA_BUFFER_s Advanced; 

} __attribute__((packed)) ;                       
typedef struct NPNZ16b_s NPNZ16b_t;               

/* ********************************************************************************/

#endif                                            // end of __SPECIAL_FUNCTION_LAYER_LIB_NPNZ16B_H__ header file section


//**********************************************************************************
// Download latest version of this tool here: https://areiter128.github.io/DCLD
//**********************************************************************************