serial 属性

串行端口对象的描述性名称，指定为字符向量或字符串。当您创建串行端口对象时，描述性名称会自动生成并存储在 Name 中。此名称是通过将“Serial”一词与 serial 函数中指定的串行端口串联起来而给出的。但是，您可以随时更改 Name 的值。

串行端口由 Port 属性提供。如果您修改此属性值，则 Name 会自动更新以反映该更改。

示例: s.Name = 'MySerialDevice';

串行端口名称，指定为字符向量或字符串。seriallist 函数提供可用串行端口的列表。您必须指定端口才能创建串行端口对象。

端口名称取决于串行端口所在的平台。该列表是不同平台上的串行构造函数示例。

示例: s.Port

与串行端口对象相关联的标签，指定为字符向量或字符串。Tag 唯一标识串行端口对象。Tag 在构造程序时特别有用，否则需要将串行端口对象定义为全局变量，或者将该对象作为参量在回调例程之间传递。

通过指定 Tag 属性值，可以使用 instrfind 函数返回串行端口对象。

示例: s.Tag = 'MySerialObj';

对象类型，指定为 serial。使用 serial 函数创建串行端口对象后，会自动定义 Type。Type 值始终为 serial。

示例: s.Type

要与串行端口对象关联的数据，指定为 MATLAB 数组。UserData 可用于配置要存储的与串行端口对象关联的数据。该对象不直接使用此数据，但您可以使用 get 函数或圆点表示法来访问它。

控制对串行端口对象的访问，指定为 'on' 或 'off'。它为应用程序开发人员提供一种防止最终用户访问其应用程序创建的串行端口对象的方法。当对象的 ObjectVisibility 属性设置为 'off' 时，instrfind 不会返回或删除该对象。

不可见的对象仍然有效。如果您可以访问该对象（例如，从创建该对象的文件中访问），您可以设置和获取它的属性，并将其传递给对串行端口对象进行操作的任何函数。

示例: s.ObjectVisibility = 'off';

设备的字节顺序，指定为 littleEndian 或 bigEndian。如果 ByteOrder 是 littleEndian，则设备将第一个字节存储在第一个内存地址中。如果 ByteOrder 是 bigEndian，则设备将最后一个字节存储在第一个内存地址中。

例如，假设十六进制值 4F52 将存储在设备内存中。因为该值由两个字节 4F 和 52 组成，所以使用两个内存位置。使用 big-endian 格式时，4F 首先存储在较低的存储地址中。使用 little-endian 格式时，52 首先存储在较低的存储地址中。

littleEndian 的字节顺序是默认值，如果未指定属性，则在读取和写入操作中使用该默认值。您只需指定属性即可将字节顺序更改为 bigEndian。

使用以下语法创建串行对象后，还可以设置 ByteOrder 属性：

s.ByteOrder = 'bigEndian';

示例: s.ByteOrder = 'bigEndian';

位传输速率，指定为双精度值。您将波特率配置为位/秒。传输的位包括开始位、数据位、奇偶校验位（如果用到）和停止位。但是，存储的位只有数据位。

波特率是指通信通道中传输信息的速率。在串行端口环境中，“9600 波特”表示串行端口每秒最多可以传输 9600 位。如果信息单位是一波特（一位），则比特率和波特率相同。如果一波特等于 10 位（例如，8 个数据位加 2 个成帧位），则比特率仍是 9600，而波特率是 9600/10，即 960。BaudRate 始终配置为位/秒。

标准波特率包括 110、300、600、1200、2400、4800、9600、14400、19200、38400、57600、115200、128000 和 256000 位/秒。

使用以下语法创建串行对象后，还可以设置 BaudRate 属性：

s.BaudRate = 4800;

示例: s.BaudRate = 4800;

要传输的数据位数，指定为 5、6、7 或 8。数据以包含五、六、七或八个位的一个系列进行传输，最低有效位先发送。传输 ASCII 字符至少需要 7 个数据位。传输二进制数据需要 8 个位。五位和六位数据格式用于专用通信设备。

