Working with Scope Objects :: Targets and Scopes in the MATLAB Interface (xPC Target™)

Learn more about xPC Target

Working with Scope Objects

On this page…
Accessing Help for Scope Objects Displaying Scope Object Properties for a Single Scope Displaying Scope Object Properties for All Scopes Setting the Value of a Scope Property Getting the Value of a Scope Property Using the Method Syntax with Scope Objects Acquiring Signal Data with Scopes of Type File Acquiring Signal Data into Multiple, Dynamically Named Files with Scopes of Type File Advanced Data Acquisition Topics

On this page…

Accessing Help for Scope Objects

Displaying Scope Object Properties for a Single Scope

Displaying Scope Object Properties for All Scopes

Setting the Value of a Scope Property

Getting the Value of a Scope Property

Using the Method Syntax with Scope Objects

Acquiring Signal Data with Scopes of Type File

Acquiring Signal Data into Multiple, Dynamically Named Files with Scopes of Type File

Advanced Data Acquisition Topics

Accessing Help for Scope Objects

See Function Reference and Functions for a reference of the scope object functions.

The scope object methods allow you to control scopes on your target PC.

If you want to control the target application from the target PC, use target PC commands. See Using the Target PC Command-Line Interface.

Displaying Scope Object Properties for a Single Scope

To list the properties of a single scope object, sc1,

In the MATLAB window, type
```
sc1  = getscope(tg,1) or sc1 = tg.getscope(1)
```
MATLAB creates the scope object sc1 from a previously created scope.
Type
```
sc1
```
The current scope properties are uploaded to the host PC, and then MATLAB displays a list of the scope object properties with the updated values. Because sc1 is a vector with a single element, you could also type sc1(1) or sc1([1]).

Note Only scopes with type host store data in the properties scope_object.Time and scope_object.Data.

For a list of target object properties with a description, see the target function get (target application object).

Displaying Scope Object Properties for All Scopes

To list the properties of all scope objects associated with the target object tg,

In the MATLAB window, type
```
getscope(tg) or tg.getscope
```
MATLAB displays a list of all scope objects associated with the target object.
Alternatively, type
```
allscopes = getscope(tg)
```
or
```
allscopes = tg.getscope
```
The current scope properties are uploaded to the host PC, and then MATLAB displays a list of all the scope object properties with the updated values. To list some of the scopes, use the vector index. For example, to list the first and third scopes, type allscopes([1,3]).

For a list of target object properties with a description, see the target function get (target application object).

Setting the Value of a Scope Property

With the xPC Target software you can use either a function syntax or an object property syntax. The syntax set(scope_object, property_name, new_property_value) can be replaced by

scope_object(index_vector).property_name = new_property_value

For example, to change the trigger mode for the scope object sc1,

In the MATLAB window, type
```
sc1.triggermode = 'signal' 
```

Alternatively, you can type

set(sc1,'triggermode', 'signal')

sc1.set('triggermode', 'signal')

Note that you cannot use dot notation to set vector object properties. To assign properties to a vector of scopes, use the set method. For example, assume you have a variable sc12 for two scopes, 1 and 2. To set the NumSamples property of these scopes to 300,

In the MATLAB window, type
```
set(sc12,'NumSamples',300)
```

To get a list of the writable properties, type set(scope_object).

Note Method names are case sensitive. You must type the entire name. Property names are not case sensitive. You do not need to type the entire name as long as the characters you do type are unique for the property.

Getting the Value of a Scope Property

You can list a property value in the MATLAB window or assign that value to a MATLAB variable. With the xPC Target software you can use either a function syntax or an object property syntax.

The syntax get(scope_object_vector, property_name) can be replaced by

scope_object_vector(index_vector).property_name

For example, to assign the number of samples from the scope object sc1,

In the MATLAB window, type
```
numsamples = sc1.NumSamples 
```

Alternatively, you can type

numsamples = get(sc1,'NumSamples')

sc1.get(NumSamples)

Note that you cannot use dot notation to get the values of vector object properties. To get properties of a vector of scopes, use the get method. For example, assume you have two scopes, 1 and 2, assigned to the variable sc12.

To get the value of NumSamples for these scopes, in the MATLAB window, type

get(sc12,'NumSamples')

You get a result like the following:

ans = 
    [300]
    [300]

To get a list of readable properties, type scope_object. The property values are listed in the MATLAB window.

Using the Method Syntax with Scope Objects

Use the method syntax to run a scope object method. The syntax method_name(scope_object_vector, argument_list) can be replaced with either

scope_object.method_name(argument_list)
scope_object_vector(index_vector).method_name(argument_list)

