Programming and operating imperix controllers

This document provides guidance to first-time users regarding the essential procedures for deploying code to imperix controllers, as well as connecting with the equipment. It is applicable to all variants of programmable controllers, including B-Box 4, B-Box RCP 3.0, B-Box Micro, B-Board PRO, and TPI8038. Among other aspects, it notably addresses:

• Code generation: how to generate and compile code using Simulink, PLECS, or the imperix IDE.
• Connectivity: how to establish the PC ↔︎ Controller connection via Ethernet.
• Monitoring basics: the fundamentals of remote monitoring and debugging using Cockpit.

Before following this guide, if readers work with Simulink or PLECS, they are advised to consult the articles related to the ACG workflow shown in the table below. A series of video tutorials is also available with similar content. Readers who develop their code in C/C++ should consult the documentation on the installation and use of the CPP SDK.

Programming workflows

Imperix controllers utilize a CPU+FPGA architecture to execute control algorithms. Typically, the control task (user code) runs on the CPU, while low-level, time-critical functions (such as PWM modulation and safety) are handled by the FPGA. Thanks to their similar hardware architecture, all imperix controllers benefit from an identical development workflow, consisting of the following two phases:

A) Control code development and offline simulation: With Simulink or PLECS, this phase takes place entirely within the simulation software running on the PC. It includes the implementation of the control algorithms themselves, as well as the optional - but highly recommended - modeling of the plant and validation the algorithms using offline simulations. With the imperix IDE, only the implementation of the C/C++ code is possible. Offline simulation is not supported. This phase is mainly covered by the dedicated user guides.

B) Code generation and device programming: With Simulink or PLECS, this phase also takes place within the simulation software, thanks to automated code generation. Subsequently, once the run-time executable code is generated, its deployment as well as all interactions with the hardware take place using imperix's dedicated software Cockpit. This phase is the main object of this article.

For the first step A), imperix supports three possible development environments, which are summarized below. For the second step B), all actions rely on Cockpit, independently of the chosen development environment.

¹⁾ requires Matlab Simulink, Matlab Coder, Simulink Coder, and Embedded Coder
²⁾ requires Simscape Electrical or PLECS Blockset for Simulink
³⁾ requires specific license issued by imperix (more details in Licensing)
⁴⁾ requires PLECS and PLECS Coder
⁵⁾ requires specific license issued by imperix (more details in Licensing)

Phase A) - Developing and generating a real-time control code

Using Simulink or PLECS

Code development

As introduced in PN134, when developing control code on Simulink or PLECS with ACG SDK, the model is usually organized with two main subsystems, each serving a distinct purpose in the development workflow:

• Plant subsystem: Used only in Simulation mode, this subsystem enables offline validation and tuning of the control algorithm. It utilizes blocks from the Power library and Simscape Electrical / PLECS blocks to model the hardware dynamics of imperix power products. In Automated Code Generation mode, it is ignored.
• Controller subsystem: Used for both Simulation and Automated Code Generation. It contains the core control implementation alongside target-specific peripheral blocks (such as ADC and PWM) from the Control library for direct deployment to the hardware.

Important guidelines and best practices for effective use of Simulation mode are provided in PN135 (Simulink) and PN137 (PLECS).

Code generation

Once implemented and tested, the Simulink or PLECS model must be translated into code and compiled into an executable before it can be deployed onto the target. This process is taken care of automatically by Simulink or PLECS, thanks to the scripts and configuration files installed by the ACG SDK. From the user's perspective, all these tasks are carried out in one click using the following procedure:

In Simulink:

1. Select “Automated Code Generation” in the CONFIG block of the model.
2. Select the right generation of the controller. This information is required at compile time to account for hardware-specific instructions and architecture.
3. Build the model by clicking the “Build” button (or with the shortcut Ctrl+B). If the Build button is not shown, make sure that Simulink Coder and Embedded Coder are installed, and open the Embedded Coder app in the APPS tab. The Build button should appear in a new C CODE tab.

In PLECS:

