serialport

Connection to serial port

Description

A serialport object represents a serial client for communication with the serial port. After creating the object, use dot notation to set its properties.

Creation

Syntax

s = serialport(port,baudrate)

s = serialport(port,baudrate,Name,Value)

s = serialport

Description

s = serialport(port,baudrate) connects to the serial port specified by port with a baud rate of baudrate.

s = serialport(port,baudrate,Name,Value) connects to the serial port and sets additional properties using optional name-value pair arguments.

s = serialport, without arguments, connects to the serial port using the property settings of your last cleared serialport object instance. The retained properties are Port, BaudRate, ByteOrder, FlowControl, StopBits, DataBits, Parity, Timeout, and Terminator. See Properties.

Input Arguments

port — Serial port name

character vector | string scalar

Serial port name, specified as a character vector or string scalar. Use serialportlist to get a list of connected ports.

Example: "COM2"

baudrate — Baud rate

double

Baud rate for serial communication, specified as a double.

Example: 9600

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

You can use Name-Value pairs to set the DataBits, Parity, StopBits, FlowControl, ByteOrder, and Timeout object properties. See Properties for their data types and allowed values.

Example: "Timeout",30

Properties

Object Creation Properties

Port — Serial port for connection

string

This property is read-only.

Serial port for connection, returned as a string.

Example: "COM1"

Data Types: string

BaudRate — Communication speed

double

Communication speed in bits per second, returned as a positive integer double.

Example: 14400

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Parity — Parity

"none" (default) | "even" | "odd"

Parity to check whether data has been lost or written, returned as "none", "even", or "odd".

Example: "odd"

Data Types: char | string

DataBits — Number of bits to represent one character of data

8 (default) | 7 | 6 | 5

Number of bits to represent one character of data, returned as 8, 7, 6, or 5.

Example: 8

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

StopBits — Pattern of bits that indicates the end of a character

1 (default) | 1.5 | 2

Pattern of bits that indicates the end of a character or of the whole transmission, returned as 1, 1.5, or 2.

Example: 1

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

FlowControl — Mode for managing data transmission rate

"none" (default) | "hardware" | "software"

Mode for managing data transmission rate, returned as "none", "hardware", or "software".

Example: "software"

Data Types: char | string

ByteOrder — Sequential order of bytes

"little-endian" (default) | "big-endian"

Sequential order in which bytes are arranged into larger numerical values, returned as "little-endian" or "big-endian". Set this property at object creation using a name-value pair argument. You can also change it after object creation using dot notation.

Example: "little-endian"

Data Types: char | string

Timeout — Allowed time to complete operations

10 (default) | numeric

Allowed time in seconds to complete read and write operations, returned as a numeric value. Set this property at object creation using a name-value pair argument. You can also change it after object creation using dot notation.

Example: 60

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Tag — Label for identifying connection

"" (default) | string

Since R2024a

Label for identifying connection, specified as a string. Use Tag to apply a label to a connection that you can use later to access the connection using serialportfind. Doing so can be useful when you open a connection in one function and use a different function to perform operations on the connection. It is also useful for locating and accessing connections in app callbacks.

Example: "pSupply"

Data Types: string

Read and Write Properties

NumBytesAvailable — Number of bytes available to read

numeric

This property is read-only.

Number of bytes available to read, returned as a numeric value.

Example: 1024

Data Types: double

NumBytesWritten — Total number of bytes written to device

0 (default) | numeric

This property is read-only.

Number of bytes written to the serial port, returned as a numeric value.

Example: 512

Data Types: double

Terminator — Terminator character for data

"LF" (default) | "CR" | "CR/LF" | 0 to 255

Terminator character for reading and writing ASCII-terminated data, returned as "LF", "CR", or "CR/LF", or a number from 0 to 255, inclusive. If the read and write terminators are different, Terminator is returned as a 1x2 cell array of these values. Set this property with the configureTerminator function.

