PySide6.QtSerialPort.QSerialPort

class QSerialPort

提供访问串行端口的功能。更多…

PySide6.QtSerialPort.QSerialPort 的继承图

概要

属性

方法

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

您可以使用QSerialPortInfo辅助类获取有关可用串行端口的信息，该类允许枚举系统中的所有串行端口。这对于获取您想要使用的串行端口的正确名称非常有用。您可以将辅助类的对象作为参数传递给setPort()或setPortName()方法，以分配所需的串行设备。

设置端口后，您可以使用open()方法以只读（r/o）、只写（w/o）或读写（r/w）模式打开它。

注意

串行端口始终以独占访问方式打开（即，没有其他进程或线程可以访问已经打开的串行端口）。

使用close()方法来关闭端口并取消I/O操作。

成功打开后，QSerialPort 尝试确定端口的当前配置并初始化自身。您可以使用 setBaudRate()、setDataBits()、setParity()、setStopBits() 和 setFlowControl() 方法将端口重新配置为所需的设置。

有几个属性用于处理引脚信号，分别是：dataTerminalReady，requestToSend。也可以使用pinoutSignals()方法来查询当前的引脚信号设置。

一旦你知道端口已经准备好读取或写入，你可以使用read()或write()方法。另外，也可以调用readLine()和readAll()这些便捷方法。如果没有一次性读取所有数据，剩余的数据将在新的传入数据附加到QSerialPort的内部读取缓冲区时可供以后使用。你可以使用setReadBufferSize()来限制读取缓冲区的大小。

QSerialPort 提供了一组函数，这些函数会挂起调用线程，直到发出某些信号。这些函数可用于实现阻塞式串行端口：

  • waitForReadyRead() 阻塞调用，直到有新数据可供读取。

  • waitForBytesWritten() 阻塞调用，直到一个数据负载被写入串行端口。

请参见以下示例：

int numRead = 0, numReadTotal = 0;
char buffer[50];

for (;;) {
    numRead  = serial.read(buffer, 50);

    // Do whatever with the array

    numReadTotal += numRead;
    if (numRead == 0 && !serial.waitForReadyRead())
        break;
}

如果 waitForReadyRead() 返回 false，则表示连接已关闭或发生了错误。

如果在任何时候发生错误，QSerialPort 将发出 errorOccurred() 信号。你也可以调用 error() 来查找上次发生的错误类型。

使用阻塞串行端口编程与使用非阻塞串行端口编程有根本的不同。阻塞串行端口不需要事件循环，通常会导致更简单的代码。然而，在GUI应用程序中，阻塞串行端口应仅在非GUI线程中使用，以避免冻结用户界面。

有关这些方法的更多详细信息，请参阅example应用程序。

QSerialPort 类也可以与 QTextStream 和 QDataStream 的流操作符（operator<<() 和 operator>>()）一起使用。但需要注意一个问题：在使用 operator>>() 重载操作符尝试读取之前，确保有足够的数据可用。

另请参阅

QSerialPortInfo

class Direction

(继承自 enum.Flag) 此枚举描述了数据传输的可能方向。

注意

此枚举用于在某些操作系统（例如，类POSIX）上为每个方向单独设置设备的波特率。

常量

描述

QSerialPort.Input

输入方向。

QSerialPort.Output

输出方向。

QSerialPort.AllDirections

同时在两个方向。
class BaudRate

(继承自 enum.IntEnum) 此枚举描述了通信设备运行的波特率。

注意

此枚举中仅列出了最常见的标准波特率。

常量

描述

QSerialPort.Baud1200

1200 波特。

QSerialPort.Baud2400

2400 波特率。

QSerialPort.Baud4800

4800 波特率。

QSerialPort.Baud9600

9600 波特率。

QSerialPort.Baud19200

19200 波特率。

QSerialPort.Baud38400

38400 波特率。

QSerialPort.Baud57600

57600 波特率。

QSerialPort.Baud115200

115200 波特率。

另请参阅

baudRate

class DataBits

此枚举描述了使用的数据位数。

常量

描述

QSerialPort.Data5