除数据位外，串行数据格式还包括一个开始位、一个或两个停止位以及可能存在的一个奇偶校验位。使用 StopBits 属性指定停止位数，并使用 Parity 属性指定奇偶校验检查的类型。

使用以下语法创建串行对象后，还可以设置 DataBits 属性：

s.DataBits = 7;

示例: s.DataBits = 7;

奇偶校验检查的类型，指定为 none、odd、even、mark 或 space。

奇偶校验检查只能检测一个位的错误。两个位中的错误可能导致数据具有看似有效的奇偶校验，而实际上它不正确。

除奇偶校验位之外，串行数据格式还包括一个开始位、5 到 8 个数据位以及一个或两个停止位。使用 DataBits 属性指定数据位数，使用 StopBits 属性指定停止位数。

使用以下语法创建串行对象后，还可以设置 Parity 属性：

s.Parity = 'even';

示例: s.Parity = 'even';

用于指示字节结尾的位数，指定为 1、1.5 或 2。如果 StopBits 是 1，则使用一个停止位来指示数据传输的结束。如果 StopBits 是 2，则使用两个停止位来指示数据传输的结束。如果 StopBits 是 1.5，则传输停止位的时间是正常传输一个位所需时间的 150%。

可能值的汇总：

除停止位之外，串行数据格式还包括一个开始位、5 到 8 个数据位以及可能存在的一个奇偶校验位。使用 DataBits 属性指定数据位数，并使用 Parity 属性指定奇偶校验检查的类型。

使用以下语法创建串行对象后，还可以设置 StopBits 属性：

s.StopBits = 2;

示例: s.StopBits = 2;

终止符字符，指定为字符串或元胞数组。可以将 Terminator 配置为 0 到 127 之间的整数值，表示字符的 ASCII 代码，也可以将 Terminator 配置为 ASCII 字符。例如，要将 Terminator 配置为回车符，请将值指定为 CR 或 13。要将 Terminator 配置为换行符，请将值指定为 LF 或 10。也可以将 Terminator 设置为 CR/LF 或 LF/CR。如果 Terminator 是 CR/LF，则终止符是回车符后跟换行符。如果 Terminator 是 LF/CR，则终止符是换行符后跟回车符。请注意，这两个值没有对应的整数值。

此外，还可以将 Terminator 设置为 1×2 元胞数组。元胞的第一个元素是读取终止符，第二个元素是写入终止符。

使用 fprintf 函数执行写入操作时，出现的所有 \n 都将替换为 Terminator 属性值。请注意，%s\n 是 fprintf 的默认格式。使用 fgetl、fgets 或 fscanf 的读取操作在读取到 Terminator 值时即结束。二元运算将忽略终止符。

当 BytesAvailableFcnMode 设置为 terminator 时，您还可以使用终止符生成字节可用事件。

使用以下语法创建串行对象后，还可以设置 Terminator 属性：

s.Terminator = 'CR';

示例: s.Terminator = 'CR';

输入缓冲区中可用的字节数，指定为双精度值。此只读属性指示当前可从输入缓冲区读取的字节数。随着输入缓冲区逐渐填满，属性值会不断更新，并在发出 fopen 函数后设置为 0。

仅在异步读取数据时才能使用 BytesAvailable。这是因为同步读取数据时，仅在输入缓冲区为空后，控制权才会返回给 MATLAB^® 命令行。因此，BytesAvailable 值始终为 0。

BytesAvailable 值的范围是零到输入缓冲区的大小。使用 InputBufferSize 属性指定输入缓冲区的大小。使用 ValuesReceived 属性返回读取的值的总数。

示例: s.BytesAvailable

输入缓冲区的大小（以字节为单位），指定为双精度值。将 InputBufferSize 配置为读取操作期间输入缓冲区中可存储的总字节数。

如果存储在输入缓冲区中的数据量达到 InputBufferSize 值，则终止读取操作。您可以使用 fgetl、fget 或 fscanf 函数读取文本数据。您可以使用 fread 函数读取二进制数据。

