基于Python的Qt开发之Pyside6 QtSerialPort库的使用

一、简介

QtSerialPort 是 PySide6 用于实现串口异步通信的核心模块，专门用于与串口设备（如单片机、传感器、蓝牙模块、串口打印机等）进行数据交互。

二、QtSerialPort库的核心内容

QtSerialPort 库的核心功能由两个关键类提供，核心操作类QSerialPort和辅助信息类QSerialPortInfo， 所有串口操作均围绕这两个类展开：

1、核心操作类：QSerialPort

QSerialPort是实现串口通信的核心类，负责串口的配置、打开 / 关闭、数据读写、错误处理等核心操作，它的核心特性包括：

• 支持串口参数配置（波特率、数据位、校验位、停止位、流控）
• 提供异步读写接口（基于信号与槽，无阻塞）
• 支持串口状态检测和错误反馈
• 支持数据缓冲区操作

QSerialPort 常用属性（串口参数）

串口通信的参数必须与外设保持一致，否则无法正常通信，常用参数如下：

QSerialPort 常用信号

由于 PySide6 采用信号与槽机制，QSerialPort 的异步操作通过以下核心信号通知上层逻辑：

• readyRead()：当串口接收缓冲区有新数据到达时触发（读取数据的核心信号）
• errorOccurred(error)：当串口发生错误时触发（如端口不存在、权限不足）
• bytesWritten(bytes)：当数据成功写入串口发送缓冲区时触发

QSerialPort 常用方法

• setPortName(portName)：设置串口名（如 "COM3"（Windows）、"/dev/ttyUSB0"（Linux））
• open(openMode)：打开串口，打开模式常用 QSerialPort.ReadWrite（读写模式）
• close()：关闭串口，释放串口资源
• write(data)：向串口写入数据（需传入字节类型 bytes，而非字符串）
• readAll()：读取接收缓冲区中的所有可用数据（返回 QByteArray，可转换为 Python 字节 / 字符串）
• read(maxSize)：读取指定长度的字节数据
• isOpen()：判断串口是否已成功打开
• clear()：清空接收 / 发送缓冲区

2. 辅助信息类：QSerialPortInfo

QSerialPortInfo 是辅助类，用于枚举系统中可用的串口设备，获取串口的详细信息，无需打开串口即可使用，核心作用是帮助用户选择有效的串口。

QSerialPortInfo 常用方法

• availablePorts()：静态方法，返回系统中所有可用串口的 QSerialPortInfo 列表
• portName()：获取串口名（如 "COM3"、"/dev/ttyUSB0"）
• description()：获取串口设备描述（如 "USB-SERIAL CH340"）
• manufacturer()：获取串口设备制造商信息
• isValid()：判断当前 QSerialPortInfo 对应的串口是否有效

三、QtSerialPort 基本使用流程

使用 QtSerialPort 实现串口通信的核心流程分为 5 步，全程基于信号与槽实现异步无阻塞操作：

1. 导入核心类
2. 枚举可用串口（可选，方便用户选择）
3. 配置串口参数并打开串口
4. 绑定信号与槽（处理数据接收、错误反馈）
5. 发送数据 / 关闭串口

四、完整可运行示例

下面实现一个简单的串口通信工具，支持枚举串口、打开 / 关闭串口、发送数据、接收数据并显示，可直接运行测试（需安装 PySide6 和对应串口驱动）。

