This API is designed to work with the TWIST hardware, providing a set of functions to manage and control the output power.
Features
- Versatile Control Modes: The API supports both voltage and peak current control modes, allowing you to choose the best option for your specific application.
- Independent Leg Operation: Each of the two legs can operate independently with different topologies, such as boost or buck, offering greater flexibility in power management.
- Configure different paramaters for power electronics (dead time, phase shift)
- Simplified ADC value retrieval
- Refer to TWIST hardware specifications for more detail on TWIST board.
Initialization sequence
Note
1. Set the version of the board twist.setVersion(shield_TWIST_VERSION)
2. Choose the wished topology : buck, boost. You can select all the legs to be in the same topology or choose a specific configuration for each one twist.initAllBuck()
, twist.initAllBoost()
Optional steps
3. Set the adc decimation to divide the number of trigger event starting the adc conversion twist.setAllAdcDecim(decim)
4. Set the dead time twist.setAllDeadTime(rise_deadTime_ns, fall_deadTime_ns)
5. Set the phase shift in degree twist.setAllPhaseShift(ps_degree)
6. Enable the ADC acquisition for twist to get voltage and current measures data.enableTwistDefaultChannels()
7. Set the duty cycle to control output voltage twist.setAllDutyCycle(duty_cycle)
8. Then start the converters twist.startAll()
1. Set the version of the board twist.setVersion(shield_TWIST_VERSION)
2. Choose the wished topology : buck, boost twist.initLegBuck(LEG1/LEG2)
, twist.initLegBoost(LEG1/LEG2)
Optional steps
3. Set the adc decimation to divide the number of trigger event starting the adc conversion twist.setLegAdcDecim(LEG1/LEG2, decim)
4. Set the dead time twist.setLegDeadTime(LEG1/LEG2,rise_deadTime_ns, fall_deadTime_ns)
5. Set the phase shift in degree twist.setLegPhaseShift(LEG1/LEG2, ps_degree)
6. Enable the ADC acquisition for twist to get voltage and current measures data.enableTwistDefaultChannels()
7. Set the duty cycle to control output voltage twist.setLegDutyCycle(LEG1/LEG2, duty_cycle)
8. Then start the converters twist.startLeg(LEG1/LEG2)
1. Set the version of the board twist.setVersion(shield_TWIST_VERSION)
2. Choose the wished topology : buck, boost. You can select all the legs to be in the same topology or choose a specific configuration for each one twist.initAllBuck(CURRENT_MODE)
, twist.initAllBoost()
Optional steps
3. Set the adc decimation to divide the number of trigger event starting the adc conversion twist.setAllAdcDecim(decim)
4. Set the dead time twist.setAllDeadTime(rise_deadTime_ns, fall_deadTime_ns)
5. Set the phase shift in degree twist.setAllPhaseShift(ps_degree)
6. Enable the ADC acquisition for twist to get voltage and current measures data.enableTwistDefaultChannels()
7. Set the slope compensation to control the output currenttwist.setAllSlopeCompensation(1.4, 1.0)
8. Then start the converters twist.startAll()
Warning
Only buck topology is supported for current mode control currently.
Example
Voltage mode and Current mode
There is two different way to control the power delivered by TWIST : voltage and current mode.
Voltage mode
Voltage mode is a traditional and widely-used approach in power electronics, where the output voltage is regulated by controlling the duty cycle. The duty cycle is a crucial parameter that determines the proportion of time a switch (such as a transistor) is active during a complete switching period. By adjusting the duty cycle, you can effectively manage the power delivered to a load.
A higher duty cycle indicates that the switch remains on for a more extended period, resulting in increased power delivery to the load. Conversely, a lower duty cycle means the switch is on for a shorter duration, thereby reducing the power supplied. Consequently, the average power and voltage applied to the load can be precisely controlled by fine-tuning the duty cycle.
Current mode
In peak current mode control, we monitors the current flowing through the power switch. Once the current reaches a predetermined peak value, we promptly turns off the power switch. This mechanism helps maintain a constant output voltage by regulating the current flow.
In this setup, a clock signal determines the switching frequency and triggers the switch to close. The controller then sends a reference peak current value. When the inductor's current reaches this reference value, the switch opens.
However, using a constant peak current reference can lead to subharmonic oscillations. To prevent this issue, we employ a technique called slope compensation. Instead of a constant value, the peak current reference is a sawtooth waveform. The final schematic with slope compensation is shown below:
The sawtooth signal Slope compensation
is generated with the function twist.setAllSlopeCompensation
or twist.setLegSlopeCompensation
. These functions set the slope compensation based on the input parameters. for example twist.setAllSlopeCompensation(1.4, 1.0)
generates a sawtooth signal ranging from 1.4V to 1.0V. You can create a sawtooth signal between 2.048V and 0V as well.
This sawtooth signal is then compared with the ADC's current value. When selecting the sawtooth parameters, it's essential to consider the conversion of current to voltage.
On the TWIST board, a voltage value of 1.024V on the ADC corresponds to a current of 0A. The system has a gain of 100mV per ampere, meaning that for each ampere increase in current, the voltage value increases by 100 millivolts.
Snippets examples
Buck topology
2 legs with the same configuration
2 independant leg operations
twist.initLegBuck(LEG1);
twist.initLegBuck(LEG2);
twist.setLegDutyCycle(LEG1, 0.3);
twist.setLegDutyCycle(LEG2, 0.5);
twist.startAll();
Boost topology
Inverter topology
Example
Check the following examples for an application :
- Voltage mode buck
- Current mode buck
- Voltage mode boost
Class TwistAPI
Public Functions
Type | Name |
---|---|
void | initAllBoost () Initialise all the legs for boost topology, current mode is not supported for boost. |
void | initAllBuck (hrtim_pwm_mode_t leg_mode=VOLTAGE_MODE) Initialise all the legs for buck topology. |
void | initAllMode (hrtim_switch_convention_t leg_convention, hrtim_pwm_mode_t leg_mode) Initialize power modes for all legs. |
void | initLegBoost (leg_t leg) Initialise all the legs for boost topology, current mode is not supported for boost. |
void | initLegBuck (leg_t leg, hrtim_pwm_mode_t leg_mode=VOLTAGE_MODE) Initialise a leg for buck topology. |
void | initLegMode (leg_t leg, hrtim_switch_convention_t leg_convention, hrtim_pwm_mode_t leg_mode) Initialize the power mode for a given leg. |
void | setAllAdcDecim (uint16_t adc_decim) set ADC decimator for all legs |
void | setAllDeadTime (uint16_t ns_rising_dt, uint16_t ns_falling_dt) set the dead time value for all legs |
void | setAllDutyCycle (float32_t duty_all) Set the duty cycle for power control of all the legs. |
void | setAllPhaseShift (int16_t phase_shift) Set the phase shift value for all the legs. |
void | setAllSlopeCompensation (float32_t set_voltage, float32_t reset_voltage) Set the slope compensation in current mode for all the leg. |
void | setAllTriggerValue (float32_t trigger_value) Set the trigger value for the ADC trigger of all the legs. |
void | setLegAdcDecim (leg_t leg, uint16_t adc_decim) set ADC decimator for a leg |
void | setLegDeadTime (leg_t leg, uint16_t ns_rising_dt, uint16_t ns_falling_dt) set the dead time value for a leg |
void | setLegDutyCycle (leg_t leg, float32_t duty_leg) Set the duty cycle for a specific leg's power control. |
void | setLegPhaseShift (leg_t leg, int16_t phase_shift) Set the phase shift value for a specific leg's power control. |
void | setLegSlopeCompensation (leg_t leg, float32_t set_voltage, float32_t reset_voltage) Set the slope compensation in current mode for a leg. |
void | setLegTriggerValue (leg_t leg, float32_t trigger_value) Set the trigger value for a specific leg's ADC trigger. |
void | setVersion (twist_version_t twist_ver) Set the hardware version of the board. |
void | startAll () Start power output for all legs. |
void | startLeg (leg_t leg) Start power output for a specific leg. |
void | stopAll () Stop power output for all legs. |
void | stopLeg (leg_t leg) Stop power output for a specific leg. |
Public Functions Documentation
function initAllBoost
function initAllBuck
Initialise all the legs for buck topology.
Parameters:
leg_mode
PWM mode - VOLTAGE_MODE or CURRENT_MODE
function initAllMode
Initialize power modes for all legs.
This function initializes the power modes for each leg with the specified 'buck' and 'voltage_mode' settings.
Parameters:
leg_convention
PWM Switch to be driven by the duty cycle. The other will be complementary - PWMx1 or PWMx2leg_mode
PWM mode - VOLTAGE_MODE or CURRENT_MODE
function initLegBoost
Initialise all the legs for boost topology, current mode is not supported for boost.
Parameters:
leg
Leg to initialize
function initLegBuck
Initialise a leg for buck topology.
Parameters:
leg
Leg to initializeleg_mode
PWM mode - VOLTAGE_MODE or CURRENT_MODE
function initLegMode
Initialize the power mode for a given leg.
void TwistAPI::initLegMode (
leg_t leg,
hrtim_switch_convention_t leg_convention,
hrtim_pwm_mode_t leg_mode
)
This function configures modulation, frequency, phase shift, dead time, and other parameters for power control of a specified leg.
Parameters:
leg
The leg to initializeleg_convention
PWM Switch to be driven by the duty cycle. The other will be complementary - PWMx1 or PWMx2leg_mode
PWM mode - VOLTAGE_MODE or CURRENT_MODE
function setAllAdcDecim
set ADC decimator for all legs
this function sets the number of event which will be ignored between two events. ie. you divide the number of trigger in a fixed period. For example if adc_decim = 1, nothing changes but with adc_decims = 2 you have twice less adc trigger.
Parameters:
adc_decim
- adc decimator, a number between 1 and 32
function setAllDeadTime
set the dead time value for all legs
Parameters:
ns_rising_dt
- rising dead time value in nsns_falling_dt
- falling dead time value in ns
function setAllDutyCycle
Set the duty cycle for power control of all the legs.
This function sets the same duty cycle for power control of all the legs. The duty cycle determines the ON/OFF ratio of the power signal for all legs.
Parameters:
duty_all
The duty cycle value to set (a floating-point number between 0.1 and 0.9).
function setAllPhaseShift
Set the phase shift value for all the legs.
Parameters:
phase_shift
The phase shift value to set.
function setAllSlopeCompensation
Set the slope compensation in current mode for all the leg.
Parameters:
set_voltage
in volt, the DAC peak voltage for slope compensation (value between 0 and 2.048)reset_voltage
in volt, the DAC lowest voltage for slope compensation (value between 0 and 2.048)
Warning:
Be sure that set_voltage > reset_voltage
function setAllTriggerValue
Set the trigger value for the ADC trigger of all the legs.
This function sets the same trigger value for the ADC trigger of all the legs. The trigger value determines the level at which the ADC trigger is activated for all legs.
Parameters:
trigger_value
The trigger value to set for all the legs between 0.0 and 1.0.
function setLegAdcDecim
set ADC decimator for a leg
this function sets the number of event which will be ignored between two events. ie. you divide the number of trigger in a fixed period. For example if adc_decim = 1, nothing changes but with adc_decims = 2 you have twice less adc trigger.
Parameters:
leg
- leg for which to set adc decimator valueadc_decim
- adc decimator, a number between 1 and 32
function setLegDeadTime
set the dead time value for a leg
Parameters:
leg
- the leg for which to set dead time valuens_rising_dt
- rising dead time value in nsns_falling_dt
- falling dead time value in ns
function setLegDutyCycle
Set the duty cycle for a specific leg's power control.
This function sets the duty cycle for the power control of a specified leg. The duty cycle determines the ON/OFF ratio of the power signal for the leg.
Parameters:
leg
The leg for which to set the duty cycle.duty_leg
The duty cycle value to set (a floating-point number between 0.1 and 0.9).
function setLegPhaseShift
Set the phase shift value for a specific leg's power control.
Parameters:
leg
The leg for which to set the phase shift value.phase_shift
The phase shift value to set.
function setLegSlopeCompensation
Set the slope compensation in current mode for a leg.
void TwistAPI::setLegSlopeCompensation (
leg_t leg,
float32_t set_voltage,
float32_t reset_voltage
)
Parameters:
leg
The leg to initializeset_voltage
in volt, the DAC peak voltage for slope compensation (value between 0 and 2.048)reset_voltage
in volt, the DAC lowest voltage for slope compensation (value between 0 and 2.048)
Warning:
Be sure that set_voltage > reset_voltage
function setLegTriggerValue
Set the trigger value for a specific leg's ADC trigger.
This function sets the trigger value for the ADC trigger of a specified leg. The trigger value determines the level at which the ADC trigger is activated.
Parameters:
leg
The leg for which to set the ADC trigger value.trigger_value
The trigger value to set between 0.05 and 0.95.
function setVersion
Set the hardware version of the board.
Parameters:
shield
shield version - shield_TWIST_V1_2, shield_TWIST_V1_3, shield_ownverter or shield_other
Warning:
You need to call this function BEFORE initializing a leg, after that it is not possible to change the shield version
function startAll
function startLeg
Start power output for a specific leg.
This function initiates the power output for a specified leg by starting the PWM subunits associated with the leg's output pins. If the leg's output pins are not declared inactive in the device tree, the corresponding subunits are started. eg. If output1 is declared inactive in the device tree, PWMA1 will not start
Parameters:
leg
The leg for which to start the power output.
function stopAll
function stopLeg
Stop power output for a specific leg.
Parameters:
leg
The leg for which to stop the power output.
The documentation for this class was generated from the following file docs/core/zephyr/modules/owntech_power_api/zephyr/public_api/TwistAPI.h