1. Open the Coder > Coder option window (Ctrl+alt+B).
2. Select the subsystem containing the control implementation in the left column.
3. In the Target tab, select the target generation corresponding to your controller. This information is required at compile time to account for hardware-specific instructions and architecture.
4. Click the "Build" button to start the building process.

At the end of a successful build, Cockpit automatically launches and creates a new project with a pre-filled project name and path of the executable file. Now, to deploy the code to the target, a connection must be established, as covered in phase B.

Using the imperix IDE for C/C++

This workflow utilizes the imperix IDE, which is an Integrated Development Environment (IDE), based on the Eclipse platform. Users are required to write their control algorithm directly in C/C++ code.

The workflow relies on a provided library of peripheral routines (effectively, hardware drivers) for interfacing with each hardware resource. A simple API is also provided for interfacing the application-level code with the BBOS kernel functions. An easy-to-use framework facilitates code implementation; however, offline simulation is not easily possible or recommended with this workflow.

To build the code and generate the runtime executable, the current project should be selected in the project explorer and the “Run” icon (green play button) should be clicked.

More details are given in Installation and use of the CPP SDK.

Phase B) - Code flashing and monitoring in Cockpit

Once code is generated, uploading it to the controller (hereafter called the target) is done via Cockpit, which opens automatically at the end of the build process.

Connecting the target to the host PC

First, an Ethernet connection must be established between the host computer and the target(s). Two scenarios can be implemented:

• The target is connected to a local Ethernet network. In this case, an IP address is generally automatically attributed to the target by a server or router (over DHCP).
• A point-to-point link is established between the target and the host computer using a single Ethernet cable. In this case, the IP address is auto-attributed in the 169.254.x.x range.

In Cockpit, no specific configuration is required. Connected targets are normally auto-detected and appear in the left bar of the Target perspective, as shown on the right.

Connection within a local Ethernet network

In order for the computer to communicate with the target, IP communication must be possible, which essentially means that both devices must belong to the same network.

If the target is connected to a local network, which the computer is already connected to, it will usually automatically receive a compatible IP address. In this case, Cockpit should automatically find the target on the network and display it in the target list. If not, its IP address can be manually added by clicking the Can't find your target? link.

If this address is unknown, it can be easily found on the B-Box 3 and 4 using the front panel. However, with a TPI, B-Box Micro, or B-Board PRO, such a display does not exist. Manually configuring the computer's IP address in the same range as the target's backup static IP address may then be the only resort (see PN144).

If the B-Box shows a dynamic IP in the 169.254.x.x range, it means it did not receive any IP address automatically. This is a self-assigned address, allocated whenever no DHCP response is received.
In this case, manually configuring the computer's IP address may be required (see PN144).

Cockpit uses the following TCP ports: 4840, as well as 59000 through 59010.
These ports must not be blocked by a firewall.

Direct (point-to-point) Ethernet connection

In case of direct point-to-point connection (e.g. using an USB-to-Ethernet dongle adapter), both the computer and the target should self-allocate an IP addresse in the 169.254.x.x range. This process is known as Automatic Private IP Addressing (APIPA).

In this case, Cockpit should automatically find the target on the network and display it in the target list. If not, its IP address can be manually added by clicking the Can't find your target? link.

APIPA requires firmware version 2025.2 or later. For older versions or in case of trouble, using a static IP may be required. Detailed instructions are given in Advanced Network Configurations.

Flashing and launching the code

At the end of a successful build, Cockpit automatically launches and creates a new project with a pre-filled project name and path. Only a few steps are required to load the code to the target and launch it:

1. Using the Cockpit left bar, click on "Link target" and choose the desired target (see images below).
2. Once the project is linked to a target, the code is automatically downloaded to that target and starts automatically.
3. If the code is re-generated from the same location (i.e., the model is rebuilt), Cockpit simply loads the new version of the code and restarts it.

More information on how to deal with projects in Cockpit is given in the Cockpit user guide.

Running the control code and enabling PWM outputs

