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.

Serial Port Properties

Configure serial port communications

Serial port properties are used to configure communications using the serial object and to configure read and write behavior.

Some properties can be set during object creation with the serial function. See the serial reference page for information about those properties, which include Port, BaudRate, ByteOrder, DataBits, Parity, StopBits, and Terminator.

Read and write properties are used to configure factors involved in the reading and writing of data, such as setting a timeout for completing the operation. Use control pin properties to configure the state of control pins and data flow control. Use recording properties to set up and control recording information to disk.

Note

This sample syntax for all the properties assumes you have created a serial object, s. Many of the properties can only be set before calling fopen on the object. Some can be changed while the object is open.

Properties can be set after you create the serial object. A read-only property is called as follows:

s = serial('COM1');
s.TransferStatus
ans = 
     idle

A property you can configure is set as follows:

s = serial('COM1');
s.Timeout = 30;

Read and Write Properties

expand all

Number of bytes available in the input buffer, specified as a double. This read-only property indicates the number of bytes currently available to be read from the input buffer. The property value is continuously updated as the input buffer is filled, and is set to 0 after the fopen function is issued.

You can make use of BytesAvailable only when reading data asynchronously. This is because when reading data synchronously, control is returned to the MATLAB® command line only after the input buffer is empty. Therefore, the BytesAvailable value is always 0.

The BytesAvailable value can range from zero to the size of the input buffer. Use the InputBufferSize property to specify the size of the input buffer. Use the ValuesReceived property to return the total number of values read.

Example: s.BytesAvailable

Data Types: double

Size of the input buffer in bytes, specified as a double. You configure InputBufferSize as the total number of bytes that can be stored in the input buffer during a read operation.

A read operation is terminated if the amount of data stored in the input buffer equals the InputBufferSize value. You can read text data with the fgetl, fget, or fscanf functions. You can read binary data with the fread function.

You can configure InputBufferSize only when the serial port object is disconnected from the device. You can configure it before calling the fopen function. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

If you configure InputBufferSize while there is data in the input buffer, that data is purged.

Example: s.InputBufferSize = 768;

Data Types: double

Specify whether an asynchronous read operation is continuous or manual, specified as manual or continuous. If ReadAsyncMode is continuous, the serial port object continuously queries the device to determine if data is available to be read. If data is available, it is automatically read and stored in the input buffer. If issued, the readasync function is ignored.

If ReadAsyncMode is manual, the object does not query the device to determine if data is available to be read. Instead, you must manually issue the readasync function to perform an asynchronous read operation. Because readasync checks for the terminator, this function can be slow. To increase speed, configure ReadAsyncMode to continuous.

Note

If the device is ready to transmit data, it will do so regardless of the ReadAsyncMode value. Therefore, if ReadAsyncMode is manual and a read operation is not in progress, data might be lost. To guarantee that all transmitted data is stored in the input buffer, you should configure ReadAsyncMode to continuous.

To determine the amount of data available in the input buffer, use the BytesAvailable property. For either ReadAsyncMode value, you can bring data into the MATLAB workspace with one of the synchronous read functions such as fscanf, fgetl, fgets, or fread.

Example: s.ReadAsyncMode = 'manual';

Data Types: char | string

Waiting time to complete a read or write operation, specified as a double. You configure Timeout to be the maximum time (in seconds) to wait to complete a read or write operation. The default value of 10 seconds is used if you do not specify a different value. Timeouts are rounded upwards to full seconds.

If a timeout occurs, the read or write operation aborts. Additionally, if a timeout occurs during an asynchronous read or write operation, then:

  • An error event is generated.

  • The callback function specified for ErrorFcn is executed.

Example: s.Timeout = 30;

Data Types: double

Status of asynchronous read or write operation, specified as idle, read, write, or read&write. This read-only property indicates if an asynchronous read or write operation is in progress. If TransferStatus is idle, no asynchronous read or write operations are in progress. If it is read, an asynchronous read operation is in progress. If it is write, an asynchronous write operation is in progress. If TransferStatus is read&write, both an asynchronous read and an asynchronous write operation are in progress.

You can write data asynchronously using the fprintf or fwrite functions. You can read data asynchronously using the readasync function, or by configuring the ReadAsyncMode property to continuous. While readasync is executing, TransferStatus might indicate that data is being read even though data is not filling the input buffer. If ReadAsyncMode is continuous, TransferStatus indicates that data is being read only when data is filling the input buffer.

You can execute an asynchronous read and an asynchronous write operation simultaneously because serial ports have separate read and write pins.

Summary the possible values:

{idle}

No asynchronous operations are in progress.

read

