Cockpit – User guide

This user guide explains how to use imperix Cockpit to interact with imperix power converter controllers, namely the B-Box RCP and the B-Board PRO. This page describes in details the tools and features provided by Cockpit as well as how to use them.

For new users, it is recommended to read the following article beforehand to get started with the imperix software development kit (SDK):
Programming and operating imperix controllers

What is Cockpit

Cockpit is a powerful monitoring software included in both the ACG and CPP SDKs. It is designed to facilitate the experimental testing of power electronics systems by leveraging the hardware capabilities of imperix B-Box RCP and the B-Board PRO programmable controllers.

The software provides multiple tools (modules) for both observing and acting on the user code running on imperix controllers.

How to create a new project

To interact with an imperix controller, creating a new project is required.
After the steps described in How to program the controller are achieved, Cockpit is automatically launched and a new project is created with a pre-filled project name and path to the user code.
Alternatively, it is also possible to manually open Cockpit and create a new project by clicking on the + button at the bottom of the project bar.

To finalize the project creation, the IP address of the target (B-Board or B-Box RCP) must be entered.
The target’s IP address can be either manually entered or automatically identified using the Target explorer tool (binocular icon).
Please refer to the chapter on How to connect the controller to the host PC to ensure the target is properly connected to the host computer.
Once all three fields are filled in, the project can be created by clicking on the CREATE button.
The project pane will then appear in the project bar and a project view will be simultaneously created.

How to interact with the project pane

The project pane offers a centralized view from where the user can pilot his imperix controller. It also allows quick access to all control variables (user variables).

Upon creation, the project pane will automatically connect to the specified target, load, and start the user code (.elf file). The following image shows the project pane once it is connected to the target. 

Note: If a fault is triggered on the controller, the project pane interface will be changed to the one displayed in the image to the right. Further information on the fault mechanism and how to troubleshoot them are detailed in The most common types of faults chapter.

Note: If Cockpit unsuccessfully tries to connect to the target, see the image to the right, the project pane will indicate that the connection with the target cannot be established or was lost. In this case, check that the Ethernet cable is correctly connected and that the target is correctly powered on. Subsequently, verify that the specified IP address is correct and validate that the target can be pinged.

Using the modules to interact with the controller

Once a project is created, the user has access to various control and monitoring modules that can be dragged and dropped from the top bar to the project view. The user can then freely rearrange and resized these modules inside the project view. 

Scope module

This module allows to display control signal on an oscilloscope-like interface. It captures every sample of the scoped user variables. The acquisition is done at the control task rate (i.e. the main interrupt frequency of the controller) ensuring each and every sample is scoped. 

The scope module can monitor up to 100 MBytes of data. The window length and the control task rate will affect how many user variables can be scoped. 
If the control task is set to a standard frequency of 20kHz, it represents scoping 1 variable for 21 minutes or 32 variables (maximum number of scoped variables) for 40 seconds.

Scope module interface

 Trigger configuration

The trigger mechanism of the scope module behaves the same way as the trigger on a regular oscilloscope. The Tigger pane located in the right bar allows the configuration of the scope trigger.

Transient generator configuration

The transient generator allows the user to apply a predefined sequence of steps to multiple user variables. 

In the following example, three transient events are applied to Ig_d_ref. It can be seen that these events are generated simultaneously with the acquisition of Ig_a, Ig_b, Ig_c, and Ig_d.

Please take note of the following limitations: 

• Only user variables connected to Tunable parameter block can be selected in the Variable field.
• The variable in Variable field must be added to a plot or the transient will not work.
• The number of transient steps throughout all transient variables is limited to 32.

Scope module shortcuts

• To add multiple variables to a plot, open the user variable section in the project pane.
  Keep the ctrl key pressed and perform left mouse clicks to select the desired variables.
  Alternatively, perform a left mouse click on the first variable to select, maintain the Shift key pressed, and do a second left mouse click on the last variable to select.
  These selected variables can then be dragged and dropped into a plot.
• To zoom in and out along the horizontal axis, place the mouse cursor where you want to zoom. Then use the wheel of your mouse to zoom in or out around the location of your mouse cursor.
• To zoom in and out along the vertical axis, place the mouse cursor where you want to zoom. Then press the ctrl key, and use the wheel of your mouse to zoom in or out around the location of your mouse cursor.
• To zoom on a specific area, perform a left mouse click and maintain the mouse button pressed. The zoom area is defined by dragging the mouse cursor over a certain portion of the plot while the left mouse button is pressed. The zoom area is displayed by a light blue rectangle.
• To achieve a horizontal autoscale, perform a right mouse click and maintain the mouse button pressed. Then move the mouse cursor horizontally. A light grey horizontal strip will appear. Release the mouse button to perform the horizontal autoscale.
• To achieve a vertical autoscale, perform a right mouse click and maintain the mouse button pressed. Then move the mouse cursor vertically. A light grey vertical strip will appear. Release the mouse button to perform the vertical autoscale.

