Introduction

This chapter serves as an introduction to the APIs used in RT-LAB. The API provides a set of functions, constants, error codes and structures. You may use these functions and constants to perform various tasks such as creating your own GUI to interact with the simulation, creating test automation scripts using Python, for example or integrating RT-LAB with other software.

All API C functions have the “Opal” prefix in their name. However, for specific language such as Python, the prefix has been removed because the functions are grouped inside a module or a class. For instance, OpalCommand becomes Command in Python. All functions will be referred to without the “Opal” prefix in this chapter.

Important: Many of the API functions rely on the MetaController, so it is primordial to make sure it is running before invoking any API calls.

Related components

The RT-LAB API provides a standard interface to interact with RT-LAB. The API is available in several programming languages. However the API is writen in C code and any language that supports C-function calls may interface with the RT-LAB API.

The RT-LAB API interacts with RT-LAB objects through the Controller process. Many APIs may interface through the same Controller concurrently. The Controller will manage all the commands sent to the model and values received from the model.

Open

RT-LAB states

An RT-LAB model may be in different states depending on the actions performed by the user.

RT-LAB states can be grouped in two categories:

• Disconnected and connected states. Before performing an API call, the project is set to the disconnected state. This is the initial state and the final state.

• Intermediate states when configuring, compiling or loading.

The next illustration depicts the different states available when using the RT-LAB API. The main functions which enable you to change a state are displayed on the transitions

Open

RT-LAB model’s state

List of Functions Available for Each State

Here are the functions available depending on RT-LAB’s state, Please note that certain functions are only available when RT-LAB is in a specific state.

API states

Disconnected

This is the initial state of the API. In this state you can get the list of active projects and either connect to one or create a new project instance.

• Connect (deprecated)

• ConnectByName (deprecated)

• GetActiveModels (deprecated)

• SetCurrentModel (deprecated)

Connected

Once the API is connected, you can modify the model’s settings.

• Disconnect (deprecated)

Model states

Unloaded

In this state, the model could be configured to prepare the simulation.

• AddExtraFile

• Load

• RemoveExtraFile

• SetNodeCpu

• SetNodeMapping

• SetNodeXHP

• SetSimulationMode

• SetTargetPlatform

• StartCompile

Compiling

In this state, settings cannot be modified.

• AbortCompile

• DisplayInformation

Loaded

When the model’s executable is started on a target, the model’s state becomes loaded. In this state, parameters and signals could be changed on the fly. Data acquisition could be performed for real-time or offline analysis.

• Execute

• GetAcqGroupSignals

• GetAcqGroupSyncSignals

• GetAcqTrigger

• GetBlob

• GetControlSignals

• GetParametersByName

• GetSignalsByName

• GetValueByAlias

• LoadParameters

• SendBlob

• SetAcqTrigger

• SetControlSignals

• SetParameters

• SetParametersByName

• SetSignalsByName

• SetValueByAlias

• SingleStep

• Snapshot

• Pause

• Reset

Available at any model state

These functions could be called anytime when the API is connected to a model.

• Command

• GetAttributes

• GetChildren

• GetDefaultAttributes

• SetAttributes

• RestoreAttributes

• CreateAlias

• DeleteConnHandle

• ExecuteConsole

• ExecuteMatlabCmd

• FreeMemory

• GetAcqBlockLastVal

• GetAcqSampleTime

• GetAcquisitionControl

• GetAliasDescription

• GetBlobsControl

• GetConfigurationControl

• GetConnHandle

• GetControlSignalsDescription

• GetCurrentModel

• GetExtraFiles

• GetLastErrMsg

• GetModelState

• GetMonitoringControl

• GetNodeCpu

• GetNodeXHP

• GetNumAcqGroup

• GetNumSignalsForGroup

• GetParameterControl

• GetParametersDescription

• GetPauseTime

• GetRtlabVersion

• GetSignalControl

• GetSignalsDescription

• GetPhysNodeList

• GetStopTime

• GetSubsystemList