An asynchronous read operation is in progress.

write

An asynchronous write operation is in progress.

read&write

Asynchronous read and write operations are in progress.

Example: s.TransferStatus

Data Types: char | string

Total number of values read from the device, specified as a double. This is a read-only property, and the value is updated after each successful read operation and set to 0 after the fopen function is issued. If the terminator is read from the device, then this value is reflected by ValuesReceived.

If you are reading data asynchronously, use the BytesAvailable property to return the number of bytes currently available in the input buffer.

When performing a read operation, the received data is represented by values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

For example, create a serial port object associated with the serial port COM1, and open the connection.

s = serial('COM1');
fopen(s)

If you write the RS232? command, and read back the response using fscanf, ValuesReceived is 17 because the instrument is configured to send the LF terminator.

fprintf(s,'RS232?')
out = fscanf(s)
out =
9600;0;0;NONE;LF
s.ValuesReceived
ans =
    17

Example: s.ValuesReceived

Data Types: double

Number of bytes currently in the output buffer, specified as a double. This read-only property indicates the number of bytes currently in the output buffer waiting to be written to the device. The property value is continuously updated as the output buffer is filled and emptied, and is set to 0 after the fopen function is issued.

You can make use of BytesToOutput only when writing data asynchronously. This is because when writing data synchronously, control is returned to the MATLAB command line only after the output buffer is empty. Therefore, the BytesToOutput value is always 0.

Use the ValuesSent property to return the total number of values written to the device.

Note

If you attempt to write out more data than can fit in the output buffer, an error is returned and BytesToOutput is 0. Specify the size of the output buffer with the OutputBufferSize property.

Example: s.BytesToOutput

Data Types: double

Size of the output buffer in bytes, specified as a double. You configure OutputBufferSize as the total number of bytes that can be stored in the output buffer during a write operation.

You can configure OutputBufferSize only when the serial port object is disconnected from the device. You can configure it before calling the fopen function. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

An error occurs if the output buffer cannot hold all the data to be written. You write text data with the fprintf function. You write binary data with the fwrite function.

Example: s.OutputBufferSize = 256;

Data Types: double

Total number of values written to the device, specified as a double. This is a read-only property, and the value is updated after each successful write operation and set to 0 after the fopen function is issued. If you are writing the terminator, ValuesSent reflects this value.

If you are writing data asynchronously, use the BytesToOutput property to return the number of bytes currently in the output buffer.

When performing a write operation, the transmitted data is represented by values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

For example, create a serial port object associated with the serial port COM1 and open the connection.

s = serial('COM1');
fopen(s)

If you write the *IDN? command using the fprintf function, ValuesSent is 6 because the default data format is %s\n, and the terminator was written.

fprintf(s,'*IDN?')
s.ValuesSent
ans =
    6

Example: s.ValuesSent

Data Types: double

Status of serial port device connection, returned as closed or open. This read-only property indicates whether the serial port object is connected to the device. If Status is closed, the serial port object is not connected to the device. If Status is open, the serial port object is connected to the device.

Before you can write or read data, you must connect the serial port object to the device with the fopen function. Use the fclose function to disconnect a serial port object from the device.

Example: s.Status

Data Types: char | string

Control Pin Properties

expand all

State of the DTR pin, specified as on or off. If DataTerminalReady is on, the Data Terminal Ready (DTR) pin is asserted. If DataTerminalReady is off, the DTR pin is unasserted.

In normal usage, the DTR and Data Set Ready (DSR) pins work together, and are used to signal if devices are connected and powered. However, there is nothing in the RS-232 standard that states the DTR pin must be used in any specific way. For example, DTR and DSR might be used for handshaking. You should refer to your device documentation to determine its specific pin behavior.

You can return the value of the DSR pin with the PinStatus property.

Example: s.DataTerminalReady = 'off';

Data Types: char | string

Data flow control method, specified as none, hardware, or software. If FlowControl is none, data flow control (handshaking) is not used. If FlowControl is hardware, hardware handshaking is used to control data flow. If FlowControl is software, software handshaking is used to control data flow.

Hardware handshaking typically utilizes the Request to Send (RTS) and Clear to Send (CTS) pins to control data flow. Software handshaking uses control characters (Xon and Xoff) to control data flow.

You can return the value of the CTS pin with the PinStatus property. You can specify the value of the RTS pin with the RequestToSend property. However, if FlowControl is hardware, and you specify a value for RequestToSend, that value might not be honored.

Note

Although you might be able to configure your device for both hardware handshaking and software handshaking at the same time, MATLAB does not support this behavior.

Example: s.FlowControl = 'hardware';

Data Types: char | string