Unlike properties, for which partial but unambiguous names are permitted, enter method names in full, and in lowercase. For example, to add signals to the first scope in a vector of all scopes,

In the MATLAB window, type
```
allscopes(1).addsignal([0,1])
```
Alternatively, you can type
```
addsignal(allscopes(1), [0,1])
```

Acquiring Signal Data with Scopes of Type File

You can acquire signal data into a file on the target PC. To do so, you add a scope of type file to the application. After you build an application and download it to the target PC, you can add a scope of type file to that application.

For example, to add a scope of type file named sc to the application, and to add signal 4 to that scope,

In the MATLAB window, type
```
sc=tg.addscope('file')
```
The xPC Target software creates a scope of type file for the application.
Type
```
sc.addsignal(4)
```
To start the scope, type
```
+sc
```
To start the target application, type
```
+tg
```

The xPC Target software adds signal 4 to the scope of type file. When you start the scope and application, the scope saves the signal data for signal 4 to a file, by default named C:\data.dat.

See Scope of Type File in Signals and Parameters for a description of scopes of type file.

If you want to acquire signal data into multiple files, see Acquiring Signal Data into Multiple, Dynamically Named Files with Scopes of Type File.

Acquiring Signal Data into Multiple, Dynamically Named Files with Scopes of Type File

You can acquire signal data into multiple, dynamically named files on the target PC. For example, you can acquire data into multiple files to examine one file while the scope continues to acquire data into other files. To acquire data in multiple files, add a scope of type file to the application. After you build an application and download it to the target PC, you can add a scope of type file to that application. You can then configure that scope to log signal data to multiple files.

For example, configure a scope of type file named sc to the application with the following characteristics:

Logs signal data into up to nine files whose sizes do not exceed 4096 bytes.
Creates files whose names contain the string file_.dat.
Contains signal 4.

In the MATLAB window, type
```
tg.StopTime=-1;
```
This parameter directs the target application to run indefinitely.
To add a scope of type file, type
```
sc=tg.addscope('file');
```
To enable the file scope to create multiple log files, type
```
sc.DynamicFileName='on';
```
Enable this setting to enable logging to multiple files.
To enable file scopes to collect data up to the number of samples, then start over again, type
```
sc.AutoRestart='on';
```
Use this setting for the creation of multiple log files.
To limit each log file size to 4096, type
```
sc.MaxWriteFileSize=4096;
```
You must use this property. Set MaxWriteFileSize to a multiple of the WriteSize property.
To enable the file scope to create multiple log files with the same name pattern, type
```
sc.Filename='file_<%>.dat';
```
This sequence directs the software to create up to nine log files, file_1.dat to file_9.dat on the target PC file system.
To add signal 4 to the file scope, type
```
sc.addsignal(4);
```
To start the scope, type
```
+sc
```
To start the target application, type
```
+tg
```
The software creates a log file named file_1.dat and writes data to that file. When the size of file_1.dat reaches 4096 bytes (value of MaxWriteFileSize), the software closes the file and creates file_2.dat for writing until its size reaches 4096 bytes. The software repeats this sequence until it fills the last log file, file_9.dat. If the target application continues to run and collect data after file_9.dat, the software reopens file_1.dat and continues to log data, overwriting the existing contents. It cycles through the other log files sequentially.

If you want to acquire signal data into a single file, see Acquiring Signal Data with Scopes of Type File.

Advanced Data Acquisition Topics

The moment that an xPC Target scope begins to acquire data is user configurable. You can have xPC Target scopes acquire data right away, or define triggers for scopes such that the xPC Target scopes wait until they are triggered to acquire data. You can configure xPC Target scopes to start acquiring data when the following scope trigger conditions are met. These are known as trigger modes.

Freerun — Starts to acquire data as soon as the scope is started (default)
Software — Starts to acquire data in response to a user request. You generate a user request when you call the scope method trigger or the scope function xPCScSoftwareTrigger.
Signal — Starts to acquire data when a particular signal has crossed a preset level
Scope — Starts to acquire data based on when another (triggering) scope starts

You can use several properties to further refine when a scope acquires data. For example, if you set a scope to trigger on a signal (Signal trigger mode), you can configure the scope to specify the following:

The signal to trigger the scope (required)
The trigger level that the signal must cross to trigger the scope to start acquiring data
Whether the scope should trigger on a rising signal, falling signal, or either one

In the following topics, the trigger point is the sample during which the scope trigger condition is satisfied. For signal triggering, the trigger point is the sample during which the trigger signal passes through the trigger level. At the trigger point, the scope acquires the first sample. By default, scopes start acquiring data from the trigger point onwards. You can modify this behavior using the pre- and posttriggering.

