Serial Port Binary Read and Write Operations

Contents

Introduction

This demo explores binary read and write operations with a serial port object.

The information obtained for this demonstration was prerecorded. Therefore, you do not need an actual instrument to learn about binary read and write operations using a serial port object. The instrument used was a Tektronix TDS 210 oscilloscope.

Functions and Properties

These functions are used when reading and writing binary data:

FREAD            - Read binary data from instrument.
FWRITE           - Write binary data to instrument.

These properties are associated with reading and writing binary data:

ValuesReceived   - Specifies the total number of values
                   read from the instrument.
ValuesSent       - Specifies the total number of values
                   sent to the instrument.
InputBufferSize  - Specifies the total number of bytes
                   that can be queued in the input buffer
                   at one time.
OutputBufferSize - Specifies the total number of bytes
                   that can be queued in the output buffer
                   at one time.

Creating a Serial Port Object

To begin, create a serial port object associated with the COM2 port.

>> s = serial('COM2');
>> s
  Serial Port Object : Serial-COM2
  Communication Settings
     Port:               COM2
     BaudRate:           9600
     Terminator:         'LF'
  Communication State
     Status:             closed
     RecordStatus:       off
  Read/Write State
     TransferStatus:     idle
     BytesAvailable:     0
     ValuesReceived:     0
     ValuesSent:         0

Connecting the Serial Port Object to the Instrument

Before you can perform a read or write operation, you must connect the serial port object to the instrument with the FOPEN function. If the object was successfully connected, its Status property is automatically configured to open. 

>> fopen(s)
>> get(s, 'Status')
ans =
open

Note that the display summary is updated accordingly.

>> s
  Serial Port Object : Serial-COM2
  Communication Settings
     Port:               COM2
     BaudRate:           9600
     Terminator:         'LF'
  Communication State
     Status:             open
     RecordStatus:       off
  Read/Write State
     TransferStatus:     idle
     BytesAvailable:     0
     ValuesReceived:     0
     ValuesSent:         0

Writing Binary Data

You use the FWRITE function to write binary data to the instrument. For example, the following command will send a sine wave to the oscilloscope: 

>> fprintf(s, 'Data:Destination RefA');
>> fprintf(s, 'Data:Encdg SRPbinary');
>> fprintf(s, 'Data:Width 1');
>> fprintf(s, 'Data:Start 1');
>> t = (0:499) .* 8 * pi / 500;
>> data = round(sin(t) * 90 + 127);
>> fprintf(s, 'CURVE #3500');
>> fwrite(s, data)

By default, the FWRITE function operates in a synchronous mode. This means that FWRITE blocks the MATLAB command line until one of the following occurs:

By default the FWRITE function writes binary data using the uchar precision. However, the following precisions can also be used: 

   MATLAB           Description
   'uchar          unsigned character,  8 bits.
   'schar'          signed character,    8 bits.
   'int8'           integer,             8 bits.
   'int16'          integer,             16 bits.
   'int32'          integer,             32 bits.
   'uint8'          unsigned integer,    8 bits.
   'uint16'         unsigned integer,    16 bits.
   'uint32'         unsigned integer,    32 bits.
   'single'         floating point,      32 bits.
   'float32'        floating point,      32 bits.
   'double'         floating point,      64 bits.
   'float64'        floating point,      64 bits.
   'char'           character,           8 bits (signed or unsigned).
   'short'          integer,             16 bits.
   'int'            integer,             32 bits.
   'long'           integer,             32 or 64 bits.
   'ushort'         unsigned integer,    16 bits.
   'uint'           unsigned integer,    32 bits.
   'ulong'          unsigned integer,    32 bits or 64 bits.
   'float'          floating point,      32 bits.

Values Versus Bytes

When performing a write operation, you should think of the transmitted data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

Binary Write Properties -- OutputBufferSize

The OutputBufferSize property specifies the maximum number of bytes that can be written to the instrument at once. By default, OutputBufferSize is 512. 

