| Digital Power Starter Kit 3 Firmware dsPIC33C Boost Converter Voltage Mode Control Example |

v_loop.h
1 /* *********************************************************************************
2 * PowerSmart™ Digital Control Library Designer, Version 0.9.14.676
3 * *********************************************************************************
4 * 3p3z controller function declarations and compensation filter coefficients
5 * derived for following operating conditions:
6 * *********************************************************************************
7 *
8 * Controller Type: 3P3Z - Basic Voltage Mode Compensator
9 * Sampling Frequency: 500000 Hz
10 * Fixed Point Format: Q15
11 * Scaling Mode: 4 - Fast Floating Point Coefficient Scaling
12 * Input Gain: 0.12531328320802
13 *
14 * *********************************************************************************
15 * CGS Version: 3.0.8
16 * CGS Date: 03/12/2021
17 * *********************************************************************************
18 * User: M91406
19 * Date/Time: 04/01/2021 23:47:39
20 * ********************************************************************************/
21
22 // This is a guard condition so that contents of this file are not included
23 // more than once.
24 #ifndef __SPECIAL_FUNCTION_LAYER_V_LOOP_H__
25 #define __SPECIAL_FUNCTION_LAYER_V_LOOP_H__
26
27 #include <xc.h> // include processor files - each processor file is guarded
28 #include <dsp.h> // include DSP data types (e.g. fractional)
29 #include <stdint.h> // include standard integer number data types
30 #include <stdbool.h> // include standard boolean data types (true/false)
31
32 #include "npnz16b.h" // include NPNZ library header file
33
34 /* *******************************************************************************
35 * Data Arrays:
36 * The NPNZ16b_s data structure contains pointers to coefficient, control and error
37 * history arrays. The pointer target objects (variables and arrays) are defined
38 * in controller source file v_loop.c
39 *
40 * Type definitions for A- and B- coefficient arrays as well as error- and control
41 * history arrays are aligned in memory using the 'packed' attribute for optimized
42 * addressing during DSP computations. These aligned data structures need to be
43 * placed in specific memory locations to allow direct X/Y-access from the DSP.
44 * This X/Y-memory placement is covered by the declarations used in controller
45 * source file v_loop.c
46 * ******************************************************************************/
47
48 /*********************************************************************************
49 * @ingroup special-function-layer-npnz16-data-objects
50 * @struct V_LOOP_CONTROL_LOOP_COEFFICIENTS_s
51 * @brief Data structure packing A- and B- coefficient arrays in a linear memory space for optimized DSP code execution
52 ********************************************************************************/
53 struct V_LOOP_CONTROL_LOOP_COEFFICIENTS_s
54 {
55 volatile int32_t ACoefficients[3]; // A-Coefficients
56 volatile int32_t BCoefficients[4]; // B-Coefficients
57 } __attribute__((packed)); // Data structure packing A- and B- coefficient arrays in a linear memory space for optimized DSP code execution
58 typedef struct V_LOOP_CONTROL_LOOP_COEFFICIENTS_s V_LOOP_CONTROL_LOOP_COEFFICIENTS_t;
59
60 /*********************************************************************************
61 * @ingroup special-function-layer-npnz16-data-objects
62 * @struct V_LOOP_CONTROL_LOOP_HISTORIES_s
63 * @brief Data structure packing A- and B- coefficient arrays in a linear memory space for optimized DSP code execution
64 ********************************************************************************/
65 struct V_LOOP_CONTROL_LOOP_HISTORIES_s
66 {
67 volatile fractional ControlHistory[3]; // Control History Array
68 volatile fractional ErrorHistory[4]; // Error History Array
69 } __attribute__((packed)); // Data structure packing control and error histories arrays in a linear memory space for optimized DSP code execution
70 typedef struct V_LOOP_CONTROL_LOOP_HISTORIES_s V_LOOP_CONTROL_LOOP_HISTORIES_t; // Data type of data structure packing control and error histories arrays
71
72 /*********************************************************************************
73 * @ingroup special-function-layer-npnz16-variables
74 * @var v_loop_pterm_factor
75 * @brief Q15 fractional of the P-Term Coefficient for Plant Measurements
76 ********************************************************************************/
77 extern volatile int16_t v_loop_pterm_factor; // Q15 fractional of the P-Term factor
78
79 /*********************************************************************************
80 * @ingroup special-function-layer-npnz16-variables
81 * @var v_loop_pterm_scaler
82 * @brief Bit-shift scaler of the P-Term Coefficient for Plant Measurements
83 ********************************************************************************/
84 extern volatile int16_t v_loop_pterm_scaler; // Bit-shift scaler of the P-Term factor
85
86
87 /*********************************************************************************
88 * @ingroup special-function-layer-npnz16-objects
89 * @var v_loop
90 * @brief External reference to user-defined NPNZ16b controller data object 'v_loop'
91 ********************************************************************************/
92 extern volatile struct NPNZ16b_s v_loop; // user-controller data object
93
94
95 /* *******************************************************************************
96 * Function call prototypes for initialization routines and control loop handling
97 * ******************************************************************************/
98
99 /*********************************************************************************
100 * @fn volatile uint16_t v_loop_Initialize(volatile struct NPNZ16b_s* controller)
101 * @ingroup special-function-layer-npnz16-functions
102 * @brief Initializes controller coefficient arrays and normalization factors
103 * @param controller: Pointer to NPNZ Controller Data Object of type struct NPNZ16b_s
104 *
105 * @details
106 * This function needs to be called from user code at startup once to initialize
107 * coefficient arrays and number normalization settings of the v_loop controller
108 * object.
109 *
110 * @attention
111 * This routine DOES NOT initialize the complete controller object.
112 * User-defined settings such as pointers to the control reference, source and
113 * target registers, output minima and maxima and further, design-dependent
114 * settings, need to be specified in user code.
115 ********************************************************************************/
116 extern volatile uint16_t v_loop_Initialize( // v_loop initialization function call
117 volatile struct NPNZ16b_s* controller // Pointer to NPNZ16b data object
118 );
119
120 /*********************************************************************************
121 * @fn void v_loop_Reset(volatile struct NPNZ16b_s* controller)
122 * @ingroup special-function-layer-npnz16-functions
123 * @brief Prototype of the Assembly routine '_v_loop_Reset' clearing the NPNZ16b controller output and error histories
124 * @param controller: Pointer to NPNZ16b data object of type struct NPNZ16b_s*
125 *
126 * @details
127 * This Assembly function clears the NPNZ16b controller output and
128 * error histories by settings all elements of the delay lines to zero. This
129 * resets the controller to its default state. This function should be called
130 * every time before the control loop is started from a disabled, unbiased output.
131 * @note
132 * Use function 'v_loop_Precharge' to start the feedback loop controller when
133 * the output is pre-biased.
134 ********************************************************************************/
135 extern void v_loop_Reset( // v_loop reset function call (Assembly)
136 volatile struct NPNZ16b_s* controller // Pointer to NPNZ16b data object
137 );
138
139 /*********************************************************************************
140 * @fn void v_loop_Precharge(volatile struct NPNZ16b_s* controller, volatile fractional ctrl_input, volatile fractional ctrl_output)
141 * @ingroup special-function-layer-npnz16-functions
142 * @brief Prototype of the Assembly routine '_v_loop_Precharge' loading user-defined values into the NPNZ16b controller output and error histories
143 * @param controller: Pointer to NPNZ16b data object of type struct NPNZ16b_s*
144 * @param ctrl_input: user-defined, constant error history value of type fractional
145 * @param ctrl_output: user-defined, constant control output history value of type fractional
146 *
147 * @details
148 * This function loads user-defined values into NPNZ16b controller
149 * output and error histories where the parameters ctrl_input and ctrl_output
150 * will written to the entire delay line of the filter emulating a pre-existing
151 * steady state operation under the user defined conditions.
152 ********************************************************************************/
153 extern void v_loop_Precharge( // v_loop history pre-charge function call (Assembly)
154 volatile struct NPNZ16b_s* controller, // Pointer to NPNZ16b data object
155 volatile fractional ctrl_input, // user-defined, constant error history value
156 volatile fractional ctrl_output // user-defined, constant control output history value
157 );
158
159 /*********************************************************************************
160 * @fn void v_loop_Update(volatile struct NPNZ16b_s* controller)
161 * @ingroup special-function-layer-npnz16-functions
162 * @brief Prototype of the Assembly feedback control loop routine helping to call the v_loop controller from C-code
163 * @param controller: Pointer to NPNZ16b data object of type struct NPNZ16b_s*
164 *
165 * @details
166 * This function is the main controller function which must be called at
167 * the control frequency from the control interrupt service routine. It
168 * calculates the most recent control error and processes it in the compensation
169 * filter computation after which the new result is written to the control
170 * output target.
171 * Runtime control is provided through the NPNZ16b data object status & control word.
172 * @note
173 * Available control options depend on the controller feature configuration.
174 * Please refer to the user guide for more detailed information.
175 ********************************************************************************/
176 extern void v_loop_Update( // Calls the 3P3Z controller (Assembly)
177 volatile struct NPNZ16b_s* controller // Pointer to NPNZ16b data object
178 );
179
180 /*********************************************************************************
181 * @fn void v_loop_PTermUpdate(volatile struct NPNZ16b_s* controller)
182 * @ingroup special-function-layer-npnz16-functions
183 * @brief Prototype of the alternate Assembly P-Term control loop helping to call the v_loop P-Term controller from C-code
184 * @param controller: Pointer to NPNZ16b data object of type struct NPNZ16b_s*
185 *
186 * @details
187 * This function has been added as extension function supporting the development
188 * process, introducing an alternative control loop able to replace the conventional
189 * compensation feedback loop with a simple P-Term controller, allowing users to
190 * perform measurements of the plant transfer function.
191 * To use this function, users may replace the default compensation feedback loop
192 * function call v_loop_Update by v_loop_PTermUpdate to perform the measurement.
193 *
194 * This additional controller seamlessly fits into the controller data
195 * interface by using the same NPNZ16b_s data structure and does not need
196 * additional configuration or initialization.
197 *
198 * @attention
199 * THIS CONTROLLER IS USED FOR MEASUREMENTS OF THE PLANT TRANSFER FUNCTION ONLY.
200 * THIS LOOP IS BY DEFAULT UNSTABLE AND ONLY WORKS UNDER STABLE TEST CONDITIONS.
201 * DO NOT USE THIS CONTROLLER TYPE FOR NORMAL OPERATION
202 ********************************************************************************/
203 extern void v_loop_PTermUpdate( // Calls the P-Term controller (Assembly)
204 volatile struct NPNZ16b_s* controller // Pointer to NPNZ16b data object
205 );
206
207 #endif // end of __SPECIAL_FUNCTION_LAYER_V_LOOP_H__
208
209
210 //**********************************************************************************
211 // Download latest version of this tool here: https://areiter128.github.io/DCLD
212 //**********************************************************************************
213
V_LOOP_CONTROL_LOOP_COEFFICIENTS_s::ACoefficients
volatile int32_t ACoefficients[3]
Definition: v_loop.h:55
V_LOOP_CONTROL_LOOP_HISTORIES_s::ControlHistory
volatile fractional ControlHistory[3]
Definition: v_loop.h:67
V_LOOP_CONTROL_LOOP_COEFFICIENTS_s::BCoefficients
volatile int32_t BCoefficients[4]
Definition: v_loop.h:56
NPNZ16b_s
Definition: npnz16b.h:502
V_LOOP_CONTROL_LOOP_HISTORIES_s::ErrorHistory
volatile fractional ErrorHistory[4]
Definition: v_loop.h:68
V_LOOP_CONTROL_LOOP_HISTORIES_s
Definition: v_loop.h:65
V_LOOP_CONTROL_LOOP_COEFFICIENTS_s
Definition: v_loop.h:53