This document presents a general overview of the DataLogger functionality, its intended use, and its features based on an example project (rtdemo1) available in the example folder with any RT-LAB distribution/release.

Introduction To The DataLogger

The DataLogger is a feature for data acquisition provided with RT-LAB from release version 11.3 upwards.

Its intended use is to capture signals according to a trigger condition and to record them to data files for analysis during simulation or post-simulation. It records multiple signals' evolution during the simulation in order to give users the ability to validate their design during simulation or in a post-processing phase.

The acquired signals can be recorded into three file formats: MAT (Matlab), CSV (Excel) and OPREC files. Additionally, the DataLogger captures transient phenomena and anomalies when they occur, which provides options to trigger the acquisition of data.

Some of its advantages include, but are not limited to:

• Usable with either triggered or non-triggered acquisition
• Low impact on real-time simulation performance
• Capable of capturing signals with trigger conditions that occur at any moment during the simulation, including the very first calculation steps
• Capable of logging multiple signals' acquisition within the same model and from multiple models
• Handles multiple signal groups and multiple acquisition rates based on ratios of the simulation step
• Parametrizable recorded file characteristics (Maximum Size, File Naming, etc.) and recorded duration (seconds, minutes, hours, etc.)
• Provides clear recorded data regarding file naming, models’ signal names, data types and their respective units, scaling, aliases of these signals, and trigger information for ease of management.

Exploring The DataLogger

This quick guide is based on the rtdemo1 example project available with any RT-LAB distribution. This guide is also based on the use of RT-LAB version 2022.1.0.348.

Opening the rtdemo1 Model

• Open RT-LAB.
• Click File > Quick start-up project; a dialog box appears. Rename the project if needed; otherwise, keep it as it is and click Ok.
• The project loads and you are able to compile the rtdemo1 model as a first step: right-click the model, then Simulation > Build.

Identifying the Elements in the Global View

In the hierarchical Project Explorer tab, to the upper left, you will be able to see the Models, I/O interfaces, Panels, and Recorders.

In this quick guide, we are interested mainly in the Datalogger's Recorders and the Models sections and their corresponding subsections.

• Expand the Models and Recorders trees in the left margin to view their contents, as above.
• Note that the Models tree contains rtdemo1, and, if you expand it, the two main subsystems in this example; sc_user_interface (user interface) and sm_computation (the calculation part of the simulation) blocks. 
  
  • Note also that the Recorders tree contains a RECORDER item by default IF the model has been built.
  • If the model has not been built/compiled, do so now by right-clicking Models > Simulation > Build.
• The recorders are named after the model name in conjunction with the subsystem block names (sm_computation in this case), and, if there is more than one recorder/subsystem, they are named after each subsequent subsystem (sm_ or ss_) block.
• By default, each Recorder contains one SIGNAL_GROUP, named SIGNAL_GROUP_1.

Choosing Signals to Log

• Expand the sm_computation tree node, and then expand the node down to the signal level.
• Choose which signals you would like to log by exploring the tree nodes and sub-nodes of interest.
  
  • Note that users choosing to locate the signals through Simulink models need to follow the signal they want to log back to its source in the block diagram in order to discover which block it’s listed under.
• In this example, below, we've expanded the Gain1, Gain Kd, Gain Ki, and Gain Kp blocks in order to explore the exit signals for each of the linked blocks.
• Select multiple signals by CTRL-clicking them one by one.
  
  • To remove individual signals from your selection, CTRL-click them again.

Assigning Signals to a SIGNAL_GROUP

A Signal Group is a group of signals of particular interest to a user. Users may want to group signals together for logging and observation because their interaction and extended comparison to one another–and to other signal groups--is of interest.

To add signals to a signal group:

• Right-click the group of signals you have selected in the previous step, and select Record. 

OR

• Click SIGNAL_GROUP_1 in the left tree-view menu to open the Quick Project Recorder tab, and, with the desired signals selected, drag them into this tab.

