serialport

连接到串行端口

全页展开

说明

serialport 对象表示与串行端口通信的串行客户端。在创建对象后，请使用圆点表示法设置其属性。

创建对象

语法

s = serialport(port,baudrate)

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

s = serialport

描述

s = serialport(port,baudrate) 连接到 port 指定的串行端口，波特率为 baudrate。

s = serialport(port,baudrate,Name,Value) 连接到串行端口，并使用可选的名称-值对组参量设置其他属性。

s = serialport（不带参量）使用上次清除的 serialport 对象实例的属性设置连接到串行端口。保留的属性包括 Port、BaudRate、ByteOrder、FlowControl、StopBits、DataBits、Parity、Timeout 和 Terminator。请参阅属性。

示例

输入参量

全部展开

`port` — 串行端口名称
字符向量 | 字符串标量

串行端口名称，指定为字符向量或字符串标量。使用 serialportlist 获取已连接端口的列表。

示例: "COM2"

`baudrate` — 波特率
双精度值

串行通信的波特率，指定为双精度。

示例: 9600

名称-值参数

全部展开

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

您可以使用名称-值对组来设置 DataBits、Parity、StopBits、FlowControl、ByteOrder 和 Timeout 对象属性。请参阅属性了解其数据类型和允许的值。

示例: "Timeout",30

属性

全部展开

对象的创建属性

`Port` — 用于连接的串行端口
只读: 字符串

此属性为只读。

用于连接的串行端口，以字符串形式返回。

示例: "COM1"

数据类型: string

`BaudRate` — 通信速度
双精度值

通信速度，以位/秒为单位，以双精度正整数形式返回。

示例: 14400

`Parity` — 奇偶校验
`"none"` (默认) | `"even"` | `"odd"`

用于检查数据是否丢失或写入的奇偶校验，以 "none"、"even" 或 "odd" 形式返回。

示例: "odd"

数据类型: char | string

`DataBits` — 表示一个数据字符的位数
`8` (默认) | `7` | `6` | `5`

表示一个数据字符的位数，返回为 8、7、6 或 5。

示例: 8

`StopBits` — 指示字符结束的位的模式
`1` (默认) | `1.5` | `2`

指示字符或整个传输结束的位的模式，返回为 1、1.5 或 2。

示例: 1

`FlowControl` — 管理数据传输速率的模式
`"none"` (默认) | `"hardware"` | `"software"`

管理数据传输速率的模式，返回为 "none"、"hardware" 或 "software"。

示例: "software"

数据类型: char | string

`ByteOrder` — 字节的顺序
`"little-endian"` (默认) | `"big-endian"`

字节排列成较大数值的顺序，返回为 "little-endian" 或 "big-endian"。使用名称-值对组参量在创建对象时设置此属性。您也可以在创建对象后使用圆点表示法更改它。

示例: "little-endian"

数据类型: char | string

`Timeout` — 允许的完成操作的时间
10 (默认) | 数值

允许的完成读写操作的时间（以秒为单位），以数值形式返回。使用名称-值对组参量在创建对象时设置此属性。您也可以在创建对象后使用圆点表示法更改它。

示例: 60

`Tag` — 用于标识连接的标签
`""` (默认) | 字符串

自 R2024a 起

用于标识连接的标签，指定为字符串。使用 Tag 将标签应用于连接，您可以稍后使用 serialportfind 访问该连接。当您在一个函数中打开连接并使用另一个函数对该连接执行操作时，这样做非常有用。它对于定位和访问 App 回调中的连接也很有用。

示例: "pSupply"

数据类型: string

读取和写入属性

`NumBytesAvailable` — 可供读取的字节数
只读: 数值

此属性为只读。

可供读取的字节数，以数值形式返回。

示例: 1024

数据类型: double

`NumBytesWritten` — 写入设备的字节总数
只读: 0 (默认) | 数值

此属性为只读。

写入串行端口的字节数，以数值形式返回。

示例: 512

数据类型: double

`Terminator` — 数据的终止符字符
`"LF"` (默认) | `"CR"` | `"CR/LF"` | 0 至 255

