Python使用pyserial接收串口数据的基础代码示例
本文详细介绍在Python中使用pyserial库接收串口数据的基础实现方法,涵盖环境准备、端口检测、基础阻塞与行读取代码示例、缓冲区状态判断及常见异常处理。
在硬件联动、单片机调试及工业传感器采集中,Python凭借简洁的语法成为处理串口通信的高频工具。使用Python接收串口数据的最直接路径是借助第三方库pyserial,其基本流程包含四个核心动作:确认硬件端口并安装驱动支持、通过指定波特率与超时时间打开串口连接、在循环检测中读取字节流并转换为文本字符、最后妥善捕获退出信号以关闭并释放串口资源。
一、环境准备与依赖安装
在开始编写代码前,需要明确一个极其常见的安装陷阱:在终端中安装库时,对应的包名称是 pyserial,而不是单独的 serial。如果错误安装了名为 serial 的第三方包,可能会导致模块命名冲突与属性缺失错误。
在操作系统终端或虚拟环境中执行以下命令安装依赖:
pip install pyserial
安装完成后,建议先使用内置工具扫描当前计算机已挂载的串口设备。由于不同操作系统的端口命名规则截然不同(Windows为 COM1、COM3,Linux为 /dev/ttyUSB0 或 /dev/ttyS0,macOS为 /dev/tty.usbserial-*),通过代码扫描可以避免盲目硬编码导致端口不存在错误:
import serial.tools.list_ports
ports = serial.tools.list_ports.comports()
if not ports:
print("未检测到任何可用串口设备,请检查USB物理连接或驱动状态。")
else:
print("检测到以下可用串口:")
for port in ports:
print(f"设备端口: {port.device} - 描述: {port.description}")
终端运行输出示例:
检测到以下可用串口:
设备端口: COM3 - 描述: USB-SERIAL CH340 (COM3)
二、标准接收步骤与核心逻辑
接收串口数据并不是一次性的简单文件读取,而是面向流式传输的持续监听。在具体编写代码时,应当遵循明确的四个操作阶段。
三、完整基础代码示例
下面是一个经过实际验证、可直接复制运行的控制台监听脚本。示例设定串口为 COM3,波特率为 9600,读取超时时间为 1.0 秒。在Linux或macOS环境下,只需将变量 port_name 调整为对应的设备路径(例如 /dev/ttyUSB0)。
import time
import serial
def start_serial_listener(port_name: str, baud_rate: int = 9600):
"""
建立串口连接并持续接收以换行符分隔的文本数据
:param port_name: 串口号(Windows形如 'COM3', Linux形如 '/dev/ttyUSB0')
:param baud_rate: 通信波特率,默认为 9600
"""
ser = None
try:
# 1. 实例化并打开串口
# timeout 设置为 1.0 秒,若在指定时间内未读到数据则返回空字节,防止线程死锁
ser = serial.Serial(port=port_name, baudrate=baud_rate, timeout=1.0)
# 很多物理单片机在串口建立后会产生短暂复位,等待 1~2 秒以确保状态稳定
time.sleep(1.5)
# 2. 清空历史残留缓冲区,保证从最新数据开始接收
ser.reset_input_buffer()
print(f"成功打开串口 [{port_name}],波特率: {baud_rate}。按 Ctrl+C 可停止监听...\n")
# 3. 循环监听数据流
while True:
# 检查底层接收缓冲区中是否有未读取的字节
if ser.in_waiting > 0:
# 读取一行数据(默认读取到 \n 为止)
raw_bytes = ser.readline()
# 解码为字符串并剔除首尾空白与换行符
try:
text_data = raw_bytes.decode("utf-8").strip()
if text_data:
print(f"[收到数据] {text_data}")
except UnicodeDecodeError:
# 针对部分中文或工业设备可能采用 GBK 编码的情况进行兜底
text_data = raw_bytes.decode("gbk", errors="replace").strip()
print(f"[GBK解码数据] {text_data}")
# 避免空转过多占用 CPU
time.sleep(0.01)
except serial.SerialException as err:
print(f"串口错误: 无法打开或操作串口 [{port_name}] -> {err}")
except KeyboardInterrupt:
print("\n检测到用户中断操作,正在退出程序...")
finally:
# 4. 无论正常退出还是异常报错,都必须释放串口资源
if ser is not None and ser.is_open:
ser.close()
print("串口已安全关闭,释放系统句柄。")
if __name__ == "__main__":
# 执行前请确保端口名称与你设备连接的实际端口保持一致
TARGET_PORT = "COM3"
start_serial_listener(port_name=TARGET_PORT, baud_rate=9600)
终端运行输出示例:
成功打开串口 [COM3],波特率: 9600。按 Ctrl+C 可停止监听...
[收到数据] TEMP: 24.5C, HUMI: 60%
[收到数据] TEMP: 24.6C, HUMI: 59%
[收到数据] STATUS: OK
^C
检测到用户中断操作,正在退出程序...
串口已安全关闭,释放系统句柄。
四、核心参数与关键机制解析
1. 为什么必须显式配置 timeout 超时?
在默认情况下,若不传递 timeout 参数(即 timeout=None),readline() 或 read() 将处于绝对阻塞模式:如果下位机没有发送换行符或者断开了连接,Python程序将在此处无限期挂起,甚至无法响应普通的控制台信号。
2. readline() 与 read() 的取舍
ser.readline() 依赖预设的行分隔符(默认是 \n,ASCII码 0x0A)。如果下位机发送的是包含回车换行的文本协议(如 NMEA 0183 GPS 数据或温度传感器日志),readline() 是最便捷的选择。但如果下位机传输的是二进制结构体、自定义协议帧或者没有换行结尾的数据流,则应当使用 ser.read(size) 按固定字节数读取,或者通过 ser.read(ser.in_waiting) 一次性把当前硬件缓冲区中的所有字节全部取出后,在内存中自行组包与校验。
五、常见问题与排查对策
排查清单:
- 报错:
SerialException: could not open port
原因通常有两个:一是端口名称写错或设备未正确插入;二是端口被其他串口调试助手(如 XCOM、SSCOM 或另一运行中的 Python 进程)独占。Windows 环境下串口为排他性资源,同时只能由一个进程打开。 - 输出内容出现乱码(包含大量问号或乱字符)
波特率不匹配是造成乱码的最主要诱因。请确认下位机配置的波特率与代码中的baudrate完全相同(例如常见的 9600、115200)。此外,字符集编码若不是 UTF-8,应尝试使用gbk方式解码。 - 数据断裂与粘包现象
串口传输属于底层流式通信,不具备消息边界概念。当下位机高频发送时,单次读取可能拿到半截数据。对于严谨项目,务必设计协议帧头帧尾(如以特定字节起始、换行结束),并在应用层维护一个字节接收缓冲区进行拼包解析。
六、总结与关键规范
在 Python 中使用 pyserial 接收串口数据是一项非常成熟的技术,但在工程落地时必须遵循严谨的编码规范以保证进程稳定性。
只要做好端口的动态探测、为读取流程设置合理的超时保护,并在异常分支中确保句柄正常关闭,Python 就能在嵌入式上位机监控与工业设备数据采集等场景中稳定可靠地运行。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













