Documentation

Real-Time File Scope

Record time-domain data on target computer file system

Description

Controls and accesses properties of file scopes.

The scope gets a data package from the kernel and stores the data in a file on the target computer file system. Depending on the setting of WriteMode, the file size is or is not continuously updated. You can transfer the data to another computer for examination or plotting.

The NumSamples parameter works with the autorestart setting.

  • Autorestart is on — When the scope triggers, the scope starts collecting data into a memory buffer. A background task examines the buffer and writes data to the disk continuously, appending new data to the end of the file. When the scope reaches the number of samples that you specified, it starts collecting data again, overwriting the memory buffer. If the background task cannot keep pace with data collection, data can be lost.

  • Autorestart is off — When the scope triggers, the scope starts collecting data into a memory buffer. It stops when it has collected the number of samples that you specified. A background task examines the buffer and writes data to the disk continuously, appending the new data to the end of the file.

The following limitations exist:

  • You can have at most eight files open on the target computer at the same time.

  • The largest single file that you can create on the target computer is 4 GB.

  • A fully qualified folder name can have a maximum of 248 characters, including the drive letter, colon, and backslash.

  • A fully qualified file name can have a maximum of 260 characters: The file part can have at most 12 characters: eight for the file name, one for the period, and at most three for the file extension. A file name longer than eight characters is truncated to six characters followed by '~1'.

  • Do not write data to the private folder on your target computer. It is reserved for Simulink® Real-Time™ internal use.

The following lexical rules exist:

  • Function names are case sensitive. Type the entire name.

  • Property names are not case sensitive. You do not need to type the entire name, as long as the characters that you type are unique for the property.

You can invoke some of the scope object properties and functions from the target computer command line when you have loaded the real-time application.

Properties

expand all

Use scope object properties to select signals that you want to acquire, set triggering modes, and access signal information from the real-time application.

To get the value of a readable scope object property from a scope object:

scope_object = getscope(target_object, scope_number);
value = scope_object.scope_object_property

To get the Decimation of scope 3:

scope_object = getscope(tg, 3);
value = scope_object.Decimation

To set the value of a writable scope property from a scope object:

scope_object = getscope(target_object, scope_number);
scope_object.scope_object_property = new_value

To set the Decimation of scope 3:

scope_object = getscope(tg, 3);
scope_object.Decimation = 10

Not all properties are user-writable. For example, after you create the scope, property Type is not writable.

File Scope Properties

Possible values:

  • 'on' — The scope collects data up to NumSamples, and then starts over again, appending the new data to the end of the signal data file.

  • 'off' — The scope collects data up to NumSamples, and then stops.

If the named signal data file exists when you start the real-time application, the software overwrites the old data with the new signal data.

To use the DynamicFileName property, set AutoRestart to 'on'.

Enables the file scope to create multiple log files dynamically.

To use the DynamicFileName property, set AutoRestart to 'on'.

Configure Filename to create incrementally numbered file names for the multiple log files. If you do not configure Filename as required, the software generates an error when you try to start the scope.

You can enable the creation of up to 99999999 files (<%%%%%%%%>.dat). The length of a file name, including the specifier, cannot exceed eight characters.

Provide a name for the file that contains the signal data. For file scopes that you create through the MATLAB® interface, no name is initially assigned to FileName. After you start the scope, the software assigns a name for the file that is to acquire the signal data. This name typically consists of the scope object name, ScopeId, and the beginning letters of the first signal added to the scope.

If you set DynamicFileName and AutoRestart to 'on', configure Filename to increment dynamically. Use a base file name, an underscore (_), and a < > specifier. Within the specifier, enter one to eight % symbols. Each symbol % represents a decimal location in the file name. The specifier can appear anywhere in the file name. For example, the following value for Filename, C:\work\file_<%%%>.dat creates file names with the following pattern:

file_001.dat
file_002.dat
file_003.dat

The last file name of this series is file_999.dat. If the block is still logging data when the last file reaches its maximum size, the function restarts and overwrites the first file in the series. If you do not retrieve the data from existing files before they are overwritten, the data is lost.

Provide the maximum size of Filename, in bytes. This value must be a multiple of WriteSize.

When the size of a log file reaches MaxWriteFileSize, the software increments the number in the file name and logs data to the new file. The software logs data to successive files until it fills the file with the highest file number that you specified. If the software cannot create additional log files, it overwrites the first log file.

Specify when a file allocation table (FAT) entry is updated. Both 'Lazy' and 'Commit' modes write the signal data to the file. With 'Commit' mode, each file write operation simultaneously updates the FAT entry for the file.

'Commit' mode is slower than 'Lazy' mode. The file system maintains the actual file size. With 'Lazy' mode, the FAT entry is updated only when the file is closed and not during each file write operation. If the system stops responding before the file is closed, the file system does not necessarily know the actual file size. The file contents are intact, but not easily accessible.

Enter the block size, in bytes, of the data chunks. This parameter specifies that a memory buffer, of length NumSamples, collects data in multiples of WriteSize. Using a block size that is the same as the disk sector size provides better performance.

If your system stops responding, you can expect to lose an amount of data equal to the size of WriteSize.

Common Scope Properties

Read-only name of the real-time application associated with this scope object.

If 1, scope acquires every sample. If greater than 1, scope acquires every Decimationth sample.

Number of samples collected before or after a trigger event. Entering a negative value collects samples before the trigger event. Entering a positive value collects samples after the trigger event. If you set TriggerMode to 'FreeRun', this property has no effect on data acquisition.

Number of contiguous samples captured during the acquisition of a data package.

