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.

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.

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

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

• 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 one of the following 3rd party applications: Matlab SimulinkTM, EMTP WorksTM.

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).

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.

• 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.

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.
• There are several reference IDs that are static. RT-LAB will always have the same reference ID, OP_RTLAB_OBJ.
• All direct children of RT-LAB also maintain the same reference IDs, e.g. ProjectList, etc. Since each Controller only contains one project, it can be accessed unconditionally using OP_SINGLE_PROJECT.

Examples

API Interactions Using Generic Functions

Before any API function is called, the Controller is not yet running and therefore does not contain any objects. Before an active project is chosen, you can call GetActiveProjects() to list the current projects, or use NewProject() to create a new project or OpenProject() to open a project that was previously saved to disk or to connect to an active project. For more details on the arguments required for generic API calls see OP_COMMAND. After a call to NewProject(), the Controller will contain the objects shown in Figure 6. The project will contain the attributes shown in Figure 6.

The project that has just been created will have a specific reference ID. This ID will be returned by the NewProject function call. It can then be used to issue Generic API commands directly to the project. For example the GetAttributes function can be used to retrieve the values of the project’s attributes. The attributes that the project contains are illustrated in Figure 7.

New project attributes

• Once the project has been created, the next step is to add a model to the project. This can be done with the project ID and the CMD_ADD command, specifying the path to the model file (.mdl, .sbd or .ecf) or the model settings file (.llm) via the attribute ATT_FILENAME. Figure 8 shows the resulting controller. Since ATT_AUTOSAVE is false by default for projects, it may be a good idea to save the project manually via the SaveProject command.
• At this point, or at any point after creating a new project or opening an existing project, it is possible to close the connection with the Controller. This can be done with the CloseProject command.
• When it is required to connect to an existing project, the OpenProject command should be used. If the project is not currently open a new Controller will be created. If the project is already active in another Controller, a new connection to that same Controller is established and control is shared between clients.
• When navigating through the Controller object tree, the GetChildren function comes in very handy. Its purpose is to list all the objects or lists that are direct children of the specified ob ject or list. For example, if GetChildren was called with the project ID, a set of objects/lists containing the Model List’s ID would be returned.

Controller after first AddModel command

Other Examples

There are various examples available for the different supported languages. These examples can be found under RT-LAB_ROOT\Examples\Api (where RTLAB_ROOT is the directory where you installed RT-LAB).

Each directory contains a readme.txt file which describes the sub-folders as well as provides a description of the example.