Programming and operating imperix controllers
PN138Table of Contents
This page helps new users get started with the B-Box RCP and the B-Board PRO. 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 Cockpit software.
For a complete introduction to imperix software development kits, it is recommended to read the following articles beforehand:
What are the B-Box and the B-Board?
The B-Box RCP and the B-Board PRO are two types of fully-programmable digital controllers, specifically designed to facilitate the experimental validation of power converter control techniques. 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.
Control of a grid-tied voltage source inverter
The B-Box RCP is the ready-to-use and fast-to-setup version, meant for lab environments, whereas the B-Board PRO is the bare version, meant to be embedded onto power converters. Both are programmed the exact 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.
Both controllers are centered around a 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 (full datasheet) | B-Board PRO (full datasheet) | |
|---|---|---|
| Processor (Xilinx Zync) | 2x ARM 1GHz | 2x ARM 1GHz |
| FPGA (Xilinx Zynq) | Kintex 7 125K | Kintex 7 125K |
| Analog inputs | 16x 16bits @500ksps | 8x 16bits @2Msps |
| PWM outputs | 16x optical 32x electrical (3.3V) | 16x electrical (1.8V) 16x electrical (3.3V) |
| Communication | 1x Ethernet 1 Gbps 3x SFP+ 5Gbps (RealSync) 1x CAN (RJ45) | 1x Ethernet 1Gbps (carrier board) 3x SFP+ 5Gbps 1x CAN (carrier board) |
| C++, Simulink and PLECS programming | Yes | Yes |
| Flexible analog front-end | Yes | No |
| Hardware-level protections | Yes | No |
How to program the controller?
Programming the B-Box or the B-Board 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
ACG SDK and CPP SDK contain a paid license that gives unlimited access to the controllers. All software licenses are target-locked (i.e. usable on multiple computers) and lifetime (no renewal fees, free software updates). In multi-controller configurations, only the master unit must be licensed (i.e. the one running the user-defined CPU program). For more info, please visit https://imperix.com/software/.
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 that is used, the build procedure is done such 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 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, enter the IP address of the target (see section below) and click “Create”.
For more info, please refer to the user manual of Cockpit.
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, or on the carrier board of the B-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 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-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 and doesn’t receive any dynamic IP address. Therefore, the pre-configured static IP address is used (default value is 192.168.222.22).
In this case, 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”.
How to operate the controller?
Hardware configuration of the B-Box analog inputs
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 screen of the B-Box. 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, you can refer to Analog front-end configuration on B-Box RCP.
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
The B-Box and B-Board 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
The B-Box and B-Board 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 if 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 mechanism on the analog inputs of 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).
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 into BLOCKED state.
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
Build power converter setups using imperix power modules
Get inspired by numerous code examples to control
Learn how to program the FPGA of the controller to develop high-performance control loops
