Instrument

R2026b

Create real-time instrument object

expand all in page

Description

An slrealtime.Instrument object streams signal data from a real-time simulation running on a Speedgoat® target computer to a MATLAB® development computer or to a destination that you select by using the Instruments property in the Target Object Properties. For more information, see the addForFileLog function, addForMATLAB function, and addForSDI function. The slrealtime.Instrument object provides access to object functions, object properties, and 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.

For more information, see Add Instruments to Real-Time Application by Using Simulink Editor and Add Instruments to Real-Time Applications by Using MATLAB Language. You also can work with instruments by using the Simulink Real-Time Instrument Viewer.

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

expand all

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.

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.

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

The Enable property enables or disables the instrument for the real-time application. When enabled (true), the instrument streams signals from the real-time application. When disabled (false), the instrument stops streaming signals.

The Name property is a valid variable name that you can use to refer to the real-time application.

You can set the value of the ModelName property to an existing model 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 Model property value directly after creating the object. The property value can only be changed after object creation by using the validate function.

Object Functions

addFileLogSignalsFind signals connected to File Log blocks and add these to real-time instrument object
addInstrumentedSignalsFind instrumented signals and add these to real-time instrument object
addSignalAdd signal for streaming to be available in callback
clearScalarAndLineDataClear data from children of real-time instrument object
connectCallbackAdd callback that responds to new data from target computer
connectLineConnect signal for streaming to axes
connectScalarAdd signal for streaming to scalar display
connectXYPlotConnect X and Y signal structures to display on axes
copyCopy the array of handle objects from one Instrument object to another
deleteDelete real-time instrument object
generateScriptGenerate script that creates scalar and axes controls from signals, scalars, and lines in real-time instrument object
getQuery Instrument object properties
getBufferedDataGets data from the real-time application instrument buffer
getCallbackDataForSignalGet callback data for a signal in real-time instrument object
removeCallbackRemoved callback from real-time instrument object
removeSignalRemove signal from real-time instrument object
setAssign Instrument object property values
validateValidate signals in instrument object

Note

Some Instrument object functions (for example, clearScalarAndLineData, connectCallback, connectLine, connectScalar, connectXYPlot, generateScript, getCallbackDataForSignal, and removeCallback) are not intended for use when selecting a signal streaming destination by using the Instruments property in the Target Object Properties. Use these object functions when developing App Designer instrument panels.

Examples

collapse all

Create instrument object hInst for an existing real-time application appName. This approach is useful for validating signal names in the real-time application MLDATX file as you add signals to the Instrument object.

appName = 'slrt_ex_pendulum_100Hz'; % name of model or MLDATX file
hInst = slrealtime.Instrument(appName);

Create instrument object hInst without assigning a real-time application. This approach is useful when building a user interface, when the real-time application MLDATX file is not available, or when you are using the instrument with multiple models. 

hInst = slrealtime.Instrument();
Open Script

This example shows how to create an Instrument object and apply Instrument object methods. This example uses real-time application slrt_ex_traffic_lights.mldatx and includes the signals that are connected to the instrument object.

Connect Target Computer

Connect to the default target computer.

tg = slrealtime;
connect(tg);

Configure Model for Target Computer

Open the example model and configure the system target file (STF) selection.

model = 'slrt_ex_traffic_lights';
open_system(model);
modelSTF = getSTFName(tg);
set_param(model,"SystemTargetFile",modelSTF);

Build Real-Time Application

Build the real-time app. Use evalc to suppress build messages.

evalc('slbuild(model)');

Open App Generator and MLDATX File

To created an Instrument object and apply Instrument object methods, use the Simulink Real-Time App Generator to bind signals and parameters to controls then generate the app.

Start the App Generator by using the button on the Real-Time tab in the Simulink® Editor.

Open the slrt_ex_traffic_lights.mat file that specifies a set of application controls. You can use this setup to generate the traffic_lights.mlapp app.

Tip: Open the Parameter panel in the App Generator to inspect parameters for the controls.

Open App Designer and View Callback Code

From the Files in MATLAB®, open the traffic_lights.mlapp app.

To view the callback code that demonstrates the object methods, switch from Design View to Code View. Scroll to the portion of the callback code that starts with this text:

  Code that executes after component creation
      function startupFcn(app)

To modify this code, open the MAT file, modify the configuration of controls, and click the Update App button.

Close Model and App

When done examining callback code, close the model, the App Generator, and App Designer.

bdclose(model);

Version History

Introduced in R2020b

See Also

| | | | | | | | | | | | | | | | |

Topics