类QSerialPort#

提供访问串行端口的函数。 更多信息…

Inheritance diagram of 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线程中使用，以避免冻结用户界面。

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

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

另请参阅

QSerialPortInfo

class Direction#

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

注意

在某些操作系统（例如 POSIX-like）上，该枚举用于分别设置每个方向的波特率。

常量

描述

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

发生了未识别的错误。

另请参阅

错误

注意

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

属性 baudRate: int#

此属性持有所需方向的波特率数据。

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

注意

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

警告

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

警告

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

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

访问函数
属性 breakEnabled: bool#

此属性持有传输线路在break状态的状态。

成功时返回true，否则返回false。如果标志为true，则传输线路处于break状态；否则是non-break状态。

注意

在尝试设置或获取该属性之前，必须先打开串行端口；否则返回 false 并设置错误代码 NotOpenError。这与类的一般Qt属性设置方法有点不同。然而，这是因为属性是通过与内核和硬件的交互进行设置的，因此这是一个特殊的用例。因此，这两种场景不能完全相互比较。

访问函数
属性dataBitsᅟ: QSerialPort.DataBits#

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

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

注意

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

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

访问函数
属性dataTerminalReadyᅟ: bool#

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

在成功时返回 true，在失败时返回 false。如果标志为 true，则DTR信号将被设置为高；否则为低。

注意

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

另请参阅

pinoutSignals()

访问函数
属性errorᅟ: QSerialPort.SerialPortError#

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

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

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

访问函数
属性 flowControlᅟ: QSerialPort.FlowControl#

此属性包含所需的流量控制模式。

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

注意

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

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

访问函数
属性 parityᅟ: QSerialPort.Parity#

此属性包含奇偶校验检查模式。

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

注意

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

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

访问函数
属性 requestToSendᅟ: bool#

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

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

注意

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

注意

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

另请参阅

pinoutSignals()

访问函数
属性 stopBits: QSerialPort.StopBits#

这个属性存储了帧中的停止位数量。

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

注意

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

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

访问函数
__init__(info[, parent=None])#
参数:

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

__init__([parent=None])
参数:

parent – QObject

构造一个新的串行端口对象，带有指定的 parent。

__init__(name[, parent=None])
参数:

构造一个新的串行端口对象，带有指定的 parent，以表示具有指定 name 的串行端口。

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

baudRate([directions=QSerialPort.Direction.AllDirections])#
参数:

directions – Direction 的组合

返回类型:

int

另请参阅

setBaudRate()

baudRateChanged(baudRate, directions)#
参数:

  • baudRate – int

  • directions – Direction 的组合

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

另请参阅

baudRate

属性 baudRateᅟ 的通知信号。

breakEnabledChanged(set)#
参数:

set – bool

属性 breakEnabled 的通知信号。

clear([directions=QSerialPort.Direction.AllDirections])#
参数:

directions – Direction 的组合

返回类型:

bool

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

注意

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

clearError()#

属性 error 的重置函数。

dataBits()#
返回类型:

数据位

另请参阅

setDataBits()

属性 dataBits 的获取器。

dataBitsChanged(dataBits)#
参数:

dataBits – DataBits

在帧中的数据位改变后发出此信号。新的帧中的数据位作为 dataBits 传递。

另请参阅

dataBits

属性 dataBits 的通知信号。

dataTerminalReadyChanged(set)#
参数:

set – bool

直线信号 DTR 的状态（高或低）改变后发出此信号。新的直线信号 DTR 的状态（高或低）作为 set 传递。

另请参阅

dataTerminalReady

属性 dataTerminalReady 的通知信号。

error()#
返回类型:

串行端口错误

属性 errorᅟ 的getter。

errorOccurred(error)#
参数:

error – SerialPortError

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

另请参阅

错误

属性 errorᅟ 的通知信号。

flowControl()#
返回类型:

流控制

另请参阅

setFlowControl()

属性 flowControlᅟ 的getter。

flowControlChanged(flowControl)#
参数:

