Scope Module

Table of Contents

This article describes how to use the Scope module of imperix Cockpit to interact with the user code running on imperix power converter controllers, namely the B-Box RCP the B-Board PRO, the Programmable Inverter and the B-Box Micro. This page provides a detailed explanation of all of the module’s features.

For new users, it is recommended to read the following articles beforehand to get started with the imperix software development kit (SDK) and imperix Cockpit monitoring software:

Scope module basics

The Scope module allows the user to display control signals on an oscilloscope-like interface by capturing and plotting 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 that each and every sample is scoped.

To start the acquisition, simply drag and drop a variable from the project pane directly to a plot of the scope module.

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 one variable for 21 minutes or 32 variables (maximum number of scoped variables) for 40 seconds.

Activating the scope will affect the CPU load. This might be of concern if the CPU load is already close to 100% prior to the activation of the scope module.

Scope module interface

The plot preview shows an overview of all the scoped signals. The vertical axis of the preview is automatically scaled so all of the signals fit the plot. The plot preview can be collapsed to optimize space when using Cockpit on a small monitor.

This is the area where the scoped signals are displayed. User variables can be dragged and dropped from the project pane into a plot, which will add them to the acquisition and display the corresponding samples in the area.
The x-axis range (when no zoom is applied) is defined by the Window [ms] field of the Trigger pane (located in the right bar). If multiple plots are created, their x-axis will always remain synchronized, including when zooming.
The user can remove a variable from a plot from the Scope tab of the bottom bar or through the variable plot context menu accessed by right-clicking on the plotted signal.

The plot containing the trigger signal will have two extra cursors added to it. The user can move these cursors to adjust the trigger level and position to set the trigger point (more information in the trigger configuration chapter).

Starts or stops the acquisition. Note that at least one variable must be added to a plot for the acquisition to start.

Force the acquisition of one window, bypassing the trigger mechanism. This is useful when the trigger is configured in Normal or Single mode.

Perform an autoscale on the horizontal and vertical axis, ensuring that the acquired signals fit in the plots.

Perform an autoscale on the horizontal axis of every plot while keeping the vertical axis unchanged.

Perform an autoscale on the vertical axis of every plot while keeping the horizontal axis unchanged.

When switched on, this feature performs a vertical autoscale on every plot after each new acquisition window.

When switched on, a pair of slideable vertical cursors are shown. The cursors allow the user to mark an interval inside which several metrics are calculated on the scoped signals and displayed in the bottom bar.

Clicking this button opens a window that allows the user to create a new plotted variable based on a mathematical formula. The formula can combine any of the variables currently displayed inside the Scope module.

Clicking this button opens a window where the user can examine the signals acquired by the scope in the frequency domain. The displayed spectra correspond one-to-one with the user and math variables displayed in the scope.

Displays the current acquisition state. The possible acquisition states are:

Stopped: the acquisition is stopped. The displayed data is from the last acquisition.
Waiting: the acquisition has started and is now waiting for a trigger event to occur.
Acquiring: the trigger event has occurred and the signals are being captured.
Offline: the target is disconnected from the host computer or the user code is not running on the target.

The loading bar displays the acquisition and transmission status of the acquired window.
Note that it is normal to see the loading bar partially filled and blocked when the acquisition is in Waiting state.

Creates an empty plot area at the bottom of the scope module.

The scoped variables are displayed in the Scope tab of the bottom bar. The bottom bar Scope tab menus allow the user to:

Modify each variable’s display style, scale multiplier, offset value, and measurement unit
Remove a variable from scope
Toggle a variable’s visibility without removing it
Move variables between scope plot areas

In addition to this, the position and the distance between vertical cursors are displayed here, along with the metrics calculated inside the interval defined by the cursors if they are enabled. If the cursors are not enabled, the metrics are calculated over the entire acquisition window.

Advanced scope features

The Scope module offers several advanced features, accessible through the plot footer buttons and the right bar menus.

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.

Defines the acquisition window length and changes the x-axis length. This value affects the total number of acquired points.

Defines whether to trigger on rising, falling, or both edges of the trigger signal.

This field defines on which signal the trigger will be applied. This signal will be marked with (T) in the plot legend and can also be changed by right-clicking on a variable and setting it as a trigger through the context menu.
Note that only variables added to the scope module are present in this drop-down list.

Defines the trigger acquisition mode.
In Normal mode, a window is acquired if the input signal reaches the defined trigger point.
In Auto mode (which is set by default), the trigger acts like in normal mode. However, the window acquisition is forced by a timer set to 100 ms, which ensures acquisition even if no trigger event occurs.
In Single mode, a single window is acquired if the input signal reaches the defined trigger point. After that, the acquisition is stopped.

Change these values to set the trigger point. Alternatively, the trigger position and level can be adjusted directly in the plot area by moving the trigger level and position icons.

Transient generator configuration

The transient generator allows the user to apply a predefined signal on multiple user variables, provided they are connected to the Tunable parameter block. The signal is defined as a sequence of transient events at different positions within the scope acquisition window.

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.

Scope module containing the result of a transient sequence (on the left). Transient configuration pane (on the right)

This field defines on which variable the defined signal will be applied. In this example, the variable Ig_d_ref is used.

This field defines a vector of positions at which the transient signal values will be applied. In the example, the events are set at 50ms, 100ms, and 150ms.

This field is a vector of values that will be applied on the transient variable. In the above example, the values [10, 5, 15] are applied at [50, 100, 150] ms. The initial value of the tunable variable Ig_d_ref was set to 2.5 and that value is held until the first event at 50ms.