每个字符的数据位数为5。它用于Baudot代码。通常仅适用于较旧的设备，如电传打字机。

QSerialPort.Data6

每个字符的数据位数为6。很少使用。

QSerialPort.Data7

每个字符的数据位数为7。它用于真正的ASCII。通常仅适用于较旧的设备，如电传打字机。

QSerialPort.Data8

每个字符的数据位数为8。它用于大多数类型的数据，因为这个大小与字节的大小相匹配。它几乎在新应用程序中普遍使用。

另请参阅

dataBits

class Parity

此枚举描述了使用的奇偶校验方案。

常量

描述

QSerialPort.NoParity

不发送奇偶校验位。这是最常见的奇偶校验设置。错误检测由通信协议处理。

QSerialPort.EvenParity

每个字符中的1的位数，包括奇偶校验位，始终为偶数。

QSerialPort.OddParity

每个字符中的1位数，包括奇偶校验位，始终为奇数。它确保每个字符中至少发生一次状态转换。

QSerialPort.SpaceParity

空格校验。校验位在空格信号条件下发送。它不提供错误检测信息。

QSerialPort.MarkParity

标记奇偶校验。奇偶校验位始终设置为标记信号条件（逻辑1）。它不提供错误检测信息。

另请参阅

parity

class StopBits

此枚举描述了使用的停止位数。

常量

描述

QSerialPort.OneStop

1 个停止位。

QSerialPort.OneAndHalfStop

1.5 停止位。这仅适用于 Windows 平台。

QSerialPort.TwoStop

2个停止位。

另请参阅

stopBits

class FlowControl

此枚举描述了使用的流控制。

常量

描述

QSerialPort.NoFlowControl

无流控制。

QSerialPort.HardwareControl

硬件流控制 (RTS/CTS)。

QSerialPort.SoftwareControl

软件流控制 (XON/XOFF)。

另请参阅

flowControl

class PinoutSignal

(继承自 enum.Flag) 此枚举描述了可能的RS-232引脚信号。

常量

描述

QSerialPort.NoSignal

没有活动线路

QSerialPort.DataTerminalReadySignal

DTR（数据终端就绪）。

QSerialPort.DataCarrierDetectSignal

DCD（数据载波检测）。

QSerialPort.DataSetReadySignal

DSR（数据集就绪）。

QSerialPort.RingIndicatorSignal

RNG（振铃指示器）。

QSerialPort.RequestToSendSignal

RTS（请求发送）。

QSerialPort.ClearToSendSignal

CTS（清除发送）。

QSerialPort.SecondaryTransmittedDataSignal

STD（次要传输数据）。

QSerialPort.SecondaryReceivedDataSignal

SRD（次级接收数据）。

另请参阅

pinoutSignals() dataTerminalReady requestToSend

class SerialPortError

此枚举描述了可能包含在error属性中的错误。

常量

描述

QSerialPort.NoError

没有发生错误。

QSerialPort.DeviceNotFoundError

尝试打开不存在的设备时发生错误。

QSerialPort.PermissionError

尝试打开已被另一个进程打开的设备或用户没有足够的权限和凭据打开时发生错误。

QSerialPort.OpenError

尝试在此对象中打开已打开的设备时发生错误。

QSerialPort.NotOpenError

当执行只能在设备打开时成功执行的操作时，会发生此错误。此值在QtSerialPort 5.2中引入。

QSerialPort.WriteError

在写入数据时发生了I/O错误。

QSerialPort.ReadError

读取数据时发生了I/O错误。

QSerialPort.ResourceError

当资源变得不可用时发生I/O错误，例如当设备意外从系统中移除时。

QSerialPort.UnsupportedOperationError

请求的设备操作不被运行的操作系统支持或禁止。

QSerialPort.TimeoutError

发生了超时错误。此值在QtSerialPort 5.2中引入。

QSerialPort.UnknownError

发生了一个未识别的错误。

另请参阅

error

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property baudRateᅟ: int

此属性保存所需方向的数据波特率。

