PySide6 QtSerialPort 库串口通信开发指南

PySide6 QtSerialPort 库用于串口异步通信，核心类为 QSerialPort 和 QSerialPortInfo。文章介绍了串口参数配置、信号与槽机制下的非阻塞读写流程，以及错误处理和资源释放。提供了完整的 GUI 示例代码，涵盖端口枚举、数据收发及界面交互，强调波特率一致性与字节编码转换的重要性。

颠三倒四发布于 2026/3/21更新于 2026/4/187 浏览

一、简介

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

二、QtSerialPort 库的核心内容

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

1. 核心操作类：`QSerialPort`

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

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

QSerialPort 常用属性（串口参数）

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

参数类型	示例	说明
波特率	`QSerialPort.Baud9600`, `QSerialPort.Baud115200`	串口通信速率，最常用 9600、115200
数据位	`QSerialPort.Data8`, `QSerialPort.Data7`	每帧数据的位数，最常用 8 位
校验位	`QSerialPort.NoParity`, `QSerialPort.EvenParity`	奇偶校验位，最常用无校验（NoParity）
停止位	`QSerialPort.OneStop`, `QSerialPort.TwoStop`	数据帧结束标志，最常用 1 位
流控	`QSerialPort.NoFlowControl`, `QSerialPort.HardwareControl`	流量控制，最常用无流控

QSerialPort 常用信号

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

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

`QSerialPort` 常用方法

相关免费在线工具

curl 转代码

解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。在线工具，curl 转代码在线工具，online

Base64 字符串编码/解码

将字符串编码和解码为其 Base64 格式表示形式即可。在线工具，Base64 字符串编码/解码在线工具，online

Base64 文件转换器

将字符串、文件或图像转换为其 Base64 表示形式。在线工具，Base64 文件转换器在线工具，online

Markdown转HTML

将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。在线工具，Markdown转HTML在线工具，online

HTML转Markdown

将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。在线工具，HTML转Markdown在线工具，online

JSON 压缩

通过删除不必要的空白来缩小和压缩JSON。在线工具，JSON 压缩在线工具，online

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_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_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())

PySide6 QtSerialPort 库串口通信开发指南

一、简介

二、QtSerialPort 库的核心内容

1. 核心操作类：`QSerialPort`

`QSerialPort` 常用方法

更多推荐文章

相关免费在线工具

2. 辅助信息类：`QSerialPortInfo`

`QSerialPortInfo` 常用方法

三、QtSerialPort 基本使用流程

四、完整可运行示例

五、运行与使用说明

六、关键注意事项

七、总结

PySide6 QtSerialPort 库串口通信开发指南

一、简介

二、QtSerialPort 库的核心内容

1. 核心操作类：QSerialPort

QSerialPort 常用方法

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

2. 辅助信息类：QSerialPortInfo

QSerialPortInfo 常用方法

三、QtSerialPort 基本使用流程

四、完整可运行示例

五、运行与使用说明

六、关键注意事项

七、总结

1. 核心操作类：`QSerialPort`

`QSerialPort` 常用方法

2. 辅助信息类：`QSerialPortInfo`

`QSerialPortInfo` 常用方法