Once the code has been deployed to the target, it is automatically launched and runs continuously. However, the PWM outputs (i.e., gating signals) are not physically generated unless they are explicitly enabled by the operator. Enabling or disabling the gating signals is done in Cockpit using the dedicated button at the top of the project. This effectively acts as a start/stop switch that determines when the converter is actually operating (i.e., converting power).

The enable/disable mechanism is entirely independent from the execution of the control algorithms and acts as a gating switch on all PWM signals. If anything goes wrong during converter operation, the PWM outputs are immediately and automatically blocked to stop the converter, while the control continues to run.

Operating states of the controller

Imperix controllers have three possible states and conform to the state diagram below:

• BLOCKED: The CPU tasks are running, but PWM outputs are blocked (ready to be enabled).
• OPERATING: The PWM outputs are enabled and the system is fully operating without any error.
• FAULT: An error occurred and the system waits for its acknowledgment. The PWMs are blocked.

Controllers can reach the FAULT state for various reasons. The most common ones are listed in the table below. Any fault immediately switches off the PWM outputs to stop the operation of the converter.

The controller goes into OPERATING state when the PWM outputs are enabled, and goes back to BLOCKED state when disabled. In case of error (e.g. due to an overcurrent detection in the power setup), the controller immediately goes into FAULT state, which immediately disables the PWM outputs. The source of the fault is described in Cockpit, either in the red banner located in the "Project pane“ (see image below) or in the "Log module". The return to the OPERATING mode is only allowed once the fault is cleared and acknowledged by the user.

Monitoring the controller in Cockpit

Each Cockpit project contains a view in which the user can drag and drop modules to monitor and alter user-defined variables. Any signal in the user code connected to a Probe block can be monitored in real time using the Scope or Rolling plot modules. Additionally, the Tunable parameters defined in the user code can be modified at run time from within the Variables module.

Some features that are especially useful include:

• Scope module to display ADC samples at the control rate, or oversampled data (B-Box 4 only)
• Transient generator tool to apply test profiles
• Spectral Analyzer tool to display scoped variables in the frequency domain
• GUI Builder module to create custom dashboards for interacting with the controller

The Cockpit user manual provides more details on the capabilities of the Cockpit software.

Using the protection mechanisms

To ensure safe operation of both the imperix hardware and the surrounding equipment, imperix systems provide three layers of fast, threshold-based protection:

• at the power-module level,
• at the controller hardware level, and
• at the controller software level.

The hardware protections of the B-Box family controllers feature configurable thresholds and are implemented within their analog input circuits. For the B-Box 4 and B-Box Micro, these thresholds can be configured in Cockpit, whereas for the B-Box RCP 3.0 they must be set directly on the device via the front-panel screen menu. More information for each controller is available at:

• B-Box 4: Analog I/O configuration on B-Box 4
• B-Box RCP 3.0: Analog front-end configuration on B-Box RCP 3.0
• B-Box Micro: Analog inputs configuration on B-Box Micro
• B-Board PRO: no hardware-level protections on analog inputs
• TPI 8032: automatic hardware-level protections, not user-configurable

At this stage, it is also highly recommended to consult Over-current and over-voltage protection for details on how these protections work to guarantee safety during operation.

Using the Timings information

When a code is running on a target, Cockpit provides a useful graphical representation of the various computation and data transfer delays that appear in the controller. This helps identify the CPU load, as well as an estimation of the total controller delay, useful for controller tuning. More information is available in the Cockpit User Guide.

Where to go from here?

Get started with specific controllers

• B-Box 4 - Quick start Guide
• B-Box micro - Quick start Guide
• TPI 8032 - Quick start Guide

Build power converter setups using imperix power modules

• How to build a buck converter
• How to build a 3-phase inverter

Get inspired by numerous code examples to control

• Grid-tied inverters
• Motor drives
• Multi-level converters

Learn how to program the FPGA of the controller to develop high-performance control loops

• Getting started with FPGA development
• High-Level Synthesis for FPGA developments