serialport

Connection to serial port

expand all in page

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.

example

Input Arguments

expand all

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

Example: "COM2"

Baud rate for serial communication, specified as a double.

Example: 9600

Name-Value Arguments

expand all

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

expand all

Object Creation Properties

This property is read-only.

Serial port for connection, returned as a string.

Example: "COM1"

Data Types: string

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 to check whether data has been lost or written, returned as "none", "even", or "odd".

Example: "odd"

Data Types: char | string

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

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

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

Example: "software"

Data Types: char | string

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

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

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

This property is read-only.

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

Example: 1024

Data Types: double

This property is read-only.

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

Example: 512

Data Types: double

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

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

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

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

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

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

readRead data from serial port
readlineRead line of ASCII string data from serial port
readbinblockRead one binblock of data from serial port
writeWrite data to serial port
writelineWrite line of ASCII data to serial port
writebinblockWrite one binblock of data to serial port
writereadWrite command to serial port and read response
serialbreakSend break to device connected to serial port
flushClear serial port device buffers
configureTerminatorSet terminator for ASCII string communication with serial port
configureCallbackSet callback function and trigger condition for communication with serial port device
getpinstatusGet serial pin status
setRTSSet serial RTS pin
setDTRSet serial DTR pin
deleteRemove instrument objects from memory
clearRemove instrument objects from MATLAB workspace

Examples

collapse all

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

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

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 =

     []

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

expand all

See Also

Functions

Topics