仅当串行端口对象与设备断开连接时，才能配置 InputBufferSize。您可以在调用 fopen 函数之前对其进行配置。使用 fclose 函数来断开与对象的连接。断开连接的对象的 Status 属性值为 closed。

如果在输入缓冲区中有数据时配置 InputBufferSize，则会清除该数据。

示例: s.InputBufferSize = 768;

指定异步读取操作为连续操作还是手动操作，指定为 'manual' 或 'continuous'。如果 ReadAsyncMode 为 continuous，则串行端口对象会持续查询设备，以确定数据是否可用于读取。如果数据可用，则会自动读取数据并存储在输入缓冲区中。如果发出，则忽略 readasync 函数。

如果 ReadAsyncMode 为 manual，则对象不会查询设备以确定数据是否可用于读取。此时，您必须手动发出 readasync 函数以执行异步读取操作。由于 readasync 会检查终止符，因此函数执行速度可能较慢。要提高速度，请将 ReadAsyncMode 配置为 continuous。

要确定输入缓冲区中可用的数据量，请使用 BytesAvailable 属性。对于任一 ReadAsyncMode 值，您可以使用某个同步读取函数将数据传送到 MATLAB 工作区，例如 fscanf、fgetl、fgets 或 fread。

示例: s.ReadAsyncMode = 'manual';

完成读取或写入操作的等待时间，指定为双精度值。将 Timeout 配置为完成读取或写入操作的最长等待时间（以秒为单位）。如果未指定其他值，则使用默认值 10 秒。超时值向上舍入到完整秒。

如果发生超时，读取或写入操作即终止。此外，如果在异步读取或写入操作期间发生超时，则：

示例: s.Timeout = 30;

异步读取或写入操作的状态，指定为 idle、read、write 或 read&write。此只读属性指示是否正在进行异步读取或写入操作。如果 TransferStatus 是 idle，则当前没有进行异步读取或写入操作。如果是 read，则正在进行异步读取操作。如果是 write，则正在进行异步写入操作。如果 TransferStatus 是 read&write，则异步读取和异步写入操作都在进行中。

您可以使用 fprintf 或 fwrite 函数以异步方式写入数据。您可以使用 readasync 函数或通过将 ReadAsyncMode 属性配置为 continuous 来以异步方式读取数据。当 readasync 正在执行时，TransferStatus 可能表示即使数据未填充输入缓冲区，也正在读取数据。如果 ReadAsyncMode 是 continuous，则 TransferStatus 表示仅在数据填充输入缓冲区时才读取数据。

您可以同时执行异步读取和异步写入操作，因为串行端口具有单独的读取和写入引脚。

可能值的汇总：

示例: s.TransferStatus

从设备读取的值的总数，指定为双精度值。这是只读属性，该值在每次成功读取操作后更新，并在发出 fopen 函数后设置为 0。如果从设备读取到终止符，则此值由 ValuesReceived 反映。

如果要异步读取数据，请使用 BytesAvailable 属性返回输入缓冲区中当前可用的字节数。

执行读取操作时，接收的数据由值（而不是字节）表示。一个值由一个或多个字节组成。例如，一个 uint32 值由四个字节组成。

例如，创建一个与串行端口 COM1 关联的串行端口对象，然后打开连接。

s = serial('COM1');
fopen(s)

如果编写 RS232? 命令，并使用 fscanf 读回响应，则 ValuesReceived 为 17，因为仪器配置为发送 LF 终止符。

fprintf(s,'RS232?')
out = fscanf(s)
out =
9600;0;0;NONE;LF
s.ValuesReceived
ans =
    17

示例: s.ValuesReceived

当前在输出缓冲区中的字节数，指定为双精度值。此只读属性指示当前在输出缓冲区中等待写入设备的字节数。随着输出缓冲区逐渐填满和清空，属性值会不断更新，并在发出 fopen 函数后设置为 0。

仅在异步写入数据时才能使用 BytesToOutput。这是因为同步写入数据时，仅在输出缓冲区为空后，控制权才会返回给 MATLAB 命令行。因此，BytesToOutput 值始终为 0。

