Programming and operating imperix controllers

This page helps new users get started with imperix power electronic controllers. In particular, it explains how to deploy a user code onto these controllers, and how they can be operated and monitored during run-time, using the imperix Cockpit software. Most of this content also applies to the TPI8032 programmable inverter.

For a complete introduction to imperix software development kits, it is recommended to read the following articles beforehand:

ACG SDK:
Installation guide for the ACG SDK

• Simulink:
  Getting started with Simulink
  Simulation essentials with Simulink

• PLECS:
  Getting started with PLECS
  Simulation essentials with PLECS

CPP SDK:
Installation and utilization of CPP SDK

Which programmable controller should I use?

The B-Box RCP and B-Box Micro are two fully programmable digital controllers, specifically designed to facilitate the experimental validation of power converter control techniques in a laboratory environment. The former offers superior I/O capabilities, while the latter is rather dedicated to teaching applications.

The B-Board PRO is a small control board, which is designed to be directly integrated within custom-designed power converters. It happens to be also used inside the B-Box RCP and Micro, as well as inside the programmable inverter.

For all controllers, the typical use cases include grid-tied inverters, motor drive inverters, multi-level converters, or DC/DC converters. Combined with imperix power modules, an experimental setup of almost any converter topology can be built easily and rapidly.

All imperix controllers can be programmed the same way, from a PC by writing C code (CPP SDK) or by drawing a block diagram in Simulink or PLECS (ACG SDK). The code is deployed onto the controller with the Cockpit software, using an Ethernet link between the PC and the controller. Cockpit also provides run-time interaction and monitoring from the host PC.

Imperix controllers are built on AMX/Xilinx Zynq 7030 SoC, featuring a dual-core ARM processor (CPU) mated with a Kintex-based programmable logic (FPGA). The control task (user code) runs on the CPU, whereas the low-level and time-critical tasks (such as PWM modulators or safety logic) run in the FPGA.

Main specifications

How to program the chosen controller?

Once selected, programming the controller requires software tools contained in the CPP SDK or ACG SDK packages. The following pages explain how to install and use the SDKs to develop power converter control algorithms. Many code examples are also available from this knowledge base.

• ACG SDK (programming from Simulink or PLECS): Installation guide for imperix ACG SDK
• CPP SDK (programming with C code): Installation and use of the CPP SDK

Once developed, the code or model must first be built before it can be deployed onto the controller. This is done using the following procedure:

Regardless of the workflow used, the build procedure is done so that everything takes place automatically. This comprises code generation, compilation, and upload of the user code onto the controller. 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. To load the user code (.elf file) to the target and start the code execution, click on “Link target” and choose your device using the Cockpit left bar.

How to connect the controller to the host computer?

The communication between the controller (referred to as the “target”) and Cockpit on the host computer is established via the Ethernet port, which is located on:

• the front of the B-Box RCP
• the front of the TPI
• the back of the B-Box Micro
• on the B-Board PRO carrier board

The host computer connects to the target using an IP address (e.g. 10.10.10.111). Once the connection is established, the target will appear in the Cockpit target list, as shown on the left.

The target can either be connected to an existing Ethernet local network, or directly to the Ethernet port of a computer. These two scenarios are presented below in more detail.

The target is connected to an existing Ethernet local network

If the target is connected to an existing network, it will usually receive a dynamic IP address automatically from the DHCP server. Most of the time, Cockpit should be able to automatically find the target on the network and display it in the target list. If the target is not found, its IP address can be manually added by clicking the Can’t find your target? link.

On a B-Box RCP, this address can be found by simply turning the push button of the front panel at the end of the startup sequence. With a TPI, B-Box Micro, or B-Board PRO, the dynamic IP address can be found using a device browser (e.g. Bonjour browser) and searching for a device with a hostname starting with “BB-” or “TPI-“.

Note that communication between the controller and the host PC uses the following TCP ports: 4840, 59000 through 59010. These ports must not be blocked by your firewall.

The target is directly connected to the host computer

Starting with firmware version 2025.2, if no DHCP server is detected, the target automatically assigns itself an IP address in the 169.254.x.x range. When connected to a PC, the target should appear in Cockpit automatically.