Please note that, since Cockpit version 2024.3, this field defines the exact values at the corresponding positions, and not how much the signal should jump at those positions. The initial value of the variable is relevant only in terms of determining the applied values between the beginning of the acquisition window (0ms) and the first defined transient event.

This field defines whether the set values are held until the next event (the Steps option) or used to define linear ramps between the event points (the Linear option). After the last event, the set value is held until the end of the acquisition window regardless of the picked interpolation option.

The transient generator allows entering multiple transient sequences on different variables.
In this example, the second transient sequence is unused.

These two buttons allow the removal or the addition of transient events. There is no limit to the number of transient events.

Clicking the preview button toggles the transient preview in the scope. The transient preview of a given variable shows up as an editable signal in the same plot area as the original acquired variable. Toggling the preview and editing it does not fire the transient or affect the scope acquisition in any way.

Clicking on this button will initiate the transient sequence on all transient variables. Once the sequence is finished, the acquisition will be in Stopped state while the transient variables will go back to the value that was set before the transient was fired.

Defining transients graphically

Starting from Cockpit version 2024.3, the transient input signal can be set using an interactive graphical interface. Clicking the preview button or any of the transient event fields causes the transient preview to show up in the scope, provided that:

The transient events and transient event definitions are valid
The variable set in the Variable field is added to the Scope

Transient preview from the previous example after selecting the Linear interpolation option and dragging one transient event point

Once the preview shows up, the transient event points, if any are set, will show up as large dots. Using the mouse, the dots can be dragged to set the transient event position and value in one move. To add new points, double click near the editable transient signal and a new dot will show up. To remove existing points, right click on the point and select the ‘Remove point’ option from its context menu.

All of these actions immediately update the corresponding transient event in the right bar. Editing the transient preview does NOT affect the actual Tunable variable or the scope acquisition in any way, unless the ‘Fire transient’ button is pressed. To exit the transient preview mode without firing the transient, simply press the Transient preview button in the right bar again.

Cockpit Formula Builder

The Formula Builder allows the user to create math variables that are then added to the Scope module. Math variables are created based on a mathematical formula that can include any of the currently Scoped variables.

The math variables are calculated on the PC side after the acquisition of a scope window. This alleviates the need to define every variable to monitor in the user code, saving on hardware resources while still allowing the user to track them live through Cockpit. This also saves time, as new math variables can be added or their formula edited without having to recompile the user code.

With the exception of constant expressions and scalar-valued functions, all of the mathematical operators and functions provided by the Formula Builder are applied element-wise. This means that the formula is applied to each and every sample of the variables included in the expression, creating a new signal to be plotted in the scope.

To create a Math Variable, it needs a valid name. The name has to be unique and cannot be edited after creation.

While not necessary for Math Variable creation, the unit of the new variable can be set while building its formula. If not set here, the unit can always be edited, like with any other variable, from the bottom bar.

This option allows the user to choose where the created Math Variable should be plotted or even create a new area to plot it in. After creation, the Math Variable can be moved around between plots like any other scoped variable.

This button controls the appearance of the list of formulae of previously created Math Variables.

Here, the formula is defined either by typing it or clicking on the options in the menus below.

The list contains all of the formulae of the previously successfully created Math Variables.

The star next to each of the formulae allows us to favorite it, making it available in all projects. Non-favorited formulae disappear when the scope they were used in is deleted.

This menu contains all of the binary operators usable for building a math formula.

This list contains all of the functions usable while building a math formula. The functions are grouped into three categories:

General math is a collection of elementary (abs, exp, log, sgn, sqrt) and rounding functions (ceil, floor, round, trunc)
Trigonometry includes all of the typical trigonometric and hyperbolic functions, along with conversion functions between degrees, radians, and gradians
Scalar-valued functions are grouped based on the fact that they all evaluate into one number.

This list contains all the variables currently displayed in the scope, including acquired user variables and other math variables. The mathematical formula can use all the variables in this list as operands.

As the math formula is being typed, the errors provided by the formula parser are displayed here. None of these errors are critical to Cockpit operation; they serve as guidance to creating a math expression that can be properly interpreted and used to evaluate the new Math Variable.

Clicking on Save variable will attempt to save the Math Variable with the currently entered parameters. If successful, the window will close, and the saved variable will be displayed in the selected Scope plot area.

Pressing the Enter key while the focus is on the formula field is a shortcut to clicking Save variable.

Clicking on Cancel will close the Formula Builder window without saving anything.

Pressing the Esc key while the focus is anywhere in Cockpit is a shortcut to clicking Cancel.

Scope tips and tricks

To add multiple variables to a plot, open the user variable section in the project pane.
Keep the ctrl key pressed and click on the desired variables to select them.
Alternatively, click on the first variable to select it, keep the Shift key pressed, and click on the last variable to select. These selected variables can then be dragged and dropped into a plot all at once.
To zoom in and out along the horizontal axis, place the mouse cursor where to zoom. Then, use the mouse wheel to zoom in or out around the location of the mouse cursor.
To zoom in and out along the vertical axis, place the mouse cursor where to zoom. Then press the ctrl key and use the mouse wheel to zoom in or out around the location of the mouse cursor.
To zoom on a specific area, click and drag to draw a blue rectangle over the zoom area.
To achieve a horizontal autoscale, right-click and drag horizontally. A light grey horizontal strip will appear. Release the mouse button to perform the horizontal autoscale.
To achieve a vertical autoscale, right-click and drag vertically. A light grey vertical strip will appear. Release the mouse button to perform the vertical autoscale.
Many of the Scope functionalities can also be accessed through context menus by right-clicking on a plotted variable or on the empty space in the plots.