使用 ValuesSent 属性可返回写入设备的值的总数。

示例: s.BytesToOutput

输出缓冲区的大小（以字节为单位），指定为双精度值。将 OutputBufferSize 配置为写入期间输出缓冲区中可存储的总字节数。

仅当串行端口对象与设备断开连接时，才能配置 OutputBufferSize。您可以在调用 fopen 函数之前对其进行配置。使用 fclose 函数来断开与对象的连接。断开连接的对象的 Status 属性值为 closed。

如果输出缓冲区无法容纳要写入的所有数据，将出现错误。使用 fprintf 函数写入文本数据。使用 fwrite 函数写入二进制数据。

示例: s.OutputBufferSize = 256;

写入设备的值的总数，指定为双精度值。这是只读属性，该值在每次成功写入操作后更新，并在发出 fopen 函数后设置为 0。如果在写入终止符，ValuesSent 会反映此值。

如果在异步写入数据，请使用 BytesToOutput 属性返回当前输出缓冲区中的字节数。

执行写入操作时，传输的数据由值（而不是字节）表示。一个值由一个或多个字节组成。例如，一个 uint32 值由四个字节组成。

例如，创建一个与串行端口 COM1 关联的串行端口对象，然后打开连接。

s = serial('COM1');
fopen(s)

如果使用 fprintf 函数写入 *IDN? 命令，则 ValuesSent 是 6，因为默认数据格式为 %s\n，并会写入终止符。

fprintf(s,'*IDN?')
s.ValuesSent
ans =
    6

示例: s.ValuesSent

串行端口设备连接的状态，返回为 closed 或 open。此只读属性指示串行端口对象是否连接到设备。如果 Status 是 closed，则串行端口对象未连接到设备。如果 Status 是 open，则串行端口对象已连接到设备。

要写入或读取数据，必须先使用 fopen 函数将串行端口对象连接到设备。要断开串行端口对象与设备的连接，请使用 fclose 函数。

示例: s.Status

中断事件发生时运行的回调函数，指定为函数句柄。当接收的数据处于断开 (空号) 状态的时间超过一个字节的传输时间时，串行端口会产生断点中断事件。

如果 RecordStatus 属性值为 on，并且发生了断点中断事件，则记录文件会记录以下信息：

发生字节可用事件时运行的回调函数，指定为函数句柄。当由 BytesAvailableFcnCount 属性指定的字节数在输入缓冲区中可用时，或者在读取到终止符后（具体由 BytesAvailableFcnMode 属性确定），会发生字节可用事件。

如果 RecordStatus 属性值为 on，并且发生了字节可用事件，则记录文件会记录以下信息：

示例: s.BytesAvailableFcn = @instrcallback;

生成字节可用事件时输入缓冲区中必须可用的字节数，指定为数值。

BytesAvailableFcnMode 属性可用于指定字节可用事件是在可用字节达到一定数量后发生，还是在读取到终止符后发生。

字节可用事件执行为 BytesAvailableFcn 属性指定的回调函数。

仅当对象与设备断开连接时，才能配置 BytesAvailableFcnCount。使用 fclose 函数来断开与对象的连接。断开连接的对象的 Status 属性值为 closed。

示例: s.BytesAvailableFcnCount = 40;

用于生成字节可用事件的字节可用函数的类型，指定为 'terminator' 或 'byte'。如果 BytesAvailableFcnMode 是 'terminator'，则在到达 Terminator 属性指定的终止符时，会发生字节可用事件。如果 BytesAvailableFcnMode 是 'byte'，则在 BytesAvailableFcnCount 属性指定的字节数可用时，会发生字节可用事件。

字节可用事件执行为 BytesAvailableFcn 属性指定的回调函数。

仅当对象与设备断开连接时，才能配置 BytesAvailableFcnMode。使用 fclose 函数来断开与对象的连接。断开连接的对象的 Status 属性值为 closed。

示例: s.BytesAvailableFcnMode = 'byte';

发生错误事件时运行的回调函数，指定为函数句柄。