如果设置成功或在打开端口之前已设置，则返回true；否则返回false并设置一个错误代码，可以通过访问error属性的值来获取。要设置波特率，请使用枚举BaudRate或任何正qint32值。

注意

如果在打开端口之前设置了设置，实际的串口设置会在端口成功打开后自动在open()方法中完成。

警告

在所有平台上都支持设置AllDirections标志。Windows仅支持此模式。

警告

在Windows上返回任何方向上的相等波特率。

默认值为Baud9600，即每秒9600位。

Access functions:
property breakEnabledᅟ: bool

此属性保存传输线在中断时的状态。

成功时返回true，否则返回false。如果标志为true，则传输线处于断开状态；否则处于非断开状态。

注意

在尝试设置或获取此属性之前，必须打开串口；否则返回false并设置NotOpenError错误代码。这与类的常规Qt属性设置相比有些不同。然而，这是一个特殊的使用情况，因为属性是通过与内核和硬件的交互来设置的。因此，这两种情况不能完全相互比较。

Access functions:
property dataBitsᅟ: QSerialPort.DataBits

此属性保存帧中的数据位。

如果设置成功或在打开端口之前已设置，则返回 true；否则返回 false 并设置一个错误代码，可以通过访问 error 属性的值来获取。

注意

如果在打开端口之前设置了设置，实际的串口设置会在端口成功打开后自动在open()方法中完成。

默认值为Data8，即8个数据位。

Access functions:
property dataTerminalReadyᅟ: bool

此属性保存线路信号DTR的状态（高或低）。

成功时返回true，否则返回false。如果标志为true，则DTR信号设置为高电平；否则为低电平。

注意

在尝试设置或获取此属性之前，必须打开串口；否则将返回false，并将错误代码设置为NotOpenError。

另请参阅

pinoutSignals()

Access functions:
property errorᅟ: QSerialPort.SerialPortError

此属性保存串行端口的错误状态。

I/O设备状态返回一个错误代码。例如，如果open()返回false，或者读/写操作返回-1，可以使用此属性来找出操作失败的原因。

错误代码在调用clearError()后被设置为默认的NoError

Access functions:
property flowControlᅟ: QSerialPort.FlowControl

此属性保存所需的流控制模式。

如果设置成功或在打开端口之前已设置，则返回 true；否则返回 false 并设置一个错误代码，可以通过访问 error 属性的值来获取。

注意

如果在打开端口之前设置了设置，实际的串口设置会在端口成功打开后自动在open()方法中完成。

默认值为 NoFlowControl，即无流量控制。

Access functions:
property parityᅟ: QSerialPort.Parity

此属性保存奇偶校验模式。

如果设置成功或在打开端口之前已设置，则返回 true；否则返回 false 并设置一个错误代码，可以通过访问 error 属性的值来获取。

注意

如果在打开端口之前设置了设置，实际的串口设置会在端口成功打开后自动在open()方法中完成。

默认值为NoParity，即无奇偶校验。

Access functions:
property requestToSendᅟ: bool

此属性保存线路信号RTS的状态（高或低）。

成功时返回 true，否则返回 false。如果标志为 true，则 RTS 信号设置为高电平；否则为低电平。

注意

在尝试设置或获取此属性之前，必须打开串口；否则将返回false，并将错误代码设置为NotOpenError。

注意

尝试在HardwareControl模式下控制RTS信号将会失败，错误代码设置为UnsupportedOperationError，因为该信号由驱动程序自动控制。

另请参阅

pinoutSignals()

Access functions:
property stopBitsᅟ: QSerialPort.StopBits

此属性保存帧中的停止位数。

如果设置成功或在打开端口之前已设置，则返回 true；否则返回 false 并设置一个错误代码，可以通过访问 error 属性的值来获取。

注意

如果在打开端口之前设置了设置，实际的串口设置会在端口成功打开后自动在open()方法中完成。

默认值为OneStop，即1个停止位。

Access functions:
__init__([parent=None])
Parameters:

父对象 – QObject

使用给定的parent构造一个新的串口对象。

__init__(info[, parent=None])
Parameters:

