Getting started with the imperix ACG SDK

This article provides getting-started instructions for first-time users of the imperix ACG SDK. It focuses on the typical workflow associated with the simulation and automated code generation intended for imperix controllers. It notably addresses:

• Product presentation: What the ACG SDK is, and what pieces of software it contains.
• Resources: How the imperix blocksets can be used and how the files are typically organized.
• Simulation: How to effectively run accurate offline simulations.

The article focuses on developing code for the controllers’ CPU. Information regarding the implementation of programmable logic to the devices’ FPGA is given in PN169. Similarly, users interested in writing C/C++ code manually (as opposed to using code generation) should refer to a separate article about the CPP SDK.

Recommended articles related to the ACG workflow are shown below. A series of video tutorials is also available with similar content.

Pre-requisites

• Working with Matlab requires requires Simulink, Matlab Coder, Simulink Coder, and Embedded Coder. Similarly, Working with PLECS requires PLECS Coder. These software should be installed first. Related instructions are given in PN133.
• The ACG SDK should be installed first. Related instructions are given in PN133.
• The ACG SDK can be freely installed, but a license is required for executing the run-time code on a controller. More information on licensing is given in PN160.

Product description

The ACG SDK is a Software Development Kit (SDK) for use as a complement to Matlab Simulink or PLEXIM PLECS, enabling engineers to program imperix controllers directly from these softwares. It includes:

Typical workflow

Regardless of the programming environment, the development typically proceeds as follows:

• Developing a Simulink or PLECS model that will support both offline simulation and code generation:
  1. Opening an existing example from the knowledge base, creating an empty Simulink/PLECS file, or starting from an empty imperix template.
  2. Implementing the control algorithms using standard Simulink/PLECS blocks as well as dedicated hardware blocks from the imperix Control library.
  3. Modeling and simulating the complete system using the imperix Power library in order to support the pre-validation of the control algorithms during offline simulations.
  4. Tuning of the implemented control using offline simulations.
  5. Generating and compiling code directly from within Simulink or PLECS.
• Using Cockpit:
  1. Connecting to the target hardware - i.e. the controller - and flashing the generated runtime code.
  2. Launching the code and executing all further interactions with the hardware, such as real-time debugging, parameter tuning, monitoring and logging.

Developing a Simulink/PLECS model

During this first phase, the control software (i.e., the set of control algorithms) is developed and its behavior is tested in an offline simulation before deployment on the controller. There are essentially five steps:

1. Opening an existing/new model

Essentially, three options are available:

1. Most users prefer starting from an example found on the imperix knowledge base, which offer the benefit of being pre-configured and generally reasonably close to the final application. Once downloaded, the example file can be copied or renamed (as long as the rules for Matlab file naming are observed).
2. Starting from an empty file is also possible. However, with Simulink, leveraging a basic template is recommended, notably as it implements a clean separation of the controller and plant (see below). The imperix base template is always located in [installation_path]\user_template\imperix_template.slx
3. Existing models can be adapted to support both simulation and code generation. In PLECS, this is trivial. However, in Simulink, a good understanding of the software's configuration is necessary. Further information is given in PN143.

The vast majority of examples available on the knowledge base are organized with two main subsystems:

• The controller subsystem contains the part that represents the control implementation, which can be simulated or used to generate real-time code. This subsystem also contains the CONFIG block, which is responsible for the model configuration as well as some global system parameters.
• The plant subsystem contains the model of the system to be controlled, as opposed to the controller side. This is typically the model of the power system itself (e.g. converter, sources, grid, machine, sensors,…).

A typical arrangement of the overall model is shown below:

2. Implementing the control algorithms

With Simulink or PLECS, application-level control algorithms can be easily developed similarly to any other simulation model thanks to numerous pre-existing blocks. Indeed, both Simulink and PLECS are specifically designed to enable automated code generation from the vast majority of their blocks. In practice, only the blocks leading to a non-deterministic execution in real time are not supported (this is notably the case of some optimization algorithms, which feature a non-predictable convergence time).

In addition to the standard blocksets, the ACG SDK provides two libraries specifically for imperix products:

• The Control library, containing target peripheral blocks, i.e. functions and resources specific to imperix control equipment, such as ADC, PWM, GPI/GPO, etc. or even communication options. These blocks are typically used on the controller side of a Simulink/PLECS model.
• The Power library, containing simulation models for individual imperix power products - such as the PEB modules - or system-level components like the motor test bench or the programmable inverter. These blocks are typically used on the plant side of a Simulink/PLECS model. Specific getting-started instructions are given in Getting-started with the Power Library.

3. Modeling and simulating the system

With the imperix ACG SDK, a unique Simulink or PLECS model (i.e. a single file) can be used for both simulation (offline, on the computer) and code generation (i.e. the production of a binary executable, for use in real time on a controller). There are hence two possible model execution purposes:

• In Simulation mode, the complete Simulink/PLECS model is simulated, including both the Controller and the Plant subsystems. The model uses the configured solver parameters (see below).
• In Automated Code Generation mode, C++ code is automatically generated by the Simulink/PLECS Coder engine. All signals coming from and going in the Plant subsystem are ignored and replaced by the analog inputs and the digital inputs/outputs of the real hardware.

As such:

• The Controller subsystem is useful for both offline simulation and code generation. In order to support this, each block of the Control library contains two subsystems:
  • One for simulation (offline) that holds an accurate model to simulate the controller hardware itself (e.g., execution delays, driver latencies).
  • One for code generation (runtime) that translates data flows and parameters from the graphical model directly into calls to the underlying C/C++ hardware driver routines.
• The Plant subsystem is only considered during offline simulation. As such, blocks from the Power library only contain a simulation model and do not infer any code during code generation.

In Simulink, the selection of the model execution purpose can be made in the CONFIG block (see below). In PLECS, both simulation (Ctrl+T) or code generation (Ctrl+alt+B) can be launched without having to make such a selection first.

Control discretization and sampling

To accurately represent real-world operation, where the control implementation (the content of the Controller subsystem) is executed within a CPU interrupt routine, that portion of the model must be simulated using a discrete time step that corresponds to the interrupt execution frequency. By contrast, the rest of the model (the content of the Plant subsystem) is best represented using continuous-time signals to accurately simulate physical electrical dynamics.

The peripheral blocks from the Control library, located within the Controller subsystem, serve as the essential interface between these two domains. Their integrated simulation models ensure that sampling instants, carrier phase shifts, execution times, and various hardware delays are accurately modeled.

To ensure accurate modeling and valid offline simulation, these mechanisms must be well understood. Because their implementations vary, users should consult the environment-specific documentation to ensure accurate modeling in either Simulink or PLECS. Further details are provided in the following dedicated pages:

• Simulation essentials with Simulink (PN135)
• Simulation essentials with PLECS (PN137)

4. Tuning the control algorithms

The simulation models provide realistic results because the relevant dynamics are accurately represented in both the controller and the plant. On the controller side, effects such as computation time and driver delays are explicitly modelled in the Control library blocks, whereas the plant is accurately modelled using the Power library. This level of fidelity allows the control implementation to be validated in offline simulation and enables controller tuning even before generating the runtime code.

It is therefore highly recommended to first test and validate the control implementation in simulation, as this significantly reduces the time required for experimental validation in the laboratory.

For readers seeking a deeper understanding, additional information on the various delays involved in the algorithm execution, as modelled in the simulation environment, is provided in Control delay identification.

5. Generating real-time code

Once validated in offline simulation, the control code can be generated automatically for deployment on an imperix controller. This procedure utilizes automated code generation tools from Simulink or PLECS, which leverage the target-specific drivers embedded within each peripheral block of the Control library.

The build procedure varies slightly between Simulink and PLECS environment. The exact procedures are detailed in PN138, but it is as simple as:

• On Simulink, set the Model execution purpose to "Automated Code Generation" in the CONFIG block, select the right controller generation in the "Code gen." tab, and build the model (Ctrl+B shortcut).
• On PLECS, in the Coder > Coder option window, select the right target generation from the target list, and click the "Build" button.

This process translates the graphical model into C++ code and compiles it with target-specific drivers for peripherals like ADCs and PWM modules. It is mandatory to specify the controller generation (Gen 3 vs. Gen 4) during this stage, as the compilation must account for hardware-specific instructions and unique memory architectures.

At the end of a successful build, an executable file (.elf) is generated to be flashed onto the controller, as described in the subsequent section.

Programming the hardware controller

After the code is generated from the Simulink or PLECS model, the next steps are:

1. Flashing the code

As introduced in PN138, to flash the code onto an imperix hardware controller, users must first establish a connection between the host PC and the target(s) using an Ethernet cable. The connection can be direct (point-to-point) or through an Ethernet local network. Connected targets are normally auto-detected by the Cockpit software and appear in the user interface without requiring manual configuration.

When Cockpit is launched, it automatically creates a new project with the executable path pre-filled. Deployment is achieved by clicking "Link target" and selecting the desired target from the list of detected targets. The code is then automatically downloaded and launched on the selected target. More details on these essential procedures are provided in PN138.

2. Interacting with the target

Once the code is running, interacting with the running code is primarily managed through Cockpit, where the operator must explicitly enable PWM outputs to physically generate gating signals, even though the control algorithm runs continuously upon launch. Users can monitor and alter defined variables in real-time using modules like the Scope, Rolling Plot, or Variables module, and can tune parameters without stopping execution. Comprehensive instructions on using these tools can be found in the Cockpit user guide.

Further readings

It is highly recommended to read the following pages

• Simulation essentials with Simulink guides the reader through offline simulation using ACG SDK and Simulink.
• Simulation essentials with PLECS guides the reader through offline simulation using ACG SDK and PLECS.
• Programming and operating imperix controllers addresses how to deploy the control code onto an imperix controller.
• Cockpit user guide (PN300) gives a full guide on how to use Cockpit monitoring software.