发生超时也会生成错误事件。如果读取或写入操作未在 Timeout 属性指定的时间内成功完成，则会发生超时。配置错误（如设置了无效属性值）不会生成错误事件。

如果 RecordStatus 属性值为 on，并且发生了错误事件，则记录文件会记录以下信息：

发生输出为空事件时执行的回调函数，指定为函数句柄。当最后一个字节从输出缓冲区发送到设备时，发生输出为空事件。

如果 RecordStatus 属性值为 on，并且发生了输出为空事件，则记录文件会记录以下信息：

发生引脚状态事件时运行的回调函数，指定为函数句柄。当载波检测 (CD)、允许发送 (CTS)、数据设备就绪 (DSR) 或振铃指示器 (RI) 引脚更改状态时，会发生引脚状态事件。串行端口引脚在被使能或禁能时会更改状态。关于这些引脚状态的信息记录在 PinStatus 属性中。

如果 RecordStatus 属性值为 on，并且发生了引脚状态事件，则记录文件会记录以下信息：

发生计时器事件时运行的回调函数，指定为函数句柄。在经过由 TimerPeriod 属性指定的时间后，会发生计时器事件。时间是从使用 fopen 将串行端口对象连接到设备时开始测量的。

如果 RecordStatus 属性值为 on，并且发生了计时器事件，则记录文件会记录以下信息：

如果系统速度明显变慢或者 TimerPeriod 值太小，可能不会处理某些计时器事件。

计时器事件之间的时间段，指定为数值，以秒为单位。它是在调用为 TimerFcn 指定的回调函数之前必须经过的时间。时间是从使用 fopen 将串行端口对象连接到设备时开始测量的。

如果系统速度明显变慢或者 TimerPeriod 值太小，可能不会处理某些计时器事件。

DTR 引脚的状态，指定为 on 或 off。如果 DataTerminalReady 为 on，则数据终端就绪 (DTR) 引脚处于使能状态。如果 DataTerminalReady 为 off，则 DTR 引脚处于禁能状态。

在正常使用中，DTR 和数据设备就绪 (DSR) 引脚协作工作，用于指示设备是否已连接并通电。但是，RS-232 标准中没有规定必须以任何特定方式使用 DTR 引脚。例如，DTR 和 DSR 可能用于握手。您应参阅设备文档以确定其具体引脚行为。

您可以使用 PinStatus 属性返回 DSR 引脚的值。

示例: s.DataTerminalReady = 'off';

数据流控制方法，指定为 none、hardware 或 software。如果 FlowControl 是 none，则不使用数据流控制（握手）。如果 FlowControl 是 hardware，则使用硬件握手来控制数据流。如果 FlowControl 是 software，则使用软件握手来控制数据流。

硬件握手通常利用请求发送 (RTS) 和允许发送 (CTS) 引脚来控制数据流。软件握手使用控制字符（Xon 和 Xoff）来控制数据流。

您可以使用 PinStatus 属性返回 CTS 引脚的值。您可以使用 RequestToSend 属性指定 RTS 引脚的值。但是，如果 FlowControl 是 hardware，并且您为 RequestToSend 指定值，则可能不支持该值。

示例: s.FlowControl = 'hardware';

CD、CTS、DSR 和 RI 引脚的状态，以结构体形式返回。此只读属性返回一个结构体数组，其中包含字段 CarrierDetect、ClearToSend、DataSetReady 和 RingIndicator。这些字段分别指示载波检测 (CD)、允许发送 (CTS)、数据设备就绪 (DSR) 和振铃指示器 (RI) 引脚的状态。

对于任何这些字段，PinStatus 可以是 on 或 off。值为 on 表示关联的引脚处于使能状态。值为 off 表示关联的引脚处于禁能状态。当其中任一引脚更改其状态时，就会发生引脚状态事件。引脚状态事件执行 PinStatusFcn 指定的回调函数。

在正常使用中，数据终端就绪 (DTR) 和 DSR 引脚协作工作，而请求发送 (RTS) 和 CTS 引脚协作工作。您可以使用 DataTerminalReady 属性指定 DTR 引脚的状态。您可以使用 RequestToSend 属性指定 RTS 引脚的状态。