Automatic IP assignment works only when a single Ethernet port is used on the computer. If multiple targets must be connected directly to the same computer, the use of a network switch is strongly recommended. Otherwise, static IP configuration is required. For detailed instructions, refer to the Advanced Network Configurations page.

For automatic IP addressing to function correctly, the host PC’s Ethernet interface must be configured to obtain an IP address automatically. This is the default setting on Windows, so no changes are necessary unless it has been manually modified.

If needed, this setting can be updated following these steps:

How to update the controller firmware?

After an SDK update, if the controller firmware requires an update, Cockpit will display the following notification window.

Clicking Update the firmware opens the Target update window shown below. If multiple devices are interconnected via SFP fibers, they can all be updated with a single click.

How to operate the controller?

Hardware configuration of the analog inputs of the B-Box RCP

Deploying the user code onto the CPU of the B-Box is not the only action required to operate the controller; the B-Box also requires hardware configurations of its analog front end. The configuration parameters are not contained within the user CPU code and need to be set from the front panel (LCD screen) of the B-Box RCP. The hardware parameters that need to be configured are the following:

• Impedance of the analog input
• Gain of the analog input
• Cutoff frequency of the input filter (optional)
• Thresholds of the overvalue detection mechanism

To learn more about how to set up those parameters, please refer to:

• Analog front-end configuration on B-Box RCP.
• Analog inputs configuration on B-Box Micro.

Enabling/disabling PWM signals

Once the code has been deployed to the target, the code is automatically started, meaning that the CPU interrupt starts running. However, the PWM signals (i.e. gating signals) are not physically produced until they are deliberately enabled by the operator. Enabling and disabling the gating signals is done from Cockpit by clicking the dedicated button at the top of the project. This can be seen as a start/stop switch to control when the converter is actually running (i.e. converting power).

The enabling/disabling process is completely independent of the running control algorithm and acts as a gating switch on all PWM signals. If anything goes wrong during operation of the converter (see FAULT state below), the PWM outputs are immediately and automatically disabled to stop the converter operation.

The operating states of the controller

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

• CONFIG: the system is checking that the peripherals (ADC, PWM,…) are correctly configured.
• BLOCKED: the system is configured correctly and PWM outputs are blocked (ready to be enabled).
• OPERATING: The PWM outputs are enabled, and the system is operating without error.
• FAULT: An error occurred and the system waits for its acknowledgment. The PWMs are blocked.

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.

The most common types of faults

Controllers can reach the FAULT state for various reasons. The most common ones are listed in the table below. A fault can be recoverable or unrecoverable, depending on whether clearing it requires re-starting the code (possibly re-compile) or not. Obviously, any type of fault immediately switches off the PWM outputs to stop the operation of the converter.

Overvalue detection on the B-Box RCP

As detailed in analog front-end configuration, the analog inputs of the B-Box RCP embed analog comparators that trigger a fault in case the measured value exceeds one of the user-defined limits. This mechanism is particularly useful to ensure that the power converter stays within safe operating conditions (for itself and the surrounding equipment). Furthermore, as the overvalue detection mechanism is implemented 100% with hardware, it is entirely independent from the software and therefore guarantees maximum reliability.

If an overvalue is detected, the PWM outputs are immediately disabled, the screen of B-Box displays “HARDWARE FAULT: Analog input“, and the orange LED of the corresponding analog input lights up. The user can use the button on the front panel to navigate through the menus of the screen to get further information about the fault and acknowledge it:

After hardware faults are acknowledged, the B-Box returns to BLOCKED state.

Overvalue detection on the B-Box Micro

As detailed in analog inputs configuration, the analog inputs of the B-Box Micro are more rudimentary than on the B-Box RCP. Notably, the programmable impedance, programmable gain and programmable filter are not available.

The overvalue detection mechanism also differs, as it is not implemented in hardware, but rather in the FPGA firmware. This offers an intermediate level of reliability, as independence with the user software is guaranteed, but protections remain however dependent from the proper operation of the FPGA.

In the B-Box Micro, the safety limits can be directly configured from within Cockpit. For that, switching to the Targets perspective and selecting the corresponding B-Box Micro will display the Target configuration menu in the Cockpit central view. This view offers an additional tab called Analog inputs (see image below).

Run-time monitoring and parameter tuning 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.

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

Where to go from here?

Learn more about Cockpit

• Cockpit user manual

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