flowControl – FlowControl

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

另请参阅

flowControl

属性 flowControlᅟ 的通知信号。

flush()#
返回类型:

bool

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

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

注意

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

另请参阅

waitForBytesWritten()

handle()#
返回类型:

int

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

警告

此函数仅适用于专家使用；使用时请自行承担风险。此外，此函数在Qt的小版本发布之间不保证兼容性。

isBreakEnabled()#
返回类型:

bool

属性 breakEnabled 的获取器。

isDataTerminalReady()#
返回类型:

bool

属性 dataTerminalReady 的获取器。

isRequestToSend()#
返回类型:

bool

属性 requestToSend 的获取器。

parity()#
返回类型:

奇偶性

另请参阅

setParity()

属性 parity 的获取器。

parityChanged(parity)#
参数:

parity – Parity

当奇偶校验模式被更改后，会发出此信号。新的奇偶校验模式以 parity 的形式传递。

另请参阅

parity

属性 parity 的通知信号。

pinoutSignals()#
返回类型:

PinoutSignal 的组合

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

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

注意

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

注意

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

另请参阅

dataTerminalReady requestToSend

portName()#
返回类型:

字符串

返回通过 setPort() 设置的名称或传递给 QSerialPort 构造函数的名称。该名称较短，即从设备的内部变量系统位置提取并转换的。转换算法与平台相关。

平台

简述

Windows

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

Unix, BSD

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

另请参阅

setPortName() setPort() portName()

readBufferSize()#
返回类型:

int

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

读取缓冲区大小为 0（默认值）表示缓冲区没有大小限制，确保不丢失数据。

requestToSendChanged(set)#
参数:

set – bool

在行信号 RTS 状态（高或低）改变后发出此信号。新的行信号 RTS 状态（高或低）作为 set 传递。

另请参阅

requestToSend

requestToSend 属性的通告信号。

setBaudRate(baudRate[, directions=QSerialPort.Direction.AllDirections])#
参数:

  • baudRate – int

  • directions – Direction 的组合

返回类型:

bool

另请参阅

baudRate()

setBreakEnabled([set=true])#
参数:

set – bool

返回类型:

bool

另请参阅

isBreakEnabled()

setDataBits(dataBits)#
参数:

dataBits – DataBits

返回类型:

bool

另请参阅

dataBits()

setDataTerminalReady(set)#
参数:

set – bool

返回类型:

bool

另请参阅

isDataTerminalReady()

setFlowControl(flowControl)#
参数:

flowControl – FlowControl

返回类型:

bool

另请参阅

flowControl()

setParity(parity)#
参数:

parity – Parity

返回类型:

bool

另请参阅

parity()

setPort(info)#
参数:

info – QSerialPortInfo

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

setPortName(name)#
参数:

name – str

设置串行端口的 name。

串行端口的名称可以作为短名称或在必要时传递长系统位置。

setReadBufferSize(size)#
参数:

size - int

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

如果缓冲区大小限制为特定大小，则 QSerialPort 不会缓冲超过此大小的数据。特殊情况下，缓冲区大小为 0 表示读取缓冲区是无限制的，并缓冲所有传入的数据。这是默认设置。

如果数据仅在特定时间点读取（例如在实时流应用程序中）或如果需要保护串行端口免受接收过多数据的侵害，这最终可能导致应用程序耗尽内存，则此选项非常有用。

另请参阅

readBufferSize() read()

setRequestToSend(set)#
参数:

set – bool

返回类型:

bool

另请参阅

isRequestToSend()

setStopBits(stopBits)#
参数:

stopBits - StopBits

返回类型:

bool

另请参阅

stopBits()

stopBits()#
返回类型:

StopBits

另请参阅

setStopBits()

stopBits 的获取器。

stopBitsChanged(stopBits)#
参数:

stopBits - StopBits

在更改帧中停止位数量后，会发出此信号。帧中新的停止位数量作为 stopBits 传递。

另请参阅

stopBits

stopBitsᅟ 属性的通知信号。