This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

SimulinkRealTime.fileScope

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 128 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 in the operating system on the target computer can have a maximum of 260 characters. If the file name is longer than eight-dot-three format (eight character file name, period, three character extension), the operating system represents the file name in truncated form (for example, six characters followed by '~1'). MATLAB commands can access the file using the fully qualified file name or the truncated representation of the name. Some block parameters, such as the Scope block filename parameter, require 8.3 format for the file name.

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

Before you consider using a Real-Time File Scopes that could produce a file larger than 2 GB, use either of these approaches:

  • Instead of a File Scope, use the Simulation Data Inspector in buffered mode for data logging.

  • If using a File Scope, use the DynamicFileName enabled option and set the MaxWriteFileSize to less than 2 GB.

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.

Creation

addscope

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.

Read-only numeric index, unique for each 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.

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.

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.

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.

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

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 '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', 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.

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.

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

Select the y-axis minimum and maximum limits for scope as Auto or with a vector containing the minimum and maximum values (for example, [-10, 10]).

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

Object Functions

addsignal (fileScope,signal)Add signals to file scope represented by scope object
remsignal (fileScope,signal)Remove signals from file scope represented by scope object
start (fileScope)Start execution of file scope on target computer
stop (fileScope)Stop execution of file scope on target computer
trigger(fileScope)Software-trigger start of data acquisition for file scope

Examples

collapse 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