Pretriggering — Starts to acquire data N moments before a trigger occurs
Posttriggering — Starts to acquire data N moments after a trigger occurs

The NumPrePostSamples scope property controls the pre- and posttriggering operation. This property specifies the number of samples to be collected before or after a trigger event.

If NumPrePostSamples is a negative number, the scope is in pretriggering mode, where it starts collecting samples before the trigger event.
If NumPrePostSamples is a positive number, the scope is in a posttriggering mode, where it starts collecting samples after the trigger event.

The following topics describe two examples of acquiring data:

Triggering One Scope with Another Scope to Acquire Data — Describes a configuration of one scope to trigger another using the concept of pre- and posttriggering
Acquiring Gap-Free Data Using Two Scopes — Describes how to apply the concept of triggering one scope with another to acquire gap-free data

Triggering One Scope with Another Scope to Acquire Data

This section describes the concept of triggering one scope with another to acquire data. The description uses actual scope objects and properties to describe triggers.

The ability to have one scope trigger another, and to delay retrieving data from the second after a trigger event on the first, is most useful when data acquisition for the second scope is triggered after data acquisition for the first scope is complete. In the following explanation, Scope 2 is triggered by Scope 1.

Assume two scopes objects are configured as a vector with the command
```
sc = tg.addscope('host', [1 2]);
```
For Scope 1, set the following values:
- sc(1).ScopeId = 1
- sc(1).NumSamples = N
- sc1.NumPrePostSamples = P
For Scope 2, set the following values:
- sc(2).ScopeId = 2
- sc(2).TriggerMode = 'Scope'
- sc(2).TriggerScope =1
- sc(2).TriggerSample = range 0 to (N + P - 1)

In the figures below, TP is the trigger point or sample where a trigger event occurs. Scope 1 begins acquiring data as described.

In the simplest case, where P = 0, Scope 1 acquires data right away.

Pretriggering (P<0) illustrates the behavior if P, the value of NumPrePostSamples, is negative. In this case, Scope 1 starts acquiring data |P| samples before TP. Scope 2 begins to acquire data only after TP occurs.

Pretriggering (P<0)

Posttriggering (P>0) illustrates the behavior if P, the value of NumPrePostSamples, is positive. In this case, Scope 1 starts acquiring data |P| samples after TP occurs.

Posttriggering (P>0)

Scope 1 triggers Scope 2 after the trigger event occurs. The following describes some of the ways you can trigger Scope 2:

sc(2).TriggerSample = 0 — Causes Scope 2 to be triggered when Scope 1 is triggered. TP for both scopes as at the same sample.
sc(2).TriggerSample = n > 0 — Causes TP for Scope 2 to be n samples after TP for Scope 1. Note that setting sc(2).TriggerSample to a value larger than (N + P - 1) does not cause an error; it implies that Scope 2 will never trigger, since Scope 1 will never acquire more than (N + P - 1) samples after TP.
sc(2).TriggerSample = 0 < n < (N + P) — Enables you to obtain some of the functionality that is available with pre- or posttriggering. For example, if you have the following Scope 1 and Scope 2 settings,
- Scope 1 has sc(1).NumPrePostSamples = 0 (no pre- or posttriggering)
- Scope 2 has sc(2).TriggerSample = 10
- Scope 2 has sc(2).NumPrePostSample = 0
The behavior displayed by Scope 2 is equivalent to having sc(2).TriggerSample = 0 and sc(2).NumPrePostSamples = 10.
sc(2).TriggerSample = -1 — Causes Scope 2 to start acquiring data from the sample after Scope 1 stops acquiring.

Note The difference between setting TriggerSample = (N + P - 1), where N and P are the parameters of the triggering scope (Scope 1) and TriggerSample = -1 is that in the former case, the first sample of Scope 2 will be at the same time as the last sample of Scope 1, whereas in the latter, the first sample of Scope 2 will be one sample after the last sample of Scope 1. This means that in the former case both scopes acquire simultaneously for one sample, and in the latter they will never simultaneously acquire.

Acquiring Gap-Free Data Using Two Scopes

With two scopes, you can acquire gap-free data. Gap-free data is data that two scopes acquire consecutively, with no overlap. The first scope acquires data up to N, then stops. The second scope begins to acquire data at N+1. This is functionality that you cannot achieve through pre- or posttriggering.

Acquisition of Gap-Free Data graphically illustrates how scopes trigger one another. In this example, the TriggerMode property of Scope 1 is set to 'Software'. This allows Scope 1 to be software triggered to acquire data when it receives the command sc1.trigger.