Rolling plot module 

The rolling plot module displays a downsampled version of the control variables. It allows the monitoring of the selected variables for up to several days. You can typically use it to monitor the long-term evolution of your power system and keep an eye on critical variables at all times.

Rolling plot module interface

Rolling plot module shortcuts

• To add multiple variables to a plot, open the user variable section of the project pane. Keep the ctrl key pressed and perform left mouse clicks to select the desired variables. Alternatively, perform a left mouse click on the first variable to select, maintain the Shift key pressed, and do a second left mouse click on the last variable to select. These selected variables can then be dragged and dropped into a plot.
• To zoom in and out along the horizontal axis, place the mouse cursor where you want to zoom. Then use the wheel of your mouse to zoom in or out around the location of your mouse cursor.
• To zoom in and out along the vertical axis, place the mouse cursor where you want to zoom. Then press the ctrl key, and use the wheel of your mouse to zoom in or out around the location of your mouse cursor.
• To zoom on a specific area, perform a left mouse click and maintain the mouse button pressed. The zoom area is defined by dragging the mouse cursor over a certain portion of the plot while the left mouse button is pressed. The zoom area is displayed by a light blue rectangle.
• To achieve a horizontal autoscale, perform a right mouse click and maintain the mouse button pressed. Then move the mouse cursor horizontally. A light grey horizontal strip will appear. Release the mouse button to perform the horizontal autoscale.
• To achieve a vertical autoscale, perform a right mouse click and maintain the mouse button pressed. Then move the mouse cursor vertically. A light grey vertical strip will appear. Release the mouse button to perform the vertical autoscale.

Variables module

The variable module grants quick access to selected control variables. It also allows you to modify the user variables without the need of rebuilding your control code. Additionally, it displays detailed information on user variables such as the min and max.

This module can contain one or more sections to conveniently sort the user variables.

• To add a new section simply click on the + button on the bottom left of the module.
• To change the columns displayed in a section, right-click on the header of the section and select/deselect the desired column.
• To add a variable to a section, simply drag and drop a variable from the project pane directly into the desired section.
• To remove a variable from a section, simply right-click on any cell of the desired variable, and select “remove variable”.
• Signals connected to a Probe block are listed under the probe type and signals connected to a Tunable parameter block are listed as parameter. Variables of type parameter, can be modified in run-time by double-clicking on the Data cell of the desired variable.

DAC module 

The DAC module allows the user to apply a given variable to one of the four analog outputs of the B-Box RCP. The values applied to the analog output are specified in volts -5V to 5V the output is saturated beyond these limits. Further hardware specifications are available in the B-Box RCP datasheet. 

Logs module

The logs module displays every message reported by your controllers. Whether it is misconfiguration details, software and hardware faults, or custom user messages.

Export data as CSV or MATLAB figure

Cockpit offers the possibility to export the signal acquired with the Scope and Rolling plot modules as a CSV or directly as a MATLAB figure. 
For the scope module, Cockpit will export each and every sample of the scoped signals. As a reminder, the signal acquisition is performed at the control task rate. 
For the rolling plot module, Cockpit will also export each and every sample of the acquired signals. As a reminder, the signals are acquired at 20 Hz. However, this is a best effort and the data may be acquired at lower frequencies. Therefore, it is common to observe in the exported CSV files timestamps that are not at 20 Hz.

To export data from a rolling plot or a scope module, simply click on the Export CSV or MATLAB figure button located in the Import/Export tab of Cockpit’s top bar, as displayed below.

Then select the desired plots to export and chose the folder where the MATLAB figure or the CSV file will be saved.
Note that the CSV file is also saved when exporting data as a MATLAB figure. 

Extra step when exporting as a MATLAB figure:

If several instances of MATLAB are installed on your computer you will be notified with the following pop-up message. Simply select the desired MATLAB version. 
The export as MATLAB figure feature only supports MATLAB versions starting at version R2019a.

Once the data has been exported, a MATLAB file .mat figure is created in the selected folder. MATLAB is then automatically launched with a new workspace set to the chosen folder. Finally, the MATLAB figure is automatically displayed.

Note: For further use in MATLAB, the signals data is available in the .mat file. This file contains a table of structures (one for each exported signal). The structure is formatted as such: 

Name: 'Ig_a'
Scale: 1
Offset: 0
Unit: '-'
Plot: 'Plot 1'
Color: '#6c4092'
Module: 'Scope'
ModuleType: 'Scope module'
Time: [4000×1 double]
Data: [4000×1 double]
Code language: Matlab (matlab)

To plot this data in a new figure simply type the following commands in the MATLAB command window:

>> load('plot_1.mat')
>> figure
>> plot(Ig_a.Time, Ig_a.Data)
Code language: Matlab (matlab)

Targets timings