• GetSystemControl

• GetTargetFile

• GetTargetNodeSystemInfo

• GetTargetPlatform

• GetTimeInfo

• OpalIsOriginalModelOpen

• LoadAlias

• LoadAliasDescription

• LoadConsole

• LoadOriginalModel

• LoadParametersDescription

• MacroGetOptions

• MacroGetStatus

• MacroPlay

• MacroRecord

• MacroSetOptions

• MacroStop

• NewConnHandle

• PauseConsole

• Ping

• PutTargetFile

• RegisterDisplay

• ReleaseFunctionControl

• RemoveAlias

• RenameAlias

• ResetConsole

• ResetOriginalModel

• SaveAlias

• SaveParameters

• SetAcqBlockLastVal

• SetAcqWriteFile

• SetConnHandle

• SetDecimationFactor

• SetFillDecimation

• SetMatlabRelease

• SetNotificationCallback

• SetNumberValues

• SetPauseTime

• SetTimeFactor

• StartExecutable

• StopConsole

• StopExecutable

• SetStopTime

• TakeFunctionControl

• WaitExecutable

Groupings

The functions are divided into several types. These types refer to the order in which you interact with the model.

The available types are:

Generic

• Command

• GetAttributes

• GetChildren

• GetDefaultAttributes

• SetAttributes

• RestoreAttributes

Model Selection

• Connect

• ConnectByName

• DeleteConnHandle

• Disconnect

• GetActiveModels

• GetConnHandle

• GetCurrentModel

• NewConnHandle

• SetConnHandle

• SetCurrentModel

Model Preparation

• AbortCompile

• AddExtraFile

• GetExtraFiles

• GetNodeXHP

• GetPhysicalNodeList

• GetSubsystemList

• GetTargetPlatform

• RemoveExtraFile

• SetNodeCpu

• SetNodeMapping

• SetNodeXHP

• SetSimulationMode

• SetTargetPlatform

• StartCompile

Model Execution

• Execute

• GetModelState

• GetPauseTime

• GetStopTime

• Load

• Pause

• Reset

• SetPauseTime

• SetStopTime

• SetTimeFactor

• SingleStep

Model Interaction

The functions of this type can be further categorized as follows:

• alias

• blobs

• console

• monitoring

• original model

• parameters

• signals

Alias

These functions manage aliases.

• CreateAlias

• GetAliasDescription

• GetValueByAlias

• LoadAlias

• LoadAliasDescription

• RemoveAlias

• RenameAlias

• SaveAlias

• SetValueByAlias

Blobs

These functions manage blobs. The blobs are used to exchange data between the RT-LAB subsystem or between the host and the target.

• GetBlob (C only)

• GetBlobsControl (C only)

• SendBlob (C only)

Console

• ExecuteConsole

• LoadConsole

• ResetConsole

• StopConsole

Monitoring

• GetMonitoringControl

• Snapshot

Original Model

• IsOriginalModelOpen

• LoadOriginalModel

• ResetOriginalModel

Parameters

• GetParameterControl

• GetParametersByName

• GetParametersDescription

• LoadParameters

• LoadParametersDescription

• SaveParameters

• SetParametersl

• SetParametersByName

Signals

These functions manage signals. Control signals are signals that are transmitted by TCPIP from the console subsystem to the computation nodes. Acquisition signals are signals that are transmitted by TCPIP from computation nodes to the console subsystem (e.g. SC_xxx). For additional information please see Acquiring and Viewing Data in the RT-LAB User’s Guide.

• GetAcqGroupSignals

• GetAcqGroupSyncSignals

• GetControlSignals

• GetControlSignalsDescription

• GetSignalControl

• GetSignalsByName

• GetSignalsDescription

• SetControlSignals

Model Configuration

This type can be further categorized as follows: Acquisition and system.

Acquisition

• GetAcqBlockLastVal

• GetAcqSampleTime

• GetAcquisitionControl

• GetNumAcqGroup

• GetNumSignalsForGroup