• For the case where you are using the first method (right-clicking the signals), you will have two options, or possible views, depending on the number of SIGNAL_GROUPs you have under the recorder associated with this model:
  
  • If you have just one SIGNAL_GROUP, the signals are routed automatically to the only existing SIGNAL_GROUP.
  • If you have multiple SIGNAL_GROUPs under your recorder, a dialog box appears, asking you to choose a SIGNAL_GROUP to assign the selected signals to, as in the screenshots below.

• Select the preferred SIGNAL_GROUP and click OK.
• The signals are added to the chosen/default SIGNAL_GROUP.

Verify that the assignment was properly set by:

• Expand the Recorders tree node, then your recorder to reveal the SIGNAL_GROUP_1, where you just added these signals. 
• Double-click SIGNAL_GROUP_1 to open the associated variable table which lists all the signals associated to this signal group.
• Examine the properties of this signal group in the lower right window.

Using the Recorder Tab Controls

To the upper right of the RT-LAB interface, you will find a Recorder window as shown below.

If it is not currently visible, double-click Recorder_[Subsystem_name] in the Recorders list.

By default, the Recorder tab has one SIGNAL_GROUP listed for each Subsystem sm_ or ss_ block, and a display panel to the right. You will notice the addition of SIGNAL_GROUP_1.

Managing the Recorder Configuration

Settings available when General is selected in the Folders column of your recorder configuration panel:

• The checkmark to the right provides a Configuration Check dialog function that gives feedback about whether the actual recorder configuration is correct or not.
• The + and - marks to the right of the Folders tab expand and collapse the tree structure and all nodes downstream.

Recording Mode

The default recording mode. The recording mode can be set independently for each signal group. This general setting is used when the signal group recording mode is set to "inherit".

• Automatic: data recording starts automatically according to trigger configuration
• Manual: recording start on demand, as an example from an API call.

No data loss mode

The No data loss mode guarantees that there are no samples lost between adjacent acquisition frames. This model is available if the Real-Time simulation mode is set to "Simulation" (non real-time simulation). See also Executing Models

The General Tab

The General tab has a list of Parameters and Values. The values column is editable, and you can choose between the Basic and the Advanced modes, both shown below:

• In Basic mode, you have only one option: whether to activate the No data loss mode or not, by selecting/unselecting the checkbox.

• To select Advanced mode, click the pull-down to the right of the Mode label:

• In Advanced mode, you will notice an additional option;
  
  • Show console for DataLoggerTool process: If checked, launches a console showing the DataLogger process messages, visible only when the model is loaded or running (Windows only). Target console is not shown.

Managing Recorder Configuration (Signal Groups)

Having multiple groups provides the capacity for storing various sets of signals with different acquisition configurations. Users can add/remove groups so that they can easily store various signals with different properties such as sampling rate, trigger, etc.

When the Signal Groups tree node is selected, you can manage the SIGNAL_GROUPs under the subsystem named in the Associated subsystem field.

The settings available when Signal Groups is selected in the Folders column of your recorder configuration panel are listed below:

Managing the Recorder Configuration (SIGNAL_GROUP level)

When one SIGNAL_GROUP tree node is selected, you can manage the settings associated with that particular SIGNAL_GROUP.

Settings available by default when a particular SIGNAL_GROUP is selected in the Folders column of your recorder configuration panel are listed below:

To the lower right of the RT-LAB interface you will find a Recorder window.

The columns in this view indicate the parameters explained in the following table:

Comments on configuring trigger signals

1. Using the Edge type of Trigger function, the user should be aware that the signal which is selected as the trigger inside the signal group, should actually change it's polarity and acquire a value that is of the polarity specified inside the Trigger polarity box. If, for example, the Positive option for Trigger polarity  is chosen, but the trigger signal starts with a positive value and stays positive till the simulation ends, there will be no recording triggered.
   
   
2. If a value of 50 is chosen for Pre-trigger percentage, along with Frame length value of 10 (Frame length unit as seconds) then the recording will start only after 5 seconds (50% of the 10s) when the trigger signal meets its condition (depending on the Trigger function chosen) .

Starting, Recording & Retrieving Recorder Files