使用给定的parent构造一个新的串口对象，以表示具有指定辅助类serialPortInfo的串口。

__init__(name[, parent=None])
Parameters:

使用给定的parent构造一个新的串口对象，以表示具有指定name的串口。

名称应具有特定格式；请参阅setPort()方法。

baudRate([directions=QSerialPort.Direction.AllDirections])
Parameters:

方向 – Direction 的组合

Return type:

整数

另请参阅

setBaudRate()

baudRateChanged(baudRate, directions)
Parameters:

  • baudRate – int

  • directions – Direction 的组合

此信号在波特率更改后发出。新的波特率作为 baudRate 传递，方向作为 directions 传递。

另请参阅

baudRate

属性 baudRateᅟ 的通知信号。

breakEnabledChanged(set)
Parameters:

set – 布尔值

属性 breakEnabledᅟ 的通知信号。

clear([directions=QSerialPort.Direction.AllDirections])
Parameters:

方向 – Direction 的组合

Return type:

布尔

根据给定的方向 directions，丢弃输出或输入缓冲区中的所有字符。这包括清除内部类缓冲区和UART（驱动程序）缓冲区。同时终止挂起的读取或写入操作。如果成功，返回 true；否则返回 false。

注意

在尝试清除任何缓冲数据之前，必须打开串口；否则返回false并设置NotOpenError错误代码。

clearError()

属性errorᅟ的重置功能。

dataBits()
Return type:

DataBits

另请参阅

setDataBits()

属性 dataBitsᅟ 的获取器。

dataBitsChanged(dataBits)
Parameters:

dataBits – DataBits

当帧中的数据位发生变化后，会发出此信号。帧中的新数据位作为 dataBits 传递。

另请参阅

dataBits

属性 dataBitsᅟ 的通知信号。

dataTerminalReadyChanged(set)
Parameters:

set – 布尔值

当线路信号DTR的状态（高或低）发生变化后，会发出此信号。线路信号DTR的新状态（高或低）作为set传递。

另请参阅

dataTerminalReady

属性 dataTerminalReadyᅟ 的通知信号。

error()
Return type:

SerialPortError

属性 errorᅟ 的获取器。

errorOccurred(error)
Parameters:

错误 – SerialPortError

当串口发生错误时，会发出此信号。指定的 error 描述了发生的错误类型。

另请参阅

error

属性 errorᅟ 的通知信号。

flowControl()
Return type:

FlowControl

另请参阅

setFlowControl()

属性 flowControlᅟ 的获取器。

flowControlChanged(flowControl)
Parameters:

flowControl – FlowControl

当流控制模式改变后，会发出此信号。新的流控制模式作为 flow 传递。

另请参阅

flowControl

属性 flowControlᅟ 的通知信号。

flush()
Return type:

布尔

此函数尽可能多地从内部写入缓冲区写入底层串行端口而不阻塞。如果写入了任何数据，此函数返回true；否则返回false。

调用此函数以立即将缓冲的数据发送到串行端口。成功写入的字节数取决于操作系统。在大多数情况下，不需要调用此函数，因为一旦控制返回到事件循环，QSerialPort类将自动开始发送数据。在没有事件循环的情况下，请调用waitForBytesWritten()代替。

注意

在尝试刷新任何缓冲数据之前，必须打开串行端口；否则返回false并设置NotOpenError错误代码。

另请参阅

waitForBytesWritten()

handle()
Return type:

整数

如果平台受支持且串口已打开，则返回本机串口句柄；否则返回-1。

警告

此功能仅供专家使用；使用时需自担风险。此外，此功能在Qt次要版本之间不保证兼容性。

isBreakEnabled()
Return type:

布尔

属性 breakEnabledᅟ 的获取器。

isDataTerminalReady()
Return type:

布尔

属性 dataTerminalReadyᅟ 的获取器。

isRequestToSend()
Return type:

布尔

获取属性 requestToSendᅟ 的Getter。

parity()
Return type:

Parity

另请参阅

setParity()

属性 parityᅟ 的获取器。

parityChanged(parity)
Parameters:

parity – Parity