• SetAcqBlockLastVal

• SetAcqWriteFile

• SetDecimationFactor

• SetFillDecimation

• SetNumberValues

System

• GetConfigurationControl

• GetSystemControl

• GetTimeInfo

Utilities

• CloseMetaController

• CreatePackage

• DisplayInformation

• ExecuteMatlabCmd

• FreeMemory

• GetLastErrMsg

• GetRtlabVersion

• GetTargetFile

• GetTargetNodeSystemInfo

• MacroGetOptions

• MacroGetStatus

• MacroPlay

• MacroRecord

• MacroSetOptions

• MacroStop

• Ping

• PutTargetFile

• RegisterDisplay

• ReleaseFunctionControl

• SetMatlabRelease

• SetNotificationCallback

• StartExecutable

• StopExecutable

• TakeFunctionControl

• WaitExecutable

API Controls

In order to modify any settings of the model, controls have to be granted. These controls allow synchronizing multiple API connected to the same model.

Here is the list of the available controls:

• system control

• monitoring control

• snapshot control

• acquisition control

• signal control

• parameter control

• blob control

Refer to the required control section for each API function to see what is the control to be granted before using this function.

For each control, there are 256 levels of priority. These priorities provide flexibility for API’s user when they want to create their applications. Refer to the TakeFunctionControl and ReleaseFunctionControl for more information about taking and releasing controls.

RT-LAB Controller Architecture

Controller Objects

• The Controller is made up of a variety of objects (see OP_OBJECT_TYPE). Each object contains any number of attributes (see OP_ATTRIBUTE). An object also can be the owner of other objects. For example, RT-LAB owns a Project and the Project owns Models.

• These objects are organized in a tree as shown in Figure 3. Each object has a unique Reference ID and contains attributes that may be accessed via Generic API calls (see OP_COMMAND).

• There are certain restrictions on the placement of objects in the Controller object tree. An important definition is that there is always exactly one (1) project per Controller. There may exist several Controllers concurrently, but every Controller will hold one project.

RT-LAB Global Object

This object is the root of the Controller’s object tree. All other objects are directly or indirectly children of RT-LAB. The attributes that RT-LAB contains are the default settings used when children are created. For example, if ATT_TARGET_PLATFORM of RT-LAB is set to REDHAWK_TARGET and a new Model is created, its default value will be REDHAWK_TARGET until modified.

Project Object

The project object mainly serves as a container for models. A project may contain anywhere between 0 and 253 models. It contains attributes.

Model Objects

Models contain a set of subsystems that are controlled as a whole to execute simulations. Models are defined by block diagrams developed with 3rd party application Matlab SimulinkTM.

Subsystem Objects

Subsystems contain various model sub-elements such as signals, block parameters, variables, etc. The block diagrams that make up a Model are divided into Subsystems to both structure the model and optimize block interactions by localizing certain operations to specific hardware (see the “Building Models” section of the User Guide).

Open

Controller Lists

Any controller object that has children necessarily contains lists. Figure 3 is only a simplified representation of the relationships between objects contained in the controller. When examined in more detail, each object contains a list for each type of children it owns. Figure 4 shows that Project does not directly own any Models but instead owns a Model List that in turn owns all the Models.

Open

• The same relationship is true for all Controller objects and lists. Objects can only own lists, and lists can only own objects. This organization helps classify objects' children by type. It also gives the user the liberty of adding or removing children from the parent object or from the intermediate list.

• As shown in Figure 5 all objects own exactly one (1) instance of each list type. Lists, however, may own any number (see OP_OBJECT_TYPE for exact upper bound) of objects, so long as they are all of the corresponding list type. For example, a Model List owns only Model objects, and a Model owns an Environment List, a Subsystem List and a Transfer File List.

Open

Reference IDs

• All object and list instances are addressable via their unique reference ID. Reference IDs are 64-bit integers that are globally unique. Reference IDs allow users to perform Generic commands on objects as well as attributes read or write operations.