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

dev_boost_special_functions.c
1 /*
2 * File: dev_boost_special_functions.c
3 * Author: M91406
4 *
5 * Created on December 3, 2020, 10:14 AM
6 */
7
8 #include <xc.h> // include processor files - each processor file is guarded.
9 #include <stdint.h> // include standard integer data types
10 #include <stdbool.h> // include standard boolean data types
11 #include <stddef.h> // include standard definition data types
12
13 #include "xc16_pral.h" // include peripheral register abstraction layer drivers
14 #include "dev_boost_typedef.h" // include boost converter type definitions
15 #include "dev_boost_special_functions.h" // include boost converter special function defiition
16
17 /***********************************************************************************
18 * @ingroup lib-layer-boost-specialfn-properties-data-types
19 * @struct CS_CALIBRATION_s
20 * @brief Current sense calibration data structure
21 **********************************************************************************/
22 struct CS_CALIBRATION_s
23 {
24 bool start;
25 bool stop;
26 volatile uint16_t counter;
27 volatile uint32_t buffer;
28 };
29 typedef struct CS_CALIBRATION_s CS_CALIBRATION_t;
30
31 /*********************************************************************************
32 * @ingroup lib-layer-boost-specialfn-properties-variables
33 * @var struct CS_CALIBRATION_s calib_cs[BOOST_MPHASE_COUNT]
34 * @brief Array of current sense calibration data objects of type CS_CALIBRATION_t
35 * @details
36 * The current sense feedback offset calibration requires a data space to
37 * accumulate and average the static feedback offset value. The final result
38 * is written to the feedback channel configuration of the boost converter data
39 * object, hence, the CS_CALIBRATION_s data structure used for the current
40 * sense feedback offset calibration is kept private and inaccessible from
41 * external firmware modules. This variable is declared as array reserving
42 * a data set for each current sense feedback channel.
43 **********************************************************************************/
44
45 volatile struct CS_CALIBRATION_s calib_cs[BOOST_MPHASE_COUNT];
46
47 /*********************************************************************************
48 * @ingroup lib-layer-boost-specialfn-properties-defines
49 * @def CS_CALIB_STEPS
50 * @brief Number of signal oversampling steps used to determine the calibration value
51 **********************************************************************************/
52 // Current Sense
53 #define CS_CALIB_STEPS 8
54
55
56 // Private function prototypes of sub-state function calls
57
58 volatile uint16_t CurrentSenseOffsetCalibration(volatile struct BOOST_CONVERTER_s *boostInstance);
59
60 /*******************************************************************************
61 * @var BoostConverterSpecialFunctions[](volatile struct BOOST_CONVERTER_s *boostInstance)
62 * @ingroup lib-layer-boost-specialfn-properties-variables
63 * @brief Function pointer list of all special function sub-state functions
64 * @details
65 * The function pointer list BoostConverterSpecialFunctions[] is providing public
66 * access to a list of functions serving special purposes supporting specific
67 * power converter configuration options. Each function mapped into this array
68 * as function pointer is a self-contained, independent sub-state, which can be
69 * called from any level of the main state machine being treated like a common
70 * sub-state.
71 *
72 * Each function needs to be called by handing over a parameter of type
73 *
74 * - struct BOOST_CONVERTER_s
75 *
76 * Each function returns of type unsigned integer:
77 *
78 * - 0 = BOOST_OPSRET_ERROR
79 * - 1 = BOOST_OPSRET_COMPLETE
80 * - 2 = BOOST_OPSRET_REPEAT
81 *
82 * <b>Recently available Special Functions<b><br>
83 *
84 * - Current Sense Feedback Offset Calibration
85 *
86 *********************************************************************************/
87
88 volatile uint16_t (*BoostConverterSpecialFunctions[])
89 (volatile struct BOOST_CONVERTER_s *boostInstance) =
90 {
91 CurrentSenseOffsetCalibration
92 };
93
94
95 /*********************************************************************************
96 * @fn volatile uint16_t drv_BoostConverter_SpecialFunctionExecute(volatile struct BOOST_CONVERTER_s * boostInstance, volatile enum BOOST_SPECIAL_FUNCTIONS_e specialFunction)
97 * @ingroup lib-layer-boost-specialfn-functions
98 * @brief This is the public function call access point to call dedicated special sub-functions
99 * @param boostInstance Pointer to a Boost Converter data object of type struct BOOST_CONVERTER_s
100 * @param specialFunction Special function selection list of type enum BOOST_SPECIAL_FUNCTIONS_e
101 * @return 0 = BOOST_OPSRET_ERROR
102 * @return 1 = BOOST_OPSRET_COMPLETE
103 * @return 2 = BOOST_OPSRET_REPEAT
104 *
105 * @details
106 * This function call is the public API function call to execute one of the
107 * special functions supported by this power converter device driver extension.
108 *
109 * <p><b>Example:</b></p>
110 * The following example initiates the automatic feedback sense offset calibration.
111 * Special Functions behave like all other state machine states and sub-states by
112 * returning the results ERROR, COMPLETE or REPEAT.
113 *
114 * - BOOST_OPSRET_ERROR
115 * An unexpected error occurred during execution of the Special Function routine,
116 * which prevents the state machine from continuing. If a ERROR is returned,
117 * it is recommended to reset the state machine and start all over.
118 *
119 * - BOOST_OPSRET_COMPLETE
120 * If the COMPLETE flag is returned, the Special Function has successfully completed
121 * and the state machine may move on.
122 *
123 * - BOOST_OPSRET_REPEAT
124 * If the REPEAT flag is returned, the function has to be called again until it returns
125 * the COMPLETE flag.
126 *
127 * @code{.c}
128 * retval = drv_BoostConverter_SpecialFunctionExecute(&boostConverter, CS_OFSET_CALIBRATION);
129 * @endcode
130 *
131 **********************************************************************************/
132
133 volatile uint16_t drv_BoostConverter_SpecialFunctionExecute(
134 volatile struct BOOST_CONVERTER_s * boostInstance,
135 volatile enum BOOST_SPECIAL_FUNCTIONS_e specialFunction
136 )
137 {
138 volatile uint16_t retval=0;
139
140 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
141 /* NULL POINTER PROTECTION */
142 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
143 // If no boost instance has been declared, leave here
144 if(boostInstance == NULL)
145 return(0);
146
147 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
148 /* CALL SPECIAL FUNCTION */
149 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
150 retval = BoostConverterSpecialFunctions[specialFunction](boostInstance);
151
152 return(retval);
153
154 }
155
156 /* *****************************************************************************
157 * PRIVATE FUNCTIONS
158 * ****************************************************************************/
159
160 /*******************************************************************************
161 * @fn uint16_t CurrentSenseOffsetCalibration(volatile struct BOOST_CONVERTER_s *boostInstance)
162 * @ingroup lib-layer-boost-specialfn-functions
163 * @brief Performs an offset calibration of the current sense feedback signal(s)
164 * @param boostInstance Pointer to a Boost Converter data object of type struct BOOST_CONVERTER_s
165 * @return unsigned integer (0=failure, 1=success)
166 *
167 * @details
168 * This function performs a current sense feedback channel zero-offset
169 * calibration. The calibration is executed when the reference voltage is
170 * applied to the current sense shunt amplifiers but the power supply is still
171 * turned off. The offset value is determined by a 4x oversampling of each of
172 * the feedback signals to eliminate high-frequency noise.
173 * Once the calibration is complete, the 'cs_calib_complete' status bit in
174 * the boost converter power controller object status word is set, allowing
175 * the state machine to run.
176 *********************************************************************************/
177
178 volatile uint16_t CurrentSenseOffsetCalibration(volatile struct BOOST_CONVERTER_s *boostInstance)
179 {
180 volatile uint16_t _i=0;
181 volatile bool _complete=true;
182 volatile enum BOOST_OPSTATE_RETURNS_e retval = BOOST_OPSRET_ERROR;
183
184 // if current sense calibration is disabled, return COMPLETE and leave
185 if(!boostInstance->status.bits.cs_calib_enable)
186 {
187 return((uint16_t)BOOST_OPSRET_COMPLETE); // Set return value to COMPLETE and leave function
188 }
189
190 // Protect against floored Current Calibration Procedure
191 if ((!boostInstance->status.bits.adc_active) ||
192 (!boostInstance->status.bits.pwm_active)
193 )
194 { return((uint16_t)BOOST_OPSRET_REPEAT); } // Return REPEAT
195
196
197 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198 // Perform Calibration Step
199
200 for(_i = 0; _i<boostInstance->set_values.no_of_phases; _i++)
201 {
202 // Reset Calibration Data Buffers if Calibration is rerun
203 if ((calib_cs[_i].start && calib_cs[_i].stop))
204 {
205 // Clear calibration data buffer
206 calib_cs[_i].buffer = 0; // Clear buffer
207 calib_cs[_i].counter = 0; // Clear counter
208 calib_cs[_i].start = false; // Clear START flag bit
209 calib_cs[_i].stop = false; // Clear STOP flag bit
210 }
211
212 // Collect data samples
213 if (calib_cs[_i].counter++ < CS_CALIB_STEPS)
214 {
215 calib_cs[_i].start = true; // Clear START flag bit
216 calib_cs[_i].stop = false; // Clear STOP flag bit
217 calib_cs[_i].buffer += boostInstance->data.i_sns[_i]; // Read ADC offset value
218 }
219 // Collection of data samples is complete
220 else
221 {
222 calib_cs[_i].buffer >>= 3; // Divide accumulated ADC samples (calculate average)
223 calib_cs[_i].stop = true; // Set STOP flag bit
224
225 // Write calibration data to boost converter data structure
226 boostInstance->i_loop[_i].feedback_offset = calib_cs[_i].buffer;
227
228 }
229
230 _complete &= calib_cs[_i].stop; // track STOP flag bits
231 }
232
233 // Return REPEAT until calibration is complete
234 if (_complete)
235 retval = (uint16_t)BOOST_OPSRET_COMPLETE; // Return COMPLETE
236 else
237 retval = (uint16_t)BOOST_OPSRET_REPEAT; // Return REPEAT
238
239 return(retval);
240
241 }
242
243 // end of file
BOOST_CONVERTER_STATUS_s::adc_active
volatile bool adc_active
Bit #1: indicating that ADC has been started and samples are taken.
Definition: dev_boost_typedef.h:210
BOOST_CONVERTER_SETTINGS_s::no_of_phases
volatile uint16_t no_of_phases
number of converter phases
Definition: dev_boost_typedef.h:351
BOOST_LOOP_SETTINGS_s::feedback_offset
volatile uint16_t feedback_offset
Feedback offset value for calibration or bi-direction feedback signals.
Definition: dev_boost_typedef.h:375
BOOST_CONVERTER_STATUS_s::pwm_active
volatile bool pwm_active
Bit #2: indicating that PWM has been started and ADC triggers are generated.
Definition: dev_boost_typedef.h:211
BOOST_CONVERTER_s::data
volatile struct BOOST_CONVERTER_DATA_s data
BOOST runtime data.
Definition: dev_boost_typedef.h:533
BOOST_CONVERTER_s::i_loop
volatile struct BOOST_LOOP_SETTINGS_s i_loop[BOOST_MPHASE_COUNT]
BOOST Current control loop objects.
Definition: dev_boost_typedef.h:540
BOOST_CONVERTER_DATA_s::i_sns
volatile uint16_t i_sns[BOOST_MPHASE_COUNT]
BOOST output current.
Definition: dev_boost_typedef.h:324
BOOST_CONVERTER_s::status
volatile struct BOOST_CONVERTER_STATUS_s status
BOOST operation status bits.
Definition: dev_boost_typedef.h:529
BOOST_CONVERTER_STATUS_s::cs_calib_enable
volatile bool cs_calib_enable
Bit #8: Flag bit indicating that current sensors need to calibrated.
Definition: dev_boost_typedef.h:218
BOOST_CONVERTER_s
BOOST control & monitoring data structure.
Definition: dev_boost_typedef.h:527
BOOST_CONVERTER_s::set_values
volatile struct BOOST_CONVERTER_SETTINGS_s set_values
Control field for global access to references.
Definition: dev_boost_typedef.h:532