The scope writes data samples into a memory buffer of size NumSamples. If the scope stops before capturing this number of samples, the scope writes zeroes after the collected data to the end of the buffer. Know what type of data you are collecting, because it is possible that your data contains zeroes.

Read-only numeric index, unique for each scope.

List of signal indices from the target object to display on the scope.

Read-only state value:

  • 'Acquiring' — The scope is acquiring data.

  • 'Ready for being Triggered' — The scope is waiting for a trigger.

  • 'Interrupted' — The scope is not running (interrupted).

  • 'Finished' — The scope has finished acquiring data.

If TriggerMode is 'Signal', this parameter indicates the value that the signal has to cross to trigger the scope and start acquiring data. The trigger level can be crossed with either a rising or falling signal.

Trigger mode for a scope:

  • 'freerun' — The scope triggers on every sample time.

  • 'software' — The scope triggers from the Command Window.

  • 'signal' — The scope triggers when a designated signal changes state.

  • 'scope' — The scope triggers when a designated scope triggers.

If TriggerMode is 'Scope', then TriggerSample specifies on which sample of the triggering scope the current scope triggers.

For example, if TriggerSample is 0 (default), the current scope triggers on sample 0 (first sample acquired) of the triggering scope. In this case, the two scopes are synchronized with each other.

If TriggerSample is 1, the current scope triggers on sample 1 (second sample acquired) of the triggering scope. In this case, the two scopes have a one-sample offset.

Setting TriggerSample to -1 means that the current scope triggers at the end of the acquisition cycle of the triggering scope. In this case, the triggered scope acquires its first sample one sample after the last sample of the triggering scope.

If TriggerMode is 'Scope', this parameter identifies the scope to use for a trigger. To trigger a scope when another scope is triggered, set the slave scope property TriggerScope to the scope index of the master scope.

If TriggerMode is 'Signal', this parameter identifies the block output signal to use for triggering the scope. Identify the signal with a signal index from the target object property Signal.

If TriggerMode is 'Signal', TriggerSlope indicates the signal behavior that triggers the scope.

  • 'Either' — The signal triggers the scope when it crosses TriggerLevel in either the rising or falling directions.

  • 'Rising' — The signal triggers the scope when it crosses TriggerLevel in the rising direction.

  • 'Falling' — The signal triggers the scope when it crosses TriggerLevel in the falling direction.

Read-only property that determines how the scope collects and displays its data:

  • 'Host' — The scope collects data on the target computer and displays it on the development computer.

  • 'Target' — The scope collects data on the target computer and displays it on the target computer monitor.

  • 'File' — The scope collects and stores data on the target computer.

Object Functions

SimulinkRealTime.fileScope.addsignalAdd signals to file scope represented by scope object
SimulinkRealTime.fileScope.remsignalRemove signals from file scope represented by scope object
SimulinkRealTime.fileScope.startStart execution of file scope on target computer
SimulinkRealTime.fileScope.stopStop execution of file scope on target computer
SimulinkRealTime.fileScope.triggerSoftware-trigger start of data acquisition for file scope

Examples

expand all

Build and download xpcosc and execute the real-time application with a file scope.

Open, build, and download the real-time application.

ex_model = 'xpcosc';
open_system(ex_model);
rtwbuild(ex_model);
tg = SimulinkRealTime.target
Target: TargetPC1
   Connected            = Yes
   Application          = xpcosc
   Mode                 = Real-Time Single-Tasking
   Status               = stopped
   CPUOverload          = none

   ExecTime             = 0.0000
   SessionTime          = 7405.9356
   StopTime             = 0.200000
   SampleTime           = 0.000250
   AvgTET               = NaN
   MinTET               = Inf
   MaxTET               = 0.000000
   ViewMode             = 0

   TimeLog              = Vector(0) 
   StateLog             = Matrix (0 x 2)
   OutputLog            = Matrix (0 x 2)
   TETLog               = Vector(0) 
   MaxLogSamples        = 16666
   NumLogWraps          = 0
   LogMode              = Normal
   ProfilerStatus       = Ready

   Scopes               = No Scopes defined  
   NumSignals           = 7
   ShowSignals          = off

   NumParameters        = 7
   ShowParameters       = off

Add and configure file scope 1.

sc1 = addscope(tg, 'file', 1);
addsignal(sc1, 4);
addsignal(sc1, 5)
ans = 
Simulink Real-Time Scope
   Application          = xpcosc
   ScopeId              = 1
   Status               = Interrupted
   Type                 = File
   NumSamples           = 250
   NumPrePostSamples    = 0
   Decimation           = 1
   TriggerMode          = FreeRun
   TriggerSignal        = 4  : Integrator1
   TriggerLevel         = 0.000000
   TriggerSlope         = Either
   TriggerScope         = 1
   TriggerSample        = 0
   FileName             = unset
   WriteMode            = Lazy
   WriteSize            = 512
   AutoRestart          = off
   DynamicFileName      = off
   MaxWriteFileSize     = 536870912
   Signals              = 4  : Integrator1
                          5  : Signal Generator

Run the real-time application for 10 seconds.

tg.StopTime = 10;
start(sc1);
start(tg);
pause(10);
stop(tg);
stop(sc1);

Download and display the file scope data.

fsys = SimulinkRealTime.fileSystem(tg);
fh = fopen(fsys, sc1.FileName);
data = fread(fsys, fh);
uint8_data = uint8(data);
plottable_data = ...
     SimulinkRealTime.utils.getFileScopeData(uint8_data);
plot(plottable_data.data)

Unload the real-time application.

unload(tg)
Target: TargetPC1
   Connected            = Yes
   Application          = loader

Introduced in R2014a

Was this topic helpful?