Main Content

serialport

Connection to serial port

Since R2019b

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

Description

example

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

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

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

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

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");

Version History

Introduced in R2019b