示例: s.PinStatus

RTS 引脚的状态，指定为 on 或 off。如果 RequestToSend 为 on，则请求发送 (RTS) 引脚处于使能状态。如果 RequestToSend 为 off，则 RTS 引脚处于禁能状态。

在正常使用中，RTS 和允许发送 (CTS) 引脚协作工作，并用作数据传输的标准握手引脚。在这种情况下，RTS 和 CTS 由 DTE 和 DCE 自动管理。但是，RS-232 标准中没有要求必须以任何特定方式使用 RTS 引脚。因此，如果手动配置 RequestToSend 值，则可能是非标准操作。

如果您的设备未以标准方式使用硬件握手，并且您需要手动配置 RequestToSend，请将 FlowControl 属性配置为 none。否则，可能不支持您指定的 RequestToSend 值。请参阅您的设备文档以确定其具体引脚行为。

您可以使用 PinStatus 属性返回 CTS 引脚的值。

示例: s.RequestToSend = 'off';

保存到记录文件的信息的详细级别，指定为 compact 或 verbose。如果 RecordDetail 是 compact，则写入设备的值的数量、从设备读取的值的数量、值的数据类型和事件信息都保存到记录文件中。如果 RecordDetail 是 verbose，则写入设备的数据和从设备读取的数据也会保存到记录文件中。

可能值的汇总：

示例: s.RecordDetail = 'verbose';

在记录文件中保存数据和事件信息的方法，指定为 overwrite、append 或 index。如果 RecordMode 是 overwrite，则每次启动记录时都会覆盖记录文件。如果 RecordMode 是 append，则每次启动记录时都会将数据追加到记录文件中。如果 RecordMode 是 index，则每次启动记录时都会创建一个不同记录文件，每个记录文件都具有索引文件名。

仅当对象未在记录时才能配置 RecordMode。使用 record 函数终止记录。未记录的对象的 RecordStatus 属性值为 off。

使用 RecordName 属性指定记录文件名。索引文件名遵循一组规定的规则。

可能值的汇总：

例如，使用记录属性记录串行数据。创建串行端口对象并打开连接。

s = serial('COM1');
fopen(s)

使用 RecordName 属性指定记录文件名，将 RecordMode 配置为 index，然后启动记录。

s.RecordName = 'MyRecord.txt';
s.RecordMode = 'index';
record(s)

在关闭记录后，记录文件名将使用索引文件名自动更新。

record(s,'off')
s.RecordName
ans =
MyRecord01.txt

断开 s 与外围设备的连接，从内存中删除 s，然后从 MATLAB 工作区中删除 s。

fclose(s)
delete(s)
clear s

示例: s.RecordMode = 'index';

记录文件的名称，指定为字符串。您可以为 RecordName 指定任何值 - 包括目录路径 - 前提是操作系统支持文件名。

默认记录文件名为 record.txt，如果您记录数据文件但未指定其他名称，则使用该文件名。

MATLAB 支持操作系统支持的任何文件名。您可以使用 type 函数访问该文件。例如，如果将记录文件命名为 MyRecord.txt，要在 MATLAB 命令行中键入此文件，请输入：

type('MyRecord.txt')

您可以使用 RecordMode 属性指定数据和事件信息是保存到一个磁盘文件还是多个磁盘文件。如果 RecordMode 是 index，则文件名遵循一组规定的规则。

仅当对象未在记录时才能配置 RecordName。使用 record 函数终止记录。未记录的对象的 RecordStatus 属性值为 off。

示例: s.RecordName = 'MonthlyDataFile_April';

记录串行数据和事件信息的状态，返回为 on 或 off。此只读属性指示记录是打开还是关闭，由 record 函数控制。如果 RecordStatus 是 off，则数据和事件信息不会保存到记录文件中。如果 RecordStatus 是 on，则数据和事件信息将保存到 RecordName 指定的记录文件中。

使用 record 函数启动或完成记录。RecordStatus 自动配置为反映记录状态。

示例: s.RecordStatus