Getting started with ACG SDK on Simulink

Table of Contents

This note introduces basic instructions in order to efficiently get started with the imperix ACG SDK on Simulink.

A general overview of software-related notes is given on this page.

Related material

Suggested prerequisites

Installation guide for imperix ACG SDK

Default template

To start working with Simulink, a file template must be used. Therefore, the first step of every control development project is always to copy the base template into the folder of your choice (such as the workspace folder of Matlab). The base template is always located in:

C:\imperix\BB3_ACG_SDK\simulink\user_template\imperix_template.slx

The copied template can be renamed as long as the rules for Matlab/Simulink file naming are observed: the file must start with a letter and can be followed by letters, numbers or underscores.

It is highly recommended not to start with a blank Simulink model, since the template already contains the necessary configuration for the automated generation, upload and loading of the runtime executable.

The default template (fig. below) contains a basic skeleton to start working right away. The model contains two subsystems:

Plant model: contains the model of the system to be controlled. This is typically the model of the power system itself (e.g. converter, sources, grid, machine, sensors,…)
Closed-loop control: contains the control implementation that can be simulated or used to generate the control code for the imperix controller (B-Box RCP, B-Box Micro, or B-Board PRO). It also contains a configuration block that performs the main configurations of the Simulink model.

Plant model subsystem

In order to run the control algorithm in simulation, Simulink needs a model of the real converter hardware (system to be controlled). This model should be located inside the Plant_Model block of the root view of your Simulink model. To model the converter hardware, it is recommended to use either PLECS Blockset or Simscape Power Systems.

Details on how to install these simulation tools are provided in PN133.

The plant model is only considered during offline simulation of the system. In code generation mode, the content of the plant model is ignored.

The figures below show two plant models of a PMSM drive.

Simulation model of motor drive using PLECS Blockset

Simulation model of motor drive using Simscape Power Systems

Closed-loop control subsystem

Blockset library

Starting from the default template or an existing example, control implementation can be done using the blocks provided in the imperix ACG-SDK blockset and any standard Simulink block.

The blockset can be found in the library browser (View > Library Browser [Ctrl+Shift+L]) and browsing to imperix ACG SDK.

Alternatively, the blockset can be accessed by selecting any imperix block in the base template and pressing Ctrl+L.

The imperix blockset is shown on the right. It essentially implements hardware-related mechanisms that are associated with analog and digital I/Os. The blockset also contains a few useful routines such as coordinate transformations, various types of PLLs, etc.

Basic control example

For the sake of example, a basic control algorithm for a buck converter is depicted below. It sets the output voltage to 12V, regardless of the measured input voltage.

This explanatory basic control scheme contains:

A Configuration block to define the model parameters (this block is mandatory)
An ADC block to retrieve the simulated DC bus voltage in simulation, and the analog input on channel 0 of the imperix controller in code generation
A Tunable Parameter block to define a variable Vout_ref that is accessible and modifiable in real-time from the Cockpit software
A Probe block to define a variable d that can be logged in real-time from Cockpit
A Carrier-based PWM (CB PWM) modulator to generate PWM signals with a duty-cycle D. The PWM signals are wired to the plant model in simulation and directly output on the PWM outputs of the imperix controller in code generation

The Configuration block provides an ADC clock signal that must be connected to the clock input of all ADC blocks, and a PWM clock signal that must be connected to the clock input of all PWM blocks. This mechanism enables Simulink to accurately take into account the sampling instant during simulation, as well as the phase reference for phase-shifted carriers.

Simulation and code generation

The same Simulink model supports both simulation and Automated Code Generation (ACG) of the control algorithm. The selection of the Model execution purpose can be made in the Configuration block:

In Simulation mode, the model is simulated using the plant model drawn inside the Plant_model block. The model uses the variable-step solver parameters specified in the Configuration block. For the closed-loop control, the values going through the ADC blocks are sampled with the sampling clock provided by the Configuration block. The whole control algorithm should be executed at the main interrupt rate, defined by the variable CTRLPERIOD (see PN135 for in-depth content).
In Automated Code Generation mode, C++ code is automatically generated by the Simulink Coder engine when the model is built (Ctrl+B). All signals coming from and going to the Plant_model block are ignored and replaced by the analog inputs and the digital inputs/outputs of the real controller (B-Box RCP, B-Box Micro, or B-Board PRO). The analog signals are sampled at the control period CTRLPERIOD and the digital PWM outputs switch at the frequency of the provided clock.
Once the C++ code is generated and compiled, the Cockpit software opens automatically and loads the executable on the connected target controller.