Instrument

Create real-time instrument object

Since R2020b

Description

An slrealtime.Instrument object streams signal data from a real-time simulation running on a Speedgoat^® target computer to a MATLAB^® development computer. The object provides access to Object Functions, Instrument Object Properties, and Instrument Object Events related to the instrument in the real-time application.

The object provides access to methods and properties that:

• Find instrumented signals in the real-time application and add these to the instrument object.

• Add or remove signals in the instrument object.

• Connect signals in the object to axes or scalar displays.

• Add, get data from, or remove callbacks for signals in the object.

Creation

instrument_object = slrealtime.Instrument('appName') creates an empty instrument object for an existing real-time application appName.

Example: Create Instrument Object for Real-Time Application

instrument_object = slrealtime.Instrument() creates an empty instrument object without an assigned real-time application.

Example: Create Instrument Object without Real-Time Application

Properties

AxesTimeSpan — Axes time span in seconds

Inf (default) | double

The AxesTimeSpan property controls the time axis (x-axis) for all axes in an App Designer UI. When set to Inf, the signal value from the real-time application running on the target computer is displayed in the axes. If you change to a value, for example 10, the time axis for all axes is set to that value, for example 10 seconds.

AxesTimeSpanOverrun — Axes time span overrun response

scroll (default) | wrap

The AxesTimeSpanOverrun property controls the response for axes in an App Designer UI when the data overruns the AxesTimeSpan property value. When the AxesTimeSpan property value is Inf, the AxesTimeSpanOverrun property has no effect. When the AxesTimeSpan property value is set in seconds, the time axis for all axes is set to a finite width (time range). When a signal value from the real-time application exceeds the largest time value on the x-axis, the axes can either scroll or wrap.

Application — Name of real-time application

character vector | string

You can set the value of the Application property to an existing real-time application when you create the Instrument object or you can set the value later. After value is written to this property, it become read-only. You can not change the Application property value directly after creating the object. The property value can only be changed after object creation by using the validate function.

Object Functions

addInstrumentedSignals	Find instrumented signals and add these to real-time instrument object
addSignal	Add signal for streaming to be available in callback
clearScalarAndLineData	Clear data from children of real-time instrument object
connectCallback	Add callback that responds to new data from target computer
connectLine	Connect signal for streaming to axes
connectScalar	Add signal for streaming to scalar display
connectXYPlot	Connect X and Y signal structures to display on axes
delete	Delete real-time instrument object
generateScript	Generate script that creates scalar and axes controls from signals, scalars, and lines in real-time instrument object
getBufferedData	Gets data from the real-time application instrument buffer
getCallbackDataForSignal	Get callback data for a signal in real-time instrument object
removeCallback	Removed callback from real-time instrument object
removeSignal	Remove signal from real-time instrument object
validate	Validate signals in instrument object

Examples

Create Instrument Object for Real-Time Application

Create instrument object hInst for an existing real-time application appName.

appName = 'slrt_ex_pendulum_100Hz.mldatx';
hInst = slrealtime.Instrument(appName);

Create Instrument Object without Real-Time Application

Create instrument object hInst without assigning a real-time application. This approach is useful when building a GUI and the real-time application MLDATX file is not available.

hInst = slrealtime.Instrument();

Apply Instrument Object Methods

This example shows how to create an Instrument object, apply Instrument object methods, and remove the object. This example assumes that a real-time application traffic_lights.mldatx exists and includes the signals that are connected to the instrument object.

app = slrealtime.Application('traffic_lights')

inst = slrealtime.Instrument();

inst.connectScalar(app.Numeric1, 'ScalarDouble1');
inst.connectScalar(app.Gauge1,   'ScalarDouble1');
inst.connectScalar(app.Numeric2, "ScalarDouble2");
inst.connectScalar(app.Gauge2,   "ScalarDouble2");

inst.connectScalar(app.Text1, "myString", 'Callback', @(t,d)string(d));
inst.connectScalar(app.Text2, "myString", 'Callback', @(t,d)string(d), 'Decimation', 2);
% Permitted values for Decimation are from 1 to 256.

inst.connectScalar(app.Lamp0, "TrafficLight", 'PropertyName', 'Visible', 'Callback', @(t,d)string(matlab.lang.OnOffSwitchState(d==hSampleEnum.Green)));
inst.connectScalar(app.Lamp1, "TrafficLight", 'PropertyName', 'Visible', 'Callback', @(t,d)string(matlab.lang.OnOffSwitchState(d==hSampleEnum.Yellow)));
inst.connectScalar(app.Lamp2, "TrafficLight", 'PropertyName', 'Visible', 'Callback', @(t,d)string(matlab.lang.OnOffSwitchState(d==hSampleEnum.Red)));

ls2 = slrealtime.instrument.LineStyle();
ls2.Marker = '*';
ls2.MarkerSize = 4;
ls2.Color = 'black';
inst.connectLine(app.Axes1, "SineWave", 'ArrayIndex', 5, 'LineStyle', ls2, 'Callback', @(t,d)(d+app.Offset.Value));
inst.connectLine(app.Axes1, "SineWave");

inst.connectCallback(@(o,e)customPlot(o,e,app)); % plot sine waves added together with amplitudes 1, 3 and 5

tg=slrealtime;
tg.addInstrument(inst);

inst.AxesTimeSpan = 10;

inst.AxesTimeSpanOverrun = 'wrap';

inst.AxesTimeSpan = Inf;

tg.removeInstrument(inst);

Version History

Introduced in R2020b