from PySide6.QtWidgets import ( QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QPushButton, QComboBox, QLineEdit, QTextEdit ) from PySide6.QtCore import Qt from PySide6.QtSerialPort import QSerialPort, QSerialPortInfo import sys class SerialPortTool(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle("QtSerialPort 串口通信示例") self.setFixedSize(600, 400) # 1. 初始化串口对象（核心） self.serial_port = QSerialPort() # 2. 构建界面 self._init_ui() # 3. 绑定信号与槽 self._bind_signals() # 4. 初始化时枚举可用串口 self.refresh_serial_ports() def _init_ui(self): """构建界面""" central_widget = QWidget() self.setCentralWidget(central_widget) main_layout = QVBoxLayout(central_widget) # 串口选择区域 port_layout = QHBoxLayout() self.port_combo = QComboBox() self.refresh_btn = QPushButton("刷新串口") self.open_btn = QPushButton("打开串口") self.close_btn = QPushButton("关闭串口") self.close_btn.setEnabled(False) port_layout.addWidget(self.port_combo) port_layout.addWidget(self.refresh_btn) port_layout.addWidget(self.open_btn) port_layout.addWidget(self.close_btn) # 数据发送区域 send_layout = QHBoxLayout() self.send_input = QLineEdit() self.send_input.setPlaceholderText("输入要发送的数据，按回车或点击发送按钮") self.send_btn = QPushButton("发送数据") send_layout.addWidget(self.send_input) send_layout.addWidget(self.send_btn) # 数据接收区域 self.recv_text = QTextEdit() self.recv_text.setPlaceholderText("接收的数据将显示在这里...") self.recv_text.setReadOnly(True) # 添加到主布局 main_layout.addLayout(port_layout) main_layout.addLayout(send_layout) main_layout.addWidget(self.recv_text) def _bind_signals(self): """绑定信号与槽""" # 界面按钮信号 self.refresh_btn.clicked.connect(self.refresh_serial_ports) self.open_btn.clicked.connect(self.open_serial_port) self.close_btn.clicked.connect(self.close_serial_port) self.send_btn.clicked.connect(self.send_data) self.send_input.returnPressed.connect(self.send_data) # 串口核心信号 self.serial_port.readyRead.connect(self.read_serial_data) # 接收数据 self.serial_port.errorOccurred.connect(self.handle_serial_error) # 错误处理 def refresh_serial_ports(self): """枚举并刷新可用串口""" self.port_combo.clear() # 获取所有可用串口 available_ports = QSerialPortInfo.availablePorts() for port_info in available_ports: # 显示格式：串口名 - 设备描述 port_text = f"{port_info.portName()} - {port_info.description()}" self.port_combo.addItem(port_text, port_info.portName()) def open_serial_port(self): """配置并打开串口""" if self.port_combo.count() == 0: self._append_recv_text("错误：无可用串口！") return # 获取选中的串口名 selected_port = self.port_combo.currentData() if not selected_port: self._append_recv_text("错误：无效的串口！") return # 1. 配置串口参数 self.serial_port.setPortName(selected_port) self.serial_port.setBaudRate(QSerialPort.Baud9600) # 波特率 9600 self.serial_port.setDataBits(QSerialPort.Data8) # 数据位 8 self.serial_port.setParity(QSerialPort.NoParity) # 无校验 self.serial_port.setStopBits(QSerialPort.OneStop) # 停止位 1 self.serial_port.setFlowControl(QSerialPort.NoFlowControl) # 无流控 # 2. 打开串口（读写模式） if self.serial_port.open(QSerialPort.ReadWrite): self._append_recv_text(f"成功：打开串口 {selected_port}") self.open_btn.setEnabled(False) self.close_btn.setEnabled(True) self.port_combo.setEnabled(False) self.refresh_btn.setEnabled(False) else: self._append_recv_text(f"错误：打开串口 {selected_port} 失败（权限不足/端口被占用）") def close_serial_port(self): """关闭串口""" if self.serial_port.isOpen(): self.serial_port.close() self._append_recv_text(f"信息：串口 {self.serial_port.portName()} 已关闭") self.open_btn.setEnabled(True) self.close_btn.setEnabled(False) self.port_combo.setEnabled(True) self.refresh_btn.setEnabled(True) def send_data(self): """向串口发送数据""" if not self.serial_manager.serial_port.isOpen(): self._append_recv_text("错误：串口未打开！") return # 获取输入框数据并转换为字节类型（必须传入 bytes，字符串需 encode） input_text = self.send_input.text().strip() if not input_text: return # 判断是否为十六进制格式（去除空格后检查是否全为十六进制字符） clean_text = input_text.replace(' ', '').replace('\t', '').replace('\n', '') # 如果是十六进制字符串，则转换为字节数组 if all(c in '0123456789ABCDEFabcdef' for c in clean_text) and len(clean_text) % 2 == 0: try: # 将十六进制字符串转换为字节数组 send_bytes = bytes.fromhex(clean_text) except ValueError: self._append_recv_text("错误：十六进制数据格式不正确！") return else: # 按普通字符串处理 send_bytes = input_text.encode("utf-8") # 写入串口（encode 转换为 UTF-8 字节流，外设需对应编码） written_bytes = self.serial_manager.serial_port.write(send_bytes) if written_bytes > 0: # 显示发送的十六进制数据 send_hex = send_bytes.hex().upper() self._append_recv_text(f"发送：{send_hex}（字节数：{written_bytes}）") # self.send_input.clear() def read_serial_data(self): """读取串口接收的数据（响应 readyRead 信号）""" if not self.serial_port.isOpen(): return # 读取所有可用数据（QByteArray -> bytes -> str） recv_data = self.serial_port.readAll() # 转换为 Python 字节类型，再解码为字符串（与发送端编码一致） recv_str = bytes(recv_data).decode("utf-8", errors="ignore") if recv_str: self._append_recv_text(f"接收：{recv_str}") def handle_serial_error(self, error): """处理串口错误（响应 errorOccurred 信号）""" # 在 PySide6 中，使用 QSerialPort.SerialPortError 枚举值 if error == QSerialPort.SerialPortError.NoError: error_msg = "信息：无错误" elif error == QSerialPort.SerialPortError.DeviceNotFoundError: error_msg = "错误：串口端口不存在" elif error == QSerialPort.SerialPortError.PermissionError: error_msg = "错误：串口权限不足" elif error == QSerialPort.SerialPortError.OpenError: error_msg = "错误：无法打开串口（可能已被其他程序占用）" elif error == QSerialPort.SerialPortError.NotOpenError: error_msg = "错误：串口未打开" elif error == QSerialPort.SerialPortError.ResourceError: error_msg = "错误：串口资源被占用或断开连接" elif error == QSerialPort.SerialPortError.UnsupportedOperationError: error_msg = "错误：不支持的操作" elif error == QSerialPort.SerialPortError.TimeoutError: error_msg = "错误：操作超时" elif error == QSerialPort.SerialPortError.UnknownError: error_msg = "错误：未知串口错误" else: error_msg = f"错误：未知串口错误（代码：{error})" self._append_recv_text(error_msg) # 错误发生时自动关闭串口 self.close_serial_port() def _append_recv_text(self, text): """向接收区域追加文本并自动滚动""" self.recv_text.append(text) # 自动滚动到最下方 scroll_bar = self.recv_text.verticalScrollBar() scroll_bar.setValue(scroll_bar.maximum()) def closeEvent(self, event): """窗口关闭时自动关闭串口""" if self.serial_port.isOpen(): self.serial_port.close() event.accept() if __name__ == "__main__": app = QApplication(sys.argv) window = SerialPortTool() window.show() sys.exit(app.exec())

五、运行与使用说明

1. 运行效果：启动程序后，会自动枚举系统中的可用串口，显示在下拉框中。
2. 操作步骤：
   • 选择需要连接的串口（如 "COM3 - USB-SERIAL CH340"）
   • 点击「打开串口」（成功后按钮状态切换）
   • 在输入框中输入数据，点击「发送数据」或按回车发送
   • 外设返回数据后，会自动显示在下方接收区域
   • 结束通信后，点击「关闭串口」释放资源

六、关键注意事项

1. 数据格式：QSerialPort.write() 仅接受字节类型（bytes），字符串必须通过 encode() 转换；读取数据时，readAll() 返回 QByteArray，需先转换为 bytes 再 decode() 为字符串。
2. 串口参数一致性：波特率、数据位等参数必须与外设完全一致，否则会出现乱码或无法通信。
3. 异步无阻塞：QtSerialPort 采用异步通信，readyRead() 信号仅在有新数据到达时触发，无需轮询（轮询会导致阻塞，影响界面响应）。
4. 资源释放：串口使用完毕后必须调用 close() 关闭，否则会导致端口被占用，下次无法打开。
5. 编码一致性：收发数据的编码格式（如 UTF-8、GBK）必须与外设保持一致，否则会出现乱码。

七、总结

1. QtSerialPort 库的核心是 QSerialPort（串口操作）和 QSerialPortInfo（串口枚举）。
2. 串口通信的核心流程是「配置参数→打开串口→绑定信号槽→读写数据→关闭串口」。
3. 异步通信依赖 readyRead() 信号接收数据，无需轮询，保证界面响应流畅。
4. 数据格式转换（字符串 ↔ 字节）和串口参数一致性是串口通信成功的关键。