>> get(s, 'OutputBufferSize')
ans =
   512

If the command specified in FWRITE contains more than 512 bytes, an error is returned and no data is written to the instrument.

Configure the object's output buffer size to 3000. Note, the OutputBufferSize can be configured only when the object is not connected to the instrument. 

>> fclose(s);
>> set(s, 'OutputBufferSize', 3000);
>> fopen(s);

Writing Int16 Binary Data

Now write a waveform as an int16 array.

>> fprintf(s, 'Data:Destination RefB');
>> fprintf(s, 'Data:Encdg SRPbinary');
>> fprintf(s, 'Data:Width 2');
>> fprintf(s, 'Data:Start 1');
>> t = (0:499) .* 8 * pi / 500;
>> data = round(sin(t) * 90 + 127);
>> fprintf(s, 'CURVE #3500');

Note: one int16 value consists of two bytes. Therefore, the following command will write 1000 bytes.

>> fwrite(s, data, 'int16')

Binary Write Properties -- ValuesSent

The ValuesSent property indicates the total number of values written to the instrument since the object was connected to the instrument. 

>> get(s, 'ValuesSent')
ans =
  581

Reading Binary Data

You use the FREAD function to read binary data from the instrument. For example, to read the waveform on channel 1 of the oscilloscope: 

>> fprintf(s, 'Data:Source CH1');
>> fprintf(s, 'Data:Encdg SRPbinary');
>> fprintf(s, 'Data:Width 1');
>> fprintf(s, 'Data:Start 1');
>> fprintf(s, 'Curve?')
>> data = fread(s, s.BytesAvailable);

By default, the FREAD function reads data using the uchar precision and blocks the MATLAB command line until one of the following occurs

By default the FREAD function reads data using the uchar precision. However, the following precisions can also be used:

   MATLAB           Description
   'uchar'          unsigned character,  8 bits.
   'schar'          signed character,    8 bits.
   'int8'           integer,             8 bits.
   'int16'          integer,             16 bits.
   'int32'          integer,             32 bits.
   'uint8'          unsigned integer,    8 bits.
   'uint16'         unsigned integer,    16 bits.
   'uint32'         unsigned integer,    32 bits.
   'single'         floating point,      32 bits.
   'float32'        floating point,      32 bits.
   'double'         floating point,      64 bits.
   'float64'        floating point,      64 bits.
   'char'           character,           8 bits (signed or unsigned).
   'short'          integer,             16 bits.
   'int'            integer,             32 bits.
   'long'           integer,             32 or 64 bits.
   'ushort'         unsigned integer,    16 bits.
   'uint'           unsigned integer,    32 bits.
   'ulong'          unsigned integer,    32 bits or 64 bits.
   'float'          floating point,      32 bits.

Values Versus Bytes

When performing a read operation, you should think of the received data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

Binary Read Properties -- InputBufferSize

The InputBufferSize property specifies the maximum number of bytes that you can read from the instrument. By default, InputBufferSize is 512. 

>> get(s, 'InputBufferSize')
ans =
    512

Reading int16 Binary Data

Now read the same waveform on channel 1 as an int16 array.

>> fprintf(s, 'Data:Source CH1');
>> fprintf(s, 'Data:Encdg SRIbinary');
>> fprintf(s, 'Data:Width 2');
>> fprintf(s, 'Data:Start 1');
>> fprintf(s, 'Curve?')
>> s.BytesAvailable
ans =
 512

Note one int16 value consists of two bytes. Therefore, the following command will read 512 bytes.

>> data = fread(s, 256, 'int16');

Binary Read Properties -- ValuesReceived

The ValuesReceived property is updated by the number of values read from the instrument.

>> get(s, 'ValuesReceived')
ans =
    768

Cleanup

If you are finished with the serial port object, disconnect it from the instrument, remove it from memory, and remove it from the workspace. 

>> fclose(s);
>> delete(s);
>> clear s

Copyright 1999-2004 The MathWorks, Inc.