This API is designed to work with the TWIST hardware, providing a set of functions to manage and control the output power.

Features

TWIST schema
- 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

Voltage mode with all the legsVoltage mode with only LEG1Current mode with all the legs

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 with all the legsVoltage mode with only LEG1Current mode with all the legs

twist.setVersion(shield_TWIST_V1_3);
twist.initAllBuck();
twist.setAllAdcDecim(1);
twist.setAllDeadTime(200,200);
twist.setAllPhaseShift(180);
data.enableTwistDefaultChannels();
twist.setAllDutyCycle(0.5);
twist.startAll();

twist.setVersion(shield_TWIST_V1_3);
twist.initLegBuck(LEG1);
twist.setLegAdcDecim(LEG1, 1);
twist.setLegDeadTime(LEG1, 200,200);
twist.setLegPhaseShift(LEG1, 180);
data.enableTwistDefaultChannels();
twist.setLegDutyCycle(LEG1, 0.5);
twist.startLeg(LEG1);

twist.setVersion(shield_TWIST_V1_3);
twist.initAllBuck(CURRENT_MODE);
twist.setAllAdcDecim(1);
twist.setAllDeadTime(200,200);
twist.setAllPhaseShift(180);
data.enableTwistDefaultChannels();
twist.setAllSlopeCompensation(1.4, 1.0);
twist.startAll();

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.

Voltage mode PWM schematic Voltage mode PWM waveform

voltage mode PWM

voltage mode PWM waveform

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.

Current mode schematic Current mode waveform

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:

Final current mode schematic Final current mode waveform

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

Connection Schematic

    twist.initAllBuck();
    twist.setAllDutyCycle(0.5);
    twist.startAll();

2 independant leg operations

Connection Schematic

    twist.initLegBuck(LEG1);
    twist.initLegBuck(LEG2);
    twist.setLegDutyCycle(LEG1, 0.3);
    twist.setLegDutyCycle(LEG2, 0.5);
    twist.startAll();

Boost topology

Connection Schematic

    twist.initAllBoost();
    twist.setAllDutyCycle(0.5);
    twist.startAll();

Inverter topology

Connection Schematic

    twist.initLegBuck(LEG1);
    twist.initLegBoost(LEG2);
    twist.setAllDutyCycle(0.5);
    twist.startAll();

Example

Check the following examples for an application :
- Voltage mode buck
- Current mode buck
- Voltage mode boost

Class TwistAPI

ClassList > 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

void TwistAPI::initAllBoost ()

function initAllBuck

Initialise all the legs for buck topology.

void TwistAPI::initAllBuck (
    hrtim_pwm_mode_t leg_mode=VOLTAGE_MODE
)

Parameters:

leg_mode PWM mode - VOLTAGE_MODE or CURRENT_MODE

function initAllMode

Initialize power modes for all legs.

void TwistAPI::initAllMode (
    hrtim_switch_convention_t leg_convention,
    hrtim_pwm_mode_t leg_mode
)

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 PWMx2
leg_mode PWM mode - VOLTAGE_MODE or CURRENT_MODE

function initLegBoost

Initialise all the legs for boost topology, current mode is not supported for boost.

void TwistAPI::initLegBoost (
    leg_t leg
)

Parameters:

leg Leg to initialize

function initLegBuck

Initialise a leg for buck topology.

void TwistAPI::initLegBuck (
    leg_t leg,
    hrtim_pwm_mode_t leg_mode=VOLTAGE_MODE
)

Parameters:

leg Leg to initialize
leg_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 initialize
leg_convention PWM Switch to be driven by the duty cycle. The other will be complementary - PWMx1 or PWMx2
leg_mode PWM mode - VOLTAGE_MODE or CURRENT_MODE

function setAllAdcDecim

set ADC decimator for all legs

void TwistAPI::setAllAdcDecim (
    uint16_t adc_decim
)

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

void TwistAPI::setAllDeadTime (
    uint16_t ns_rising_dt,
    uint16_t ns_falling_dt
)

Parameters:

ns_rising_dt - rising dead time value in ns
ns_falling_dt - falling dead time value in ns

function setAllDutyCycle

Set the duty cycle for power control of all the legs.

void TwistAPI::setAllDutyCycle (
    float32_t duty_all
)

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.

void TwistAPI::setAllPhaseShift (
    int16_t phase_shift
)

Parameters:

phase_shift The phase shift value to set.

function setAllSlopeCompensation

Set the slope compensation in current mode for all the leg.

void TwistAPI::setAllSlopeCompensation (
    float32_t set_voltage,
    float32_t reset_voltage
)

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.

void TwistAPI::setAllTriggerValue (
    float32_t trigger_value
)

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

void TwistAPI::setLegAdcDecim (
    leg_t leg,
    uint16_t adc_decim
)

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 value
adc_decim - adc decimator, a number between 1 and 32

function setLegDeadTime

set the dead time value for a leg

void TwistAPI::setLegDeadTime (
    leg_t leg,
    uint16_t ns_rising_dt,
    uint16_t ns_falling_dt
)

Parameters:

leg - the leg for which to set dead time value
ns_rising_dt - rising dead time value in ns
ns_falling_dt - falling dead time value in ns

function setLegDutyCycle

Set the duty cycle for a specific leg's power control.

void TwistAPI::setLegDutyCycle (
    leg_t leg,
    float32_t duty_leg
)

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.

void TwistAPI::setLegPhaseShift (
    leg_t leg,
    int16_t phase_shift
)

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 initialize
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 setLegTriggerValue

Set the trigger value for a specific leg's ADC trigger.

void TwistAPI::setLegTriggerValue (
    leg_t leg,
    float32_t trigger_value
)

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.

void TwistAPI::setVersion (
    twist_version_t twist_ver
)

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

void TwistAPI::startAll ()

function startLeg

Start power output for a specific leg.

void TwistAPI::startLeg (
    leg_t 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

void TwistAPI::stopAll ()

function stopLeg

Stop power output for a specific leg.

void TwistAPI::stopLeg (
    leg_t 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