Serial Port ASCII Read and Write Operations

Contents

• Introduction
• Functions and Properties
• Creating a Serial Port Object
• Connecting the Serial Port Object to the Instrument
• Writing ASCII Data
• ASCII Write Properties -- OutputBufferSize
• ASCII Write Properties -- ValuesSent
• Reading ASCII Data
• ASCII Read Properties -- InputBufferSize
• ASCII Read Properties -- ValuesReceived
• Cleanup

Introduction

This demo explores ASCII 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 ASCII 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 text:

FPRINTF          - Write text to instrument.
FSCANF           - Read data from instrument and format as
                   text.

These properties are associated with reading and writing text:

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.
Terminator       - Character used to terminate commands
                   sent to the instrument.

Creating a Serial Port Object

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

>> s = serial('COM2');
>> set(s, 'Terminator', 'CR');
>> s

  Serial Port Object : Serial-COM2

  Communication Settings
     Port:               COM2
     BaudRate:           9600
     Terminator:         'CR'

  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

Writing ASCII Data

You use the FPRINTF function to write ASCII data to the instrument. For example, the 'Display:Contrast' command will change the display contrast of the oscilloscope.

>> fprintf(s, 'Display:Contrast 45')

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

• All the data is written
• A timeout occurs as specified by the Timeout property

By default the FPRINTF function writes ASCII data using the %s\n format. All occurrences of \n in the command being written to the instrument are replaced with the Terminator property value. When using the default format, %s\n, all commands written to the instrument will end with the Terminator character.

For the previous command, the carriage return (CR) is sent after 'Display:Contrast 45' is written to the oscilloscope, thereby indicating the end of the command.

You can also specify the format of the command written by specifying a third input argument to FPRINTF. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.

For example, the display contrast command previously shown can be written to the instrument using three calls to FPRINTF.

>> fprintf(s, '%s', 'Display:');
>> fprintf(s, '%s', 'Contrast');
>> fprintf(s, '%s\n', ' 45');

The Terminator character indicates the end of the command and is sent after the last call to FPRINTF.

ASCII 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 FPRINTF contains more than 512 bytes, an error is returned and no data is written to the instrument.

ASCII 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 =

  40

Reading ASCII Data

You use the FSCANF function to read ASCII data from the instrument. For example, the oscilloscope command 'Display:Contrast?' returns the oscilloscope's display contrast:

>> fprintf(s, 'Display:Contrast?')
>> data = fscanf(s)

data =

45

By default, the FSCANF function reads data using the '%c' format and blocks the MATLAB command line until one of the following occurs:

• The terminator is received as specified by the Terminator property
• A timeout occurs as specified by the Timeout property
• The input buffer is filled
• The specified number of values is read

You can also specify the format of the data read by specifying a second input argument to FSCANF. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.

For example, the following command returns the display contrast as a double.

>> fprintf(s, 'Display:Contrast?')
>> data = fscanf(s, '%d')

data =

   45

>> isnumeric(data)

ans =

    1

ASCII 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

ASCII Read Properties -- ValuesReceived

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

>> get(s, 'ValuesReceived')

ans =

   6

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.