用于读取和写入以 ASCII 字符结尾的数据的终止符字符，返回为 "LF"、"CR" 或 "CR/LF"，或从 0 到 255（包括两者）的数字。如果读取终止符和写入终止符不同，则 Terminator 以这些值的 1×2 元胞数组形式返回。使用 configureTerminator 函数设置此属性。

示例: "CR"

数据类型: char | string

回调属性

`BytesAvailableFcnMode` — 字节可用回调触发模式
`"off"` (默认) | `"byte"` | `"terminator"`

字节可用回调触发模式，返回为 "off"、"byte" 或 "terminator"。此设置确定回调是关闭、由 BytesAvailableFcnCount 指定的字节数触发还是由 Terminator 指定的终止符触发。使用 configureCallback 函数设置此属性。

示例: "off"

数据类型: char | string

`BytesAvailableFcnCount` — 触发回调的数据字节数
64 (默认) | 数值

由 BytesAvailableFcn 指定的触发回调的数据字节数，以双精度形式返回。仅当 BytesAvailableFcnMode 属性为 "byte" 时，才使用此值。使用 configureCallback 函数设置这些属性。

示例: 128

`BytesAvailableFcn` — 由字节可用事件触发的回调函数
函数句柄

由字节可用事件触发的回调函数，以函数句柄形式返回。接收到一定数量的字节或终止符会生成字节可用事件。在分配函数句柄之前，此属性为空。使用 configureCallback 函数设置此属性。

示例: @myFcn

数据类型: function_handle

`ErrorOccurredFcn` — 由错误事件触发的回调函数
函数句柄

由错误事件触发的回调函数，以函数句柄形式返回。发生异步读取或写入错误时，会生成错误事件。在分配函数句柄之前，此属性为空。

示例: @myErrFcn

数据类型: function_handle

`UserData` — 用户数据的通用属性
任意类型

用户数据的通用属性，以任何 MATLAB^® 数据类型形式返回。例如，当回调函数触发事件时，可以使用此属性存储数据。

示例: datetime()

对象函数

`read`	从串行端口读取数据
`readline`	从串行端口读取 ASCII 字符串数据行
`write`	将数据写入串行端口
`writeline`	将 ASCII 数据行写入串行端口
`serialbreak`	Send break to device connected to serial port
`flush`	清空串行端口设备缓冲区
`configureTerminator`	为与串行端口的 ASCII 字符串通信设置终止符
`configureCallback`	为与串行端口设备的通信设置回调函数和触发条件
`getpinstatus`	获取串行引脚状态
`setRTS`	设置串行 RTS 引脚
`setDTR`	设置串行 DTR 引脚
`delete`	删除句柄对象
`clear`	从工作区中删除项目、释放系统内存

示例

全部折叠

从串行端口读取数据

从 COM3 串行端口读取 uint32 数据的 16 个值。

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

断开与单个串行端口的连接

当您在脚本中或在 MATLAB 命令行中使用 serialport 时，结果是由 MATLAB 工作区中的对象表示的连接。

s1 = serialport("COM3",9600)

s1 = 

  Serialport with properties:

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

当其他变量中不存在对该同一连接的引用时，可以通过清除工作区变量来断开与串行端口的连接。

clear(s1)

使用 serialportfind 确认连接已关闭。

serialportfind

ans =

     []

在函数或 App 回调中断开与串行端口的连接

当一个 serialport 连接存在于 MATLAB 工作区中或保存为类属性或 App 属性时，可能无法在不同函数或 App 回调中访问 serialport 对象。在这种情况下，您可以使用 serialportfind 查找和删除该连接。

S = serialportfind

S = 

  Serialport with properties:

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

要关闭此连接，请删除 S。

delete(S)

此命令删除 serialport 对象并断开与设备的连接。如果您要重新连接到该设备，必须使用 serialport 创建一个新接口。

在删除后，调用 serialportfind 确认没有现有连接。

serialportfind

ans =

     []

请注意，变量 S 仍存在于工作区中，但它现在是无效句柄。