Acquisition of Gap-Free Data

The following procedure describes how you can programmatically acquire gap-free data with two scopes.

Ensure that you have already built and downloaded the Simulink model xpcosc.mdl to the target PC.
In the MATLAB Command Window, assign tg to the target PC and set the StopTime property to 1. For example,
```
tg=xpctarget.xpc
tg.StopTime = 1;
```
Add two scopes of type host to the target application. You can assign the two scopes to a vector, sc, so that you can work with both scopes with one command.
```
sc = tg.addscope('host', [1 2]);
```
Add the signals of interest (0 and 1) to both scopes.
```
addsignal(sc,[0 1]);
```
Set the NumSamples property for both scopes to 500 and the TriggerSample property for both scopes to -1. With this property setting, each scope triggers the next scope at the end of its 500 sample acquisition.
```
set(sc, 'NumSamples', 500, 'TriggerSample', -1)
```
Set the TriggerMode property for both scopes to 'Scope'. Set the TriggerScope property such that each scope is triggered by the other.
```
set(sc, 'TriggerMode', 'Scope');
sc(1).TriggerScope = 2;
sc(2).TriggerScope = 1;
```
Set up storage for time, t, and signal, data acquisition.
```
t    = [];
data = zeros(0, 2);
```
Start both scopes and the model.
```
start(sc);
start(tg);
```
Note that both scopes receive exactly the same signals, 0 and 1.
Trigger scope 1 to start acquiring data.
```
scNum = 1;
sc(scNum).trigger;
```
Setting scNum to 1 indicates that scope 1 will acquire data first.

Start acquiring data using the two scopes to double buffer the data.

while (1)
  % Wait until this scope has finished acquiring 500 samples
  % or the model stops (scope is interrupted).
  while ~(strcmp(sc(scNum).Status, 'Finished') || ...
          strcmp(sc(scNum).Status, 'Interrupted')), end
  % Stop buffering data when the model stops.
  if strcmp(tg.Status, 'stopped')
    break
  end
  % Save the data.
  t(   end + 1 : end + 500)    = sc(scNum).Time;
  data(end + 1 : end + 500, :) = sc(scNum).Data;
  % Restart this scope.
  start(sc(scNum)); 
  % Switch to the next scope.
%Shortcut for if(scNum==1) scNum=2;else scNum=1,end
scNum = 3 - scNum; 
end

When done, remove the scopes.

% Remove the scopes we added.
remscope(tg,[1 2]);

The following is a complete code listing for the preceding double-buffering data acquisition procedure. You can copy and paste this code into an M-file and run it after you download the model (xpcosc.mdl) to the target PC. This example assumes that the communication speed between the host and target PC is fast enough to handle the number of samples and can acquire the full data set before the next acquisition cycles starts. In a similar way, you can use more than two scopes to implement a triple- or quadruple-buffering scheme.

% Assumes model xpcosc.mdl has been built and loaded on the target PC.
% Attach to the target PC and set StopTime to 1 sec.
tg = xpctarget.xpc;
tg.StopTime = 1;
% Add two host scopes.
sc = tg.addscope('host', [1 2]);
% [0 1] are the signals of interest.  Add to both scopes.
addsignal(sc,[0 1]);
% Each scope triggers next scope at end of a 500 sample acquisition.
set(sc, 'NumSamples', 500, 'TriggerSample', -1);
set(sc, 'TriggerMode', 'Scope');
sc(1).TriggerScope = 2;
sc(2).TriggerScope = 1;
% Initialize time and data log.
t    = [];
data = zeros(0, 2);
% Start the scopes and the model.
start(sc);
start(tg);
% Start things off by triggering scope 1.
scNum = 1; 
sc(scNum).trigger; 
% Use the two scopes as a double buffer to log the data.
while (1)
  % Wait until this scope has finished acquiring 500 samples
  % or the model stops (scope is interrupted).
  while ~(strcmp(sc(scNum).Status, 'Finished') || ...
          strcmp(sc(scNum).Status, 'Interrupted')), end
  % Stop buffering data when the model stops.
  if strcmp(tg.Status, 'stopped')
    break
  end
  % Save the data.
  t(   end + 1 : end + 500)    = sc(scNum).Time;
  data(end + 1 : end + 500, :) = sc(scNum).Data;
  % Restart this scope.
  start(sc(scNum)); 
  % Switch to the next scope.
  scNum = 3 - scNum;
end
% Remove the scopes we added.
remscope(tg,[1 2]);
% Plot the data.
plot(t,data); grid on; legend('Signal 0','Signal 1');

Working with Target Objects

Signals and Parameters

Related Products & Applications

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit