Using SimulinkRealTime.fileSystem Objects

The fileSystem object enables you to work with the target computer file system from the development computer. You enter target object functions in the MATLAB® window on the development computer or use scripts. The fileSystem object has functions that allow you to use

  • cd to change folders

  • dir to list the contents of the current folder

  • mkdir to make a folder

  • pwd to get the current working folder path

  • rmdir to remove a folder

  • diskinfo to get information about the specified disk

  • fclose to close a file (similar to MATLAB fclose)

  • fileinfo to get information about a particular file

  • filetable to get information about files in the file system

  • fopen to open a file (similar to MATLAB fopen)

  • fread to read a file (similar to MATLAB fread)

  • fwrite to write a file (similar to MATLAB fwrite)

  • getfilesize to get the size of a file in bytes

  • removefile to remove a file from the target computer

Note: The SimulinkRealTime.fileSystem object will be removed in a future release. See the release note for file system commands to use instead. These commands use the SimulinkRealTime.openFTP function and the functions for the MATLAB ftp object.

Useful global functions:

These procedures assume that the target computer has a signal data file created by a Simulink® Real-Time™ file scope. This file has the path name C:\data.dat.

There are the following limitations:

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

Copying Files from the Target Computer to the Development Computer

You can copy a data file from the target computer to the development computer using a SimulinkRealTime package function on the development computer.

For example, to retrieve a file named data.dat from the target computer C:\ drive (default):

  1. If you have not already done so, in the MATLAB window, type the following to assign the default SimulinkRealTime.target object to a variable.

    tg = slrt;
  2. Type

    SimulinkRealTime.copyFileToHost(tg,'data.dat')

    This command retrieves the file and saves that file to the variable data. This content is in the Simulink Real-Time file format.

Copying Files from the Development Computer to the Target Computer

You can copy a file from the development computer to the target computer using a SimulinkRealTime package function on the development computer.

For example, to copy a file named data2.dat from the development computer to the target computer C:\ drive (default),

  1. If you have not already done so, in the MATLAB window, type the following to assign the default SimulinkRealTime.target object to a variable.

    tg = slrt;
  2. Type the following to save that file to the variable data.

    SimulinkRealTime.copyFileToTarget(tg,'data2.dat')

Accessing File Systems on a Specific Target Computer

You can access specific target computer files from the development computer for the SimulinkRealTime.fileSystem object.

Use the SimulinkRealTime.fileSystem creator function. If your system has multiple targets, you can access specific target computer files from the development computer for the SimulinkRealTime.fileSystem object.

For example, to list the name of the current folder of target computer 'TargetPC1':

  1. In the MATLAB window, type a command like the following to assign the SimulinkRealTime.fileSystem object for the default computer to a variable.

    fsys = SimulinkRealTime.fileSystem;
  2. Type

    dir(fsys)

Alternatively, you can use the SimulinkRealTime.target constructor to construct a target object for a specific computer, then use that target object as an argument to SimulinkRealTime.fileSystem.

  1. In the MATLAB window, type a command like the following to assign the SimulinkRealTime.target object for target computer 'TargetPC1' to a variable.

    tg1 = SimulinkRealTime.target('TargetPC1');
  2. To assign the SimulinkRealTime.fileSystem object to a variable, type:

    fsys = SimulinkRealTime.fileSystem(tg1);
  3. Type

    dir(fsys)

Reading the Contents of a File on the Target Computer

You can read the contents of a data file from the target computer by using SimulinkRealTime.fileSystem functions on the development computer. Use this procedure as an alternative to the method described in Configure File Scopes with MATLAB Language.

To run a SimulinkRealTime.fileSystem object function, use the function_name(fs_object, argument_list) syntax. For example, to retrieve the contents of a file named data.dat from the target computer C:\ drive (default):

  1. If you have not already done so, in the MATLAB window, type the following to assign the SimulinkRealTime.fileSystem object to a variable.

    fsys = SimulinkRealTime.fileSystem;
  2. Type

    h = fopen(fsys, 'data.dat');

    This command opens the file data.dat for reading and assigns the file identifier to h.

  3. Type

    data2 = fread(fsys,h);

    This command reads the file data.dat and stores the contents of the file to data2. This content is in the Simulink Real-Time file format.

  4. Type

    fclose(fsys, h)

    This command closes the file data.dat.

Before you can view or plot the contents of this file, you must convert the contents. See Converting Simulink Real-Time File Format Content to Double Precision Data.

Converting Simulink Real-Time File Format Content to Double Precision Data

The Simulink Real-Time software provides the function SimulinkRealTime.utils.getFileScopeData to convert Simulink Real-Time file format content (in bytes) to double precision data representing the signals and timestamps. The SimulinkRealTime.utils.getFileScopeData function takes in data from a file in Simulink Real-Time format. The data must be a vector of bytes (uint8). To convert the data to uint8, use a command like the following:

data2 = uint8(data2');

This section assumes that you have a variable, data2, that contains data in the Simulink Real-Time file format (see Reading the Contents of a File on the Target Computer).

  1. In the MATLAB window, change folder to the folder that contains the Simulink Real-Time format file.

  2. Type

    new_data2 = SimulinkRealTime.utils.getFileScopeData(data2);

    SimulinkRealTime.utils.getFileScopeData converts the format of data2 from the Simulink Real-Time file format to an array of bytes. It also creates a structure for that file in new_data2, of which one of the elements is an array of doubles, data. The data member is also appended with a timestamp vector. The data is returned as doubles, which represent the real-world values of the original Simulink signals at the specified times during target execution.

You can view or examine the signal data. You can also plot the data with plot(new_data2.data).

If you use Simulink Real-Time in standalone mode, you can extract the data from the data file:

  • First determine the file header size. To obtain the file header size, ignore the first 8 bytes of the file. The next 4 bytes store the header size as an unsigned integer.

  • After the header size number of bytes, the file stores the signals sequentially as doubles. For example, assume that the scope has three signals, x, y, and z. Assume that x[0] is the value of x at sample 0, x[1] is the value at sample 1, and so forth. Also assume t[0], t[1] are the simulation time values at samples 0, 1, and so forth. The file saves the data using the following pattern:

    x[0] y[0] z[0] t[0] x[1] y[1] z[1] t[1] x[2] y[2] z[2] t[2]...
    x[N] y[N] z[N] t[N]

    N is the number of samples acquired. The file saves x, y, z, and t as doubles at 8 bytes each.

Removing a File from the Target Computer

You can remove a file from the target computer by using Simulink Real-Time functions on the development computer for the SimulinkRealTime.fileSystem object. If you have not already done so, close this file first with fclose.

To run a SimulinkRealTime.fileSystem object function, use the function_name(fs_object, argument_list) syntax. For example, to remove a file named data2.dat from the target computer C:\ drive (default),

  1. If you have not already done so, in the MATLAB window, type the following to assign the SimulinkRealTime.fileSystem object to a variable.

    fsys = SimulinkRealTime.fileSystem;
  2. Type the following to remove the specified file from the target computer.

    removefile(fsys,'data2.dat')

Getting a List of Open Files on the Target Computer

You can get a list of open files on the target computer file system by using SimulinkRealTime.fileSystem object functions on the development computer. The target computer file system limits the number of open files you can have to eight. Use this list to identify files that you can close.

To run a SimulinkRealTime.fileSystem object function, use the function_name(fs_object, argument_list) syntax. For example, to get a list of open files for the file system object fsys,

  1. If you have not already done so, in the MATLAB window, type the following to assign the SimulinkRealTime.fileSystem object to a variable.

    fsys = SimulinkRealTime.fileSystem;
  2. Type

    filetable(fsys)
    

    If the file system has open files, a list like the following is displayed:

    ans =
    Index    Handle  Flags     FilePos  Name
    ------------------------------------------
        0  00060000  R__          8512  C:\DATA.DAT
        1  00080001  R__             0  C:\DATA1.DAT
        2  000A0002  R__          8512  C:\DATA2.DAT
        3  000C0003  R__          8512  C:\DATA3.DAT
        4  001E0001  R__             0  C:\DATA4.DA
  3. The table returns the open file handles in hexadecimal. To convert a handle to one that other SimulinkRealTime.fileSystem functions, such as fclose, can use, use the hex2dec function. For example,

    h1 = hex2dec('001E0001')
    h1 =
    1966081
  4. To close that file, use the SimulinkRealTime.fileSystem fclose function. For example,

    fclose(fsys, h1)

Getting Information About a File on the Target Computer

You can display information for a file on the target computer file system by using SimulinkRealTime.fileSystem object functions on the development computer.

To run a SimulinkRealTime.fileSystem object function, use the function_name(fs_object, argument_list) syntax. For example, to display the information for the file identifier fid1,

  1. If you have not already done so, in the MATLAB window, type the following to assign the SimulinkRealTime.fileSystem object to a variable.

    fsys = SimulinkRealTime.fileSystem;
  2. Type

    fid1 = fopen(fsys, 'data.dat');

    This command opens the file data.dat for reading and assigns the file identifier to fid1.

  3. Type

    fileinfo(fsys, fid1)

    This returns disk information like the following for the C:\ drive file system.

    ans =        
                   FilePos: 0
             AllocatedSize: 12288
             ClusterChains: 1
        VolumeSerialNumber: 1.0450e+009
                  FullName: 'C:\DATA.DAT'

Getting Information About a Disk on the Target Computer

You can display information for a disk on the target computer file system by using SimulinkRealTime.fileSystem object functions on the development computer.

To run a SimulinkRealTime.fileSystem object function, use the function_name(fs_object, argument_list) syntax. For example, to display the disk information for the C:\ drive,

  1. If you have not already done so, in the MATLAB window, type the following to assign the SimulinkRealTime.fileSystem object to a variable.

    fsys = SimulinkRealTime.fileSystem;
  2. Type

    diskinfo(fsys, 'C:\');

    This returns disk information like the following for the C:\ drive file system.

    ans = 
    
      struct with fields:
    
                DriveLetter: 'C'
                      Label: 'FREEDOS'
                   Reserved: '   '
               SerialNumber: -857442364
        FirstPhysicalSector: 63
                    FATType: 32
                   FATCount: 2
              MaxDirEntries: 0
             BytesPerSector: 512
          SectorsPerCluster: 64
              TotalClusters: 1831212
                BadClusters: 0
               FreeClusters: 1827614
                      Files: 938
                 FileChains: 942
                 FreeChains: 1
           LargestFreeChain: 1827614
                  DriveType: DRIVE_FIXED