Skip to content

This API is designed to work with Spin shields hardware, providing a set of functions to manage and control the shields.

To work with Shield API, include the following file in your code:

Note

#include <ShieldAPI.h>

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

1. 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 shield.power.initBuck(ALL), shield.power.initBoost(ALL)

Optional steps 2. Set the adc decimation to divide the number of trigger event starting the adc conversion shield.power.setAdcDecim(ALL, decim) 3. Set the dead time shield.power.setDeadTime(ALL, rise_deadTime_ns, fall_deadTime_ns) 4. Set the phase shift in degree shield.power.setPhaseShift(ALL, ps_degree)

5. Enable the ADC acquisition for twist to get voltage and current measures shield.sensors.enableDefaultTwistSensors() 6. Set the duty cycle to control output voltage shield.power.setDutyCycle(ALL, duty_cycle) 7. Then start the converters shield.power.start(ALL)

1. Choose the wished topology : buck, boost shield.power.initBuck(LEG1/LEG2), shield.power.initBoost(LEG1/LEG2)

Optional steps 2. Set the adc decimation to divide the number of trigger event starting the adc conversion shield.power.setAdcDecim(LEG1/LEG2, decim) 3. Set the dead time shield.power.setDeadTime(LEG1/LEG2, rise_deadTime_ns, fall_deadTime_ns) 4. Set the phase shift in degree shield.power.setPhaseShift(LEG1/LEG2, ps_degree)

5. Enable the ADC acquisition for twist to get voltage and current measures shield.sensors.enableDefaultTwistSensors() 6. Set the duty cycle to control output voltage shield.power.setDutyCycle(LEG1/LEG2, duty_cycle) 7. Then start the converters shield.power.start(ALL)

1. 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 shield.power.initBuck(ALL, CURRENT_MODE), shield.power.initBoost(ALL)

Optional steps 2. Set the adc decimation to divide the number of trigger event starting the adc conversion shield.power.setAdcDecim(ALL, decim) 3. Set the dead time shield.power.setDeadTime(ALL, rise_deadTime_ns, fall_deadTime_ns) 4. Set the phase shift in degree shield.power.setPhaseShift(ALL, ps_degree)

5. Enable the ADC acquisition for twist to get voltage and current measures shield.sensors.enableDefaultTwistSensors() 6. Set the slope compensation to control the output currentshield.power.setSlopeCompensation(ALL, 1.4, 1.0) 7. Then start the converters shield.power.start(ALL)

Warning

Only buck topology is currently supported for current mode control.

Example

shield.power.initBuck(ALL);
shield.power.setAdcDecim(ALL, 1);
shield.power.setDeadTime(ALL, 200, 200);
shield.power.setPhaseShift(ALL, 180);
shield.sensors.enableDefaultTwistSensors();
shield.power.setDutyCycle(ALL, 0.5);
shield.power.start(ALL);

shield.power.initBuck(LEG1);
shield.power.setAdcDecim(LEG1, 1);
shield.power.setDeadTime(LEG1, 200,200);
shield.power.setPhaseShift(LEG1, 180);
shield.sensors.enableDefaultTwistSensors();
shield.power.setDutyCycle(LEG1, 0.5);
shield.power.start(LEG1);

shield.power.initBuck(ALL, CURRENT_MODE);
shield.power.setAdcDecim(ALL, 1);
shield.power.setDeadTime(ALL, 200, 200);
shield.power.setPhaseShift(ALL, 180);
shield.sensors.enableDefaultTwistSensors();
shield.power.setSlopeCompensation(ALL, 1.4, 1.0);
shield.power.start(ALL);

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

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.

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 shield.power.setSlopeCompensation. This function sets the slope compensation based on the input parameters. for example shield.power.setSlopeCompensation(ALL, 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

    shield.power.initBuck(ALL);
    shield.power.setDutyCycle(ALL, 0.5);
    shield.power.start(ALL);

2 independant leg operations

    shield.power.initBuck(LEG1);
    shield.power.initBuck(LEG2);
    shield.power.setDutyCycle(LEG1, 0.3);
    shield.power.setDutyCycle(LEG2, 0.5);
    shield.power.start(ALL);

Boost topology

    shield.power.initBoost(ALL);
    shield.power.setDutyCycle(ALL, 0.5);
    shield.power.start(ALL);

Inverter topology

    shield.power.initBuck(LEG1);
    shield.power.initBoost(LEG2);
    shield.power.setDutyCycle(ALL, 0.5);
    shield.power.start(ALL);

Example

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

Detailed documentation on available APIs classes:

Detailed documentation on Hardware Abstraction Layer classes:

API Reference

Class ShieldAPI

ClassList > ShieldAPI

Public Static Attributes

Type Name
NgndHAL ngnd
Contains all the function of the NGND switch compatible with TWISTs prior to 1.4.
PowerAPI power
Contains all the functions to drive shield power capabilities.
SensorsAPI sensors
Contains all the functions to interact with shield sensors.

Public Static Attributes Documentation

variable ngnd

Contains all the function of the NGND switch compatible with TWISTs prior to 1.4. 

NgndHAL ShieldAPI::ngnd;

variable power

Contains all the functions to drive shield power capabilities. 

PowerAPI ShieldAPI::power;

variable sensors

Contains all the functions to interact with shield sensors. 

SensorsAPI ShieldAPI::sensors;

The documentation for this class was generated from the following file docs/core/zephyr/modules/owntech_shield_api/zephyr/public_api/ShieldAPI.h