Debugging: Recording Information to Disk


Recording information to disk provides a permanent record of your serial port session, and is an easy way to debug your application. While the serial port object is connected to the device, you can record the following information to a disk file:

  • The number of values written to the device, the number of values read from the device, and the data type of the values

  • Data written to the device, and data read from the device

  • Event information

Recording Properties

You record information to a disk file with the record function. The following table shows the properties associated with recording information to disk.

Recording Properties

Property NameDescription


Amount of information saved to a record file


Specify whether data and event information is saved to one record file or to multiple record files


Name of the record file


Indicate if data and event information are saved to a record file

Example: Introduction to Recording Information

This example records the number of values written to and read from the device, and stores the information to the file myfile.txt.

s = serial('COM1');
s.RecordName = 'myfile.txt';
idn = fscanf(s);
rs232 = fscanf(s);

End the serial port session.

clear s

To display myfile.txt at the command line, use the type command.

Creating Multiple Record Files

When you initiate recording with the record function, the RecordMode property determines if a new record file is created or if new information is appended to an existing record file.

You can configure RecordMode to overwrite, append, or index. If RecordMode is overwrite, the record file is overwritten each time recording is initiated. If RecordMode is append, the new information is appended to the file specified by RecordMode. If RecordMode is index, a different disk file is created each time recording is initiated. The rules for specifying a record filename are discussed in the next section.

Specifying a Filename

You specify the name of the record file with the RecordName property. You can specify any value for RecordName — including a directory path — provided the filename is supported by your operating system. Additionally, if RecordMode is index, the filename follows these rules:

  • Indexed filenames are identified by a number. This number precedes the filename extension and is increased by 1 for successive record files.

  • If no number is specified as part of the initial filename, the first record file does not have a number associated with it. For example, if RecordName is myfile.txt, myfile.txt is the name of the first record file, myfile01.txt is the name of the second record file, and so on.

  • RecordName is updated after the record file is closed.

  • If the specified filename already exists, the existing file is overwritten.

The Record File Format

The record file is an ASCII file that contains a record of one or more serial port sessions. You specify the amount of information saved to a record file with the RecordDetail property.

RecordDetail can be compact or verbose. A compact record file contains the number of values written to the device, the number of values read from the device, the data type of the values, and event information. A verbose record file contains the preceding information as well as the data transferred to and from the device.

Binary data with precision given by uchar, schar, (u)int8, (u)int16, or (u)int32 is recorded using hexadecimal format. For example, if the integer value 255 is read from the instrument as a 16-bit integer, the hexadecimal value 00FF is saved in the record file. Single- and double-precision floating-point numbers are recorded as decimal values using the %g format, and as hexadecimal values using the format specified by the IEEE® Standard 754-1985 for Binary Floating-Point Arithmetic.

The IEEE floating-point format includes three components: the sign bit, the exponent field, and the significant field. Single-precision floating-point values consist of 32 bits. The value is given by

Double-precision floating-point values consist of 64 bits. The value is given by

The floating-point format component, and the associated single-precision and double-precision bits are shown in the following table.

ComponentSingle-Precision BitsDouble-Precision Bits










Bit 1 is the left-most bit as stored in the record file.

Example: Recording Information to Disk

This example illustrates how to record information transferred between a serial port object and a Tektronix® TDS 210 oscilloscope. Additionally, the structure of the resulting record file is presented.

  1. Create the serial port object — Create the serial port object s associated with the serial port COM1.

    s = serial('COM1');
  2. Connect to the device — Connect s to the oscilloscope. Because the default value for the ReadAsyncMode property is continuous, data is asynchronously returned the input buffer as soon as it is available from the instrument.

  3. Configure property values — Configure s to record information to multiple disk files using the verbose format. Recording is then initiated with the first disk file defined as WaveForm1.txt.

    s.RecordMode = 'index';
    s.RecordDetail = 'verbose';
    s.RecordName = 'WaveForm1.txt';
  4. Write and read data — The commands written to the instrument, and the data read from the instrument are recorded in the record file. For an explanation of the oscilloscope commands, see Example — Writing and Reading Text Data.

    idn = fscanf(s);
    source = fscanf(s);

    Read the peak-to-peak voltage with the fread function. Note that the data returned by fread is recorded using hex format.

    ptop = fread(s,s.BytesAvailable);

    Convert the peak-to-peak voltage to a character array.

    ans =

    The recording state is toggled from on to off. Because the RecordMode value is index, the record filename is automatically updated.

    ans =
    ans =
  5. Disconnect and clean up — When you no longer need s, disconnect it from the instrument, and remove it from memory and from the MATLAB® workspace.

    clear s

The Record File Contents

The contents of the WaveForm1.txt record file are shown below. Because the RecordDetail property was verbose, the number of values, commands, and data were recorded. Note that data returned by the fread function is in hex format.

type WaveForm1.txt

  * - An event occurred.
  > - A write operation occurred.
  < - A read operation occurred.
1      Recording on 22-Jan-2000 at 11:21:21.575. Binary data in... 
2    > 6 ascii values.
3    < 56 ascii values.
       TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
4    > 29 ascii values.
5    > 26 ascii values.
6    < 4 ascii values.
7    > 27 ascii values.
8    > 25 ascii values.
9    < 15 uchar values.
       32 2e 30 31 39 39 39 39 39 38 30 39 45 30 0a 
10     Recording off.