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:

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

	B-Box RCP (datasheet)	B-Box Micro (datasheet)	B-Board PRO (datasheet)
Processor (AMD/Xilinx Zynq)	2x ARM 1GHz	2x ARM 1GHz	2x ARM 1GHz
FPGA (AMD/Xilinx Zynq)	Kintex 7 125K	Kintex 7 125K	Kintex 7 125K
Analog inputs	16x 16bits @500ksps	8x 16bits @2Msps	8x 16bits @2Msps
PWM outputs	16x optical 32x electrical (3.3V)	8x optical	16x electrical (1.8V) 16x electrical (3.3V)
Communication	1x Ethernet 1 Gbps 3x SFP+ 5Gbps (RealSync) 1x CAN (RJ45)	1x Ethernet 1Gbps	1x Ethernet 1Gbps (carrier board) 3x SFP+ 5Gbps 1x CAN (carrier board)
C++ programming	Yes	Yes	Yes
Simulink/PLECS programming	Yes	Yes	Yes
Flexible analog front-end	Yes	No	No
Hardware-level protections	Yes	No	No

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:

Simulink	PLECS	C++
Make sure that “Automated Code Generation” is selected in the Configuration block of the model, and click the “Build” button (Ctrl+B).	Open the “Coder > Coder option” window (Ctrl+alt+B), make sure that the correct subsystem is highlighted in the left column, and click the “Build” button.	In imperix IDE, make sure the current project is selected in the project explorer and click on the “run” icon.

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 PC?

The communication between the target and the host computer uses the Ethernet port located at the front of the B-Box RCP, the back of the B-Box Micro, or on the B-Board PRO carrier board. The connection to the host computer is required to deploy the user code and to provide real-time access to the controller variables during run-time.

Two different scenarios must be distinguished, depending on how the IP address is assigned to the target:

Option A: The target is part of an Ethernet network

If the target is part of an Ethernet network and has a dynamic IP address, assigned by a DHCP server. 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 B-Box Micro or B-Board PRO, the dynamic IP address can be found using the “Target explorer” window of Cockpit or a device browser (e.g. Bonjour browser) and searching for a device with a hostname starting with “BB-”.

Option B: The target is directly tied to the host computer

If the target is directly tied to the host computer, it doesn’t automatically receives a dynamic IP address. THen the static IP must be used.

A single target is connected to the computer

The pre-configured static IP address default value is 192.168.222.22. To connect to it, the user must configure the host computer accordingly. To do so:

• Navigate to “Control Panel” > “Network and Internet” > “Network Connections”.
• Right-click on the Ethernet adapter that is connected to the target and select “Properties”.
• Highlight “Internet Protocol Version 4 (TCP/IPv4)” and click “Properties”.
• Check the box “Use the following IP address”, enter the first three bytes of the static IP address of the device, and choose the last byte, different from that of the target. Also, change the network mask to “255.255.255.0”.

Several targets are connected to the computer

If several targets are connected directly to the computer, each target must be manually assigned a different static IP 2 address. The IP 2 addresses must be in another subnet than the default IP 1 to avoid conflict (for instance 192.168.100.xx) . To modify the static IP 2 address, connect one-by-one each target using the default IP 1 address (see procedure above), open Cockpit, and edit the static IP 2 address from the Target configuration window.

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.

Fault type	Reason(s)	Recoverable
Configuration	Misconfiguration in the user code, such as: – Physical resource used multiple times (e.g. analog input) – Excessive interrupt frequency considering the code complexity	No
Code crash	Can be CPU or FPGA watchdog expired, C exception, etc…	No
Overvalue detected	The configured threshold on one of the analog inputs of the B-Box is exceeded. (See section below)	Yes – requires user ack
Interlock	A fault is triggered by an external device connected to the interlock connector (electrical or optical). (See B-Box datasheet)	Yes
Fault line	One of the fault inputs (FLT) is pulled high. (See B-Box datasheet)	Yes

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