S = 

  handle to deleted Serialport

由于 serialport 是句柄对象，因此该变量在删除接口后仍存在。（有关这种类型的对象的详细信息，请参阅句柄对象行为。）您可以使用 clear 从工作区中删除无效的句柄。

clear S

版本历史记录

在 R2019b 中推出

全部展开

R2024a: 新的 `Tag` 属性

使用新的 Tag 属性将标签应用于连接，您可以稍后使用 serialportfind 访问该连接。

另请参阅

函数

serialportlist | serialportfind | read | write | delete | clear

serialport

说明

创建对象

语法

描述

输入参量

port — 串行端口名称 字符向量 | 字符串标量

baudrate — 波特率 双精度值

名称-值参数

属性

对象的创建属性

Port — 用于连接的串行端口 只读: 字符串

BaudRate — 通信速度 双精度值

Parity — 奇偶校验 "none" (默认) | "even" | "odd"

DataBits — 表示一个数据字符的位数 8 (默认) | 7 | 6 | 5

StopBits — 指示字符结束的位的模式 1 (默认) | 1.5 | 2

FlowControl — 管理数据传输速率的模式 "none" (默认) | "hardware" | "software"

ByteOrder — 字节的顺序 "little-endian" (默认) | "big-endian"

Timeout — 允许的完成操作的时间 10 (默认) | 数值

Tag — 用于标识连接的标签 "" (默认) | 字符串

读取和写入属性

NumBytesAvailable — 可供读取的字节数 只读: 数值

NumBytesWritten — 写入设备的字节总数 只读: 0 (默认) | 数值

Terminator — 数据的终止符字符 "LF" (默认) | "CR" | "CR/LF" | 0 至 255

回调属性

BytesAvailableFcnMode — 字节可用回调触发模式 "off" (默认) | "byte" | "terminator"

BytesAvailableFcnCount — 触发回调的数据字节数 64 (默认) | 数值

BytesAvailableFcn — 由字节可用事件触发的回调函数 函数句柄

ErrorOccurredFcn — 由错误事件触发的回调函数 函数句柄

UserData — 用户数据的通用属性 任意类型

对象函数

示例

从串行端口读取数据

断开与单个串行端口的连接

在函数或 App 回调中断开与串行端口的连接

版本历史记录

R2024a: 新的 Tag 属性

另请参阅

函数

`port` — 串行端口名称
字符向量 | 字符串标量

`baudrate` — 波特率
双精度值

`Port` — 用于连接的串行端口
只读: 字符串

`BaudRate` — 通信速度
双精度值

`Parity` — 奇偶校验
`"none"` (默认) | `"even"` | `"odd"`

`DataBits` — 表示一个数据字符的位数
`8` (默认) | `7` | `6` | `5`

`StopBits` — 指示字符结束的位的模式
`1` (默认) | `1.5` | `2`

`FlowControl` — 管理数据传输速率的模式
`"none"` (默认) | `"hardware"` | `"software"`

`ByteOrder` — 字节的顺序
`"little-endian"` (默认) | `"big-endian"`

`Timeout` — 允许的完成操作的时间
10 (默认) | 数值

`Tag` — 用于标识连接的标签
`""` (默认) | 字符串

`NumBytesAvailable` — 可供读取的字节数
只读: 数值

`NumBytesWritten` — 写入设备的字节总数
只读: 0 (默认) | 数值

`Terminator` — 数据的终止符字符
`"LF"` (默认) | `"CR"` | `"CR/LF"` | 0 至 255

`BytesAvailableFcnMode` — 字节可用回调触发模式
`"off"` (默认) | `"byte"` | `"terminator"`

`BytesAvailableFcnCount` — 触发回调的数据字节数
64 (默认) | 数值

`BytesAvailableFcn` — 由字节可用事件触发的回调函数
函数句柄

`ErrorOccurredFcn` — 由错误事件触发的回调函数
函数句柄

`UserData` — 用户数据的通用属性
任意类型

R2024a: 新的 `Tag` 属性