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
Description
connects to the serial port specified by s
= serialport(port
,baudrate
)port
with a baud rate of
baudrate
.
connects to the serial port and sets additional properties using optional name-value pair
arguments.s
= serialport(port
,baudrate
,Name,Value
)
, without arguments, connects
to the serial port using the property settings of your last cleared
s
= serialportserialport
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
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 |
write | Write data to serial port |
writeline | Write line of ASCII data to serial port |
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 | Delete handle object |
clear | Remove items from workspace, freeing up system memory |
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 R2019bR2024a: 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
.
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)