Example: "CR"

Data Types: char | string

Callback Properties

BytesAvailableFcnMode — Bytes available callback trigger mode

"off" (default) | "byte" | "terminator"

Bytes available callback trigger mode, returned as "off", "byte", or "terminator". This setting determines if the callback is off, triggered by the number of bytes specified by BytesAvailableFcnCount, or triggered by the terminator specified by Terminator. Set this property with the configureCallback function.

Example: "off"

Data Types: char | string

BytesAvailableFcnCount — Number of bytes of data to trigger callback

64 (default) | numeric value

Number of bytes of data to trigger the callback specified by BytesAvailableFcn, returned as a double. This value is used only when the BytesAvailableFcnMode property is "byte". Set these properties with the configureCallback function.

Example: 128

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

BytesAvailableFcn — Callback function triggered by bytes available event

function handle

Callback function triggered by a bytes available event, returned as a function handle. A bytes available event is generated by receiving a certain number of bytes or a terminator. This property is empty until you assign a function handle. Set this property with the configureCallback function.

Example: @myFcn

Data Types: function_handle

ErrorOccurredFcn — Callback function triggered by error event

function handle

Callback function triggered by an error event, returned as a function handle. An error event is generated when an asynchronous read or write error occurs. This property is empty until you assign a function handle.

Example: @myErrFcn

Data Types: function_handle

UserData — General purpose property for user data

any type

General purpose property for user data, returned as any MATLAB^® data type. For example, you can use this property to store data when an event is triggered from a callback function.

Example: datetime()

Object Functions

read	Read data from serial port
readline	Read line of ASCII string data from serial port
readbinblock	Read one binblock of data from serial port
write	Write data to serial port
writeline	Write line of ASCII data to serial port
writebinblock	Write one binblock of data to serial port
writeread	Write command to serial port and read response
serialbreak	Send break to device connected to serial port
flush	Clear serial port device buffers
configureTerminator	Set terminator for ASCII string communication with serial port
configureCallback	Set callback function and trigger condition for communication with serial port device
getpinstatus	Get serial pin status
setRTS	Set serial RTS pin
setDTR	Set serial DTR pin
delete	Remove instrument objects from memory
clear	Remove instrument objects from MATLAB workspace

Examples

Read Data from Serial Port

Read 16 values of uint32 data from the COM3 serial port.

s = serialport("COM3",9600,"Timeout",5);
data = read(s,16,"uint32");

Disconnect Single Serial Port Connection

When you use serialport in a script or at the MATLAB command line, the result is a connection represented by an object in the MATLAB workspace.

s1 = serialport("COM3",9600)

s1 = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
                  Tag: ""
    NumBytesAvailable: 0

When no references to the same connection exist in other variables, you can disconnect the serial port by clearing the workspace variable.

clear(s1)

Use serialportfind to confirm that the connection is closed.

serialportfind

ans =

     []

Disconnect Serial Port Connections in Functions or App Callbacks

When you have a serialport connection that exists in the MATLAB workspace or is saved as a class property or app property, the serialport object might not be accessible in a different function or app callback. In this case, you can use serialportfind to find and delete the connection.

S = serialportfind

S = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
                  Tag: ""
    NumBytesAvailable: 0

To close this connection, delete S.

delete(S)

This command deletes the serialport object and disconnects the device. If you want to reconnect to the device, you must create a new interface with serialport.

After the deletion, calling serialportfind confirms that there are no existing connections.

serialportfind

ans =

     []

Note that the variable S is still present in the workspace, but it is now an invalid handle.

S

S = 

  handle to deleted Serialport

The variable persists after deletion of the interface because serialport is a handle object. (For more information about this type of object, see Handle Object Behavior.) You can use clear to remove the invalid handle from the workspace.

clear S

Version History

Introduced in R2019b

R2024a: New Tag Property

Use the new Tag property to apply a label to a connection that you can use later to access the connection using serialportfind.