• After the acquisition settings are set properly in the DataLogger Recorder parameters, the simulation model can be loaded onto the simulation target and the simulation can be executed.
• The data logging feature is launched at the same time as the model and can be used while the simulation is running: manual acquisition start, signal visualization, logging files retrieval can all be recorded for post-simulation analysis.
  
  A red -dot appears on the icon preceding the signal group name which are configured properly and records data as and when the requirements set inside the signal configuration settings is met.
  
• Users may choose to use the checklist below to ensure the DataLogger is correctly configured and ready to start.

• When all the actions above are checked, load (CTRL + Alt + L) your model and execute (CTRL + Alt + S) it.
• After simulation completion and model reset, a new tree node, named data, appears after the Recorders tree node at the same level.
• This tree node contains the files generated by each recorder. If you have multiple recorders and/or multiple SIGNAL_GROUPs with signals assigned to them, you will have the corresponding number of files.
• Otherwise, if you have only one recorder and one SIGNAL_GROUP with assigned signals to log, as in the case below, you will have only one generated file in the format specified in your parameters.  

At this point, if users double-click the OPREC file, it opens in ScopeView and they can examine the contents of the file obtained during simulation.

If the file has several frames, ScopeView enables the viewing of all frames.

Users can also manually open ScopeView files with the suffixes .mat, .csv and .oprec. 

Recording in Manual Mode

• Recording in Manual mode is equivalent to recording when using a trigger, except that the trigger is based on a human intervention through the GUI, and more specifically on the signal_group or on the recorder levels on the Recorders tree.
• When the model is running and being manually recorded, the user can right-click on the recorder/signal_group, and a menu appears containing two options; start recording and stop recording as shown in the two screenshots below.
• If the user right-clicks the recorder, an equivalent menu appears, except that the action applies to all the signal_groups configured in Manual mode under that particular recorder, as shown in the third screengrab.

File-naming with Multi-model Simulation and/or Multiple Recorders/SIGNAL_GROUPs

When you are performing a multi-model simulation with logging, or you have multiple slave/master subsystems and you are also using the DataLogger, ensure that;

• All the ss_ and sm_ blocks have unique names, otherwise, you will not be able to correctly assign signals to log to the appropriate SIGNAL_GROUPs, and these signals will be not logged.
  If you choose to name your logs without using the auto-naming feature, ensure they have unique names to avoid overwriting data and/or data loss,

Known Limitations

• Recording of Real-Time simulation data is limited to 2GB for real-time simulation on real-time targets (32bit). When using localhost targets, there is no known limitation to the logging file size.
• Occasional freezes in RT-LAB software may be experienced, especially with a high number of signals/signals_groups to log.
• When logging using vectors, all the elements of the vector are logged and there is no possibility to select only a subsection of the vector for recording.
• The export format to .mat file is very limited for now. A workaround is to use the .csv export format or to exploit .oprec files with MATLAB functions (cf. next section).

Exploiting OPREC files with MATLAB

Two MATLAB functions : OpRecInfo and OpRecRead are available to retrieve information and/or read data from OPAL Record files (.oprec).

Script usage

OpRecInfo

This script allows retrieving metadata from .oprec files.

Parameter

• Full Oprec file path

Usage

Just provide a full path to the .oprec file to retrieve the following information:

• Time step (in seconds)
• Minimal timestamp (in seconds): first simulation step recorded.
• Maximum timestamp (in seconds): last simulation step recorded.
• The count and the list of all recorded signals.

Output example

OpRecRead

This script allows retrieving data for all recorded signals.

Parameters

• Full Oprec file path
• [optional] the first timestamp to read. By default, this corresponds to the timestamp of the first recorded step.
  This value is adjusted in case the specified timestamp is lower than the timestamp of the first recorded step.
  This parameter is mandatory when the last timestamp is specified (see below).
• [optional] the last timestamp to read. By default, this corresponds to the timestamp of the last recorded step.
  This value is adjusted in case the specified timestamp is greater than the timestamp of the last recorded step.

Usage

Provide two output variables to store the data read from the .oprec file:

• The first variable will store the signal names and types.
• The second variable will store all the step data for the signals in the exact same order as in the first variable.

Output examples