State of the CD, CTS, DSR, and RI pins, returned as a structure. This read-only property returns a structure array that contains the fields CarrierDetect, ClearToSend, DataSetReady and RingIndicator. These fields indicate the state of the Carrier Detect (CD), Clear to Send (CTS), Data Set Ready (DSR) and Ring Indicator (RI) pins, respectively.

PinStatus can be on or off for any of these fields. A value of on indicates the associated pin is asserted. A value of off indicates the associated pin is unasserted. A pin status event occurs when any of these pins changes its state. A pin status event executes the call back function specified by PinStatusFcn.

In normal usage, the Data Terminal Ready (DTR) and DSR pins work together, while the Request to Send (RTS) and CTS pins work together. You can specify the state of the DTR pin with the DataTerminalReady property. You can specify the state of the RTS pin with the RequestToSend property.

Example: s.PinStatus

Data Types: struct

State of the RTS pin, specified as on or off. If RequestToSend is on, the Request to Send (RTS) pin is asserted. If RequestToSend is off, the RTS pin is unasserted.

In normal usage, the RTS and Clear to Send (CTS) pins work together, and are used as standard handshaking pins for data transfer. In this case, RTS and CTS are automatically managed by the DTE and DCE. However, there is nothing in the RS-232 standard that requires the RTS pin must be used in any specific way. Therefore, if you manually configure the RequestToSend value, it is probably for nonstandard operations.

If your device does not use hardware handshaking in the standard way, and you need to manually configure RequestToSend, configure the FlowControl property to none. Otherwise, the RequestToSend value that you specify might not be honored. Refer to your device documentation to determine its specific pin behavior.

You can return the value of the CTS pin with the PinStatus property.

Example: s.RequestToSend = 'off';

Data Types: char | string

Recording Properties

expand all

Detail level of information saved to a record file, specified as compact or verbose. If RecordDetail is compact, 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 are saved to the record file. If RecordDetail is verbose, the data written to the device and the data read from the device are also saved to the record file.

Summary of the possible values:

{compact}

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 are saved to the record file.

verbose

The data written to the device, and the data read from the device are also saved to the record file.

Example: s.RecordDetail = 'verbose';

Data Types: char | string

Method for saving data and event information in record files, specified as overwrite, append, or index. If RecordMode is overwrite, the record file is overwritten each time recording is initiated. If RecordMode is append, data is appended to the record file each time recording is initiated. If RecordMode is index, a different record file is created each time recording is initiated, each with an indexed filename.

You can configure RecordMode only when the object is not recording. You terminate recording with the record function. An object that is not recording has a RecordStatus property value of off.

You specify the record filename with the RecordName property. The indexed filename follows a prescribed set of rules.

Summary of the possible values:

{overwrite}

The record file is overwritten.

append

Data is appended to an existing record file.

index

A different record file is created, each with an indexed filename.

For example, record serial data using the record properties. Create the serial port object and open the connection.

s = serial('COM1');
fopen(s)

Specify the record filename with the RecordName property, configure RecordMode to index, and initiate recording.

s.RecordName = 'MyRecord.txt';
s.RecordMode = 'index';
record(s)

The record filename is automatically updated with an indexed filename after recording is turned off.

record(s,'off')
s.RecordName
ans =
MyRecord01.txt

Disconnect s from the peripheral device, remove s from memory, and remove s from the MATLAB workspace.

fclose(s)
delete(s)
clear s

Example: s.RecordMode = 'index';

Data Types: char | string

Name of the record file, specified as a string. You can specify any value for RecordName - including a directory path - provided the file name is supported by your operating system.

The default record filename is record.txt, which is used if you record a data file and do not specify a different name.

MATLAB supports any file name supported by your operating system. You can access the file using the type function. For example, if you name the record file MyRecord.txt, to type this file at the MATLAB command line, enter:

type('MyRecord.txt')

You can specify whether data and event information are saved to one disk file or to multiple disk files with the RecordMode property. If RecordMode is index, the filename follows a prescribed set of rules.

You can configure RecordName only when the object is not recording. You terminate recording with the record function. An object that is not recording has a RecordStatus property value of off.

Example: s.RecordName = 'MonthlyDataFile_April';

Data Types: char | string

Status of recording serial data and event information, returned as on or off. This read-only property indicates whether recording is on or off, which is controlled by the record function. If RecordStatus is off, then data and event information are not saved to a record file. If RecordStatus is on, then data and event information are saved to the record file specified by RecordName.

Use the record function to initiate or complete recording. RecordStatus is automatically configured to reflect the recording state.

Example: s.RecordStatus

Data Types: char | string

Introduced before R2006a