The Timings window provides a graphical representation of the various computation and communication delays involved in the B-Board PRO and B-Box RCP controllers during run-time.
It is particularly useful to observe the delays involved in the control dynamics of the system as explained in Identifying the discrete control delay (PN142). The control parameters, such as the \(K_p\) and \(K_i\) of a PI control implementation as shown in Basic PI control implementation (TN105), can then be adjusted accordingly.

Below are screenshots of the Timings window when running the model Central PV inverter (AN006) in two scenarios. This window can be opened from the three dots menu of a project pane.

The timing graph accurately represents the delays involved in the execution of the user control code.

• CLOCK_0 timer represents the value of the clock generator counter. CLOCK_0 is used as the time base for the sampling events and the control task routine execution. In most cases, the PWM modulators are also based on CLOCK_0.
• Sampling shows the sampling events, i.e. the instants where the ADCs sample the input analog signals. In the example above, the sampling phase is set 0.5 so the sampling occurs in the middle of the period of the PWMs that are based on CLOCK_0. The oversampling enables the possibility to set up multiple sampling events between each control task execution as explained in Oversampling (PN154).
• ADC acquisition delay shows the delay between a sampling event and the availability of the values in the FPGA. It comprises the analog-to-digital delay and the results transfer to the FPGA delay. This value can be set to 2000 ns (B-Box RCP or B-Board PRO) or to 500 ns (B-Board PRO) from the CONFIG block.
• The Read delay shows the time needed to perform FPGA-to-CPU transfers. These tasks are executed right after the ADC results are available in the FPGA. The values transferred are typically the ADC measurements, the GPI values, or the angle decoder output.
• The Processing delay shows the time the CPU spends executing the interrupt routine. To execute the CPU-to-FPGA transfers as early as possible (and reduce the overall response delay), the interrupt routine is separated into two phases:
  • The control task execution is the delay to execute the user control model and update the modulation parameters and other FPGA values. The CPU-to-FPGA transfers are executed right after, in parallel with the post-processing execution.
  • The post-processing execution is the delay necessary to perform all the tasks that are not directly involved in the control algorithm. It includes the datalogging execution, the CAN communication, etc. 
• The Write delay shows the time needed to perform the CPU-to-FPGA transfers. These tasks are performed once the control task execution is over. The values transferred are typically the PWM modulation parameters (duty-cycle, phase), the GPO values, or the DAC values.

At the top of the window, the following information is displayed:

• CLOCK_0, CLOCK_1, CLOCK_2, and CLOCK_3 show the configured frequency of the four Clock generators.
• The CPU state displays the current operating state of the controller.
• The Control task routine execution frequency and period are also displayed. Note that the control task is always mapped on CLOCK_0.
• The Sampling shows the frequency and period of the ADCs sampling. It allows the user to visualize if the oversampling is configured or not.
• The CPU load represents how much time the CPU spends in the interrupt routine. Safety mechanisms are implemented to detect CPU overload. An overload can result from a control algorithm being too complex or an execution frequency being too high.
  The min, max, and avg values are computed on a window of one second.
• The Cycle delay represents the delay between the sampling event and when the newly computed data are available in FPGA (ADC acquisition delay + FPGA-to-CPU transfers + control task execution + CPU-to-FPGA transfers). This value can be used by the user to compute the control delay and the total loop delay, as explained in Identifying the discrete control delay (PN142).
  The cycle delay value is precisely measured directly from within the FPGA. The min, max, and avg values are computed on a window of one second.

Other features

How to launch a user code at controller start-up

In some cases, it can be interesting to automatically start a user code when turning on your imperix controller. To do so, follow the procedure below:

• Launch the user code and connect to the target as usual by pressing Ctrl+B on Simulink or Ctrl+alt+B on PLECS.
• Once the code is running on the target, open the Target configuration window from the three dots menu of the project pane.
• In the section User code saved on SD card, click on the Save the currently running code button to save the current code on the SD card inside of the controller.
• Click on the checkbox Load at startup to automatically launch the code when the controller is powered on.

In a few words, this will save the control algorithm on the SD card inside your controller. Then, when it is turned on, it will automatically load and start the code from the SD card.

How to load a custom FPGA bitstream

In some cases, it is interesting for the user to offload all or parts of the computations from the CPU to the FPGA. Doing so often results in much faster closed-loop control systems.

To do so, follow the procedure below:

• Launch the user code and connect to the target as usual by pressing Ctrl+B on Simulink or Ctrl+alt+B on PLECS.
• Once the code is running on the target, open the Target configuration window from the three dots menu of the project pane.
• In the section FPGA bitstream saved on SD card, click on the Browse button and select the desired bitstream. The bitstream will be uploaded into the SD card of the controller. A check in the Load at startup checkbox indicates that the target will load the imported customized bitstream at the next power cycle of the target instead of the standard one.

Further information on how to develop power converter control algorithms in FPGA can be found on the Getting started with FPGA control development page.