此信号在奇偶校验模式更改后发出。新的奇偶校验模式作为 parity 传递。

另请参阅

parity

属性 parityᅟ 的通知信号。

pinoutSignals()
Return type:

PinoutSignal的组合

以位图格式返回线路信号的状态。

从这个结果中，可以通过应用掩码“AND”来分配所需信号的状态，其中掩码是来自PinoutSignals的所需枚举值。

注意

此方法执行系统调用，从而确保线路信号状态正确返回。当底层操作系统无法提供关于变化的适当通知时，这是必要的。

注意

在尝试获取引脚信号之前，必须打开串行端口；否则返回NoSignal并设置NotOpenError错误代码。

另请参阅

dataTerminalReady requestToSend

portName()
Return type:

字符串

返回由setPort()设置的名称或传递给QSerialPort构造函数的名称。此名称是简短的，即它是从设备的内部变量系统位置中提取并转换而来的。转换算法是平台特定的：

平台

简要描述

Windows

从系统位置中移除前缀“\\.\”或“//./”并返回字符串的其余部分。

Unix, BSD

从系统位置中移除前缀“/dev/”并返回字符串的其余部分。

另请参阅

setPortName() setPort() portName()

readBufferSize()
Return type:

整数

返回内部读取缓冲区的大小。这限制了客户端在调用read()或readAll()方法之前可以接收的数据量。

读取缓冲区大小为 0（默认值）意味着缓冲区没有大小限制，确保不会丢失任何数据。

requestToSendChanged(set)
Parameters:

set – 布尔值

当线路信号RTS的状态（高或低）发生变化后，会发出此信号。新的线路信号RTS的状态（高或低）作为set传递。

另请参阅

requestToSend

属性 requestToSendᅟ 的通知信号。

setBaudRate(baudRate[, directions=QSerialPort.Direction.AllDirections])
Parameters:

  • baudRate – int

  • directions – Direction 的组合

Return type:

布尔

另请参阅

baudRate()

setBreakEnabled([set=true])
Parameters:

set – 布尔值

Return type:

布尔

另请参阅

isBreakEnabled()

setDataBits(dataBits)
Parameters:

dataBits – DataBits

Return type:

布尔

另请参阅

dataBits()

setDataTerminalReady(set)
Parameters:

set – 布尔值

Return type:

布尔

另请参阅

isDataTerminalReady()

setFlowControl(flowControl)
Parameters:

flowControl – FlowControl

Return type:

布尔

另请参阅

flowControl()

setParity(parity)
Parameters:

parity – Parity

Return type:

布尔

另请参阅

parity()

setPort(info)
Parameters:

信息 – QSerialPortInfo

设置存储在串口信息实例 serialPortInfo 中的端口。

setPortName(name)
Parameters:

name – str

设置串口的name。

串口的名称可以作为短名称或长系统位置传递，如果需要的话。

setReadBufferSize(size)
Parameters:

size – int

将QSerialPort的内部读取缓冲区大小设置为size字节。

如果缓冲区大小限制为特定大小，QSerialPort将不会缓冲超过此大小的数据。缓冲区大小为0的特殊情况意味着读取缓冲区是无限的，所有传入的数据都会被缓冲。这是默认设置。

如果数据仅在特定时间点读取（例如在实时流应用程序中），或者如果应保护串行端口免受接收过多数据的影响，这可能会导致应用程序内存不足，则此选项非常有用。

另请参阅

readBufferSize() read()

setRequestToSend(set)
Parameters:

set – 布尔值

Return type:

布尔

另请参阅

isRequestToSend()

setStopBits(stopBits)
Parameters:

stopBits – StopBits

Return type:

布尔

另请参阅

stopBits()

stopBits()
Return type:

StopBits

另请参阅

setStopBits()

属性 stopBitsᅟ 的获取器。

stopBitsChanged(stopBits)
Parameters:

stopBits – StopBits

当帧中的停止位数发生变化后，会发出此信号。帧中的新停止位数作为stopBits传递。

另请参阅

stopBits

属性 stopBitsᅟ 的通知信号。