Python pyserial库安装与基础串口通信代码示例

宋时安
宋时安
发布时间:2026-11-22 | 17人浏览过
原创

详细讲解Python中pyserial库的正确安装步骤、各操作系统下的串口设备识别方法、核心参数配置,并提供完整的串口读写代码示例与异常排查指南。

在利用 Python 与单片机、工业传感器、PLC 或其他嵌入式硬件通信时,串口通信(Serial Communication)是最常用、最直接的方式。Python 官方并未内置串口驱动模块,通常使用成熟的第三方库 pyserial 来实现底层数据交互。本文将系统梳理 pyserial 的安装要点、各操作系统的端口辨识方法、通信参数的配置原则,并提供完整且健壮的收发代码示例。

一、pyserial 的安装与环境准备

在安装串口通信库时,最容易出现混淆的是包名称。Python 社区早期存在一个废弃的 serial 包,如果错误安装该包会导致后续调用失败。正确的第三方库名称为 pyserial,但在 Python 代码中导入时的命名空间依然是 serial。

打开终端(Windows 下为 PowerShell 或命令提示符,macOS/Linux 下为 Terminal),在激活的 Python 环境中执行以下安装命令:

pip install pyserial

如果之前误安装了 serial,需要先将其卸载,再重新安装 pyserial,避免命名冲突:

# 若曾误装 serial,需先清理
pip uninstall serial
pip install pyserial

安装完成后,可以在命令行进入 Python 交互界面,输入以下代码验证安装版本与可用性:

import serial
print(serial.__version__)

当屏幕输出版本号(例如 3.5)且无报错时,表明安装成功。

Python pyserial库安装与基础串口通信代码示例
图 1:pyserial 安装、USB 硬件接入识别与端口枚举操作流程

二、串口设备的识别与端口扫描

在使用代码打开串口之前,必须明确目标设备所连接的端口名称。由于底层操作系统不同,端口的表示形式存在显著差异:

  • Windows:通常表示为 COM1、COM3、COM8 等。可以通过系统自带的“设备管理器 -> 端口 (COM 和 LPT)”直接查看。
  • Linux:标准串口通常命名为 /dev/ttyS*,USB 转串口模块(如 CH340、FTDI 等)则通常命名为 /dev/ttyUSB0 或 /dev/ttyACM0。
  • macOS:通常表示为 /dev/cu.usbserial-* 或 /dev/tty.usbmodem*。在 Python 脚本通信中,推荐优先选用 /dev/cu.* 节点,其不会因 DCD 载波信号而引发非预期的等待。

pyserial 提供了内置模块 serial.tools.list_ports,允许我们在不依赖系统原生工具的情况下,直接在 Python 脚本中枚举所有可用端口:

import serial.tools.list_ports

def list_available_ports():
    ports = serial.tools.list_ports.comports()
    if not ports:
        print("未检测到任何可用串口设备。")
        return []
    
    print(f"共发现 {len(ports)} 个串口设备:")
    for port in ports:
        print(f"端口名: {port.device} | 描述: {port.description} | 硬件ID: {port.hwid}")
    return [p.device for p in ports]

if __name__ == "__main__":
    list_available_ports()

执行该脚本后,控制台会输出当前接入的所有串口设备列表,这为后续通信提供了精确的端口参数。

三、串口通信的核心参数解析

串口通信双方必须保持通信协议参数完全一致,任何一个参数不匹配,都会直接导致数据出现乱码或完全无法接收。这些核心参数包括:

参数名 对应属性 常用默认值 技术含义与设置说明
端口号 (Port) port 无(必填) 通信实体的硬件路径,如 Windows 下的 COM3,Linux 下的 /dev/ttyUSB0。
波特率 (Baudrate) baudrate 9600 每秒传输的符号数。常见标准速率有 9600、19200、38400、57600、115200。通信双方速率必须严格匹配。
数据位 (Bytesize) bytesize 8 (EIGHTBITS) 每个数据帧中承载的有效二进制位数,一般使用 8 位(包含 1 字节),特殊工业协议使用 7 位。
校验位 (Parity) parity None (PARITY_NONE) 用于检错的奇偶校验位。可选 'N' (无校验)、'E' (偶校验)、'O' (奇校验) 等。大多数嵌入式通信设为无校验。
停止位 (Stopbits) stopbits 1 (STOPBITS_ONE) 标志一个字符传输结束的位长度。通常设为 1,部分硬件需要设为 1.5 或 2。
超时时间 (Timeout) timeout None (永久阻塞) 读取数据时的等待时限(单位:秒)。强烈建议显式指定(如 timeout=1.0),避免没有数据时程序陷入死锁。
Python pyserial库安装与基础串口通信代码示例
图 2:串口 8-N-1 协议数据帧格式与 pyserial 双向 FIFO 缓冲流转模型

四、基础串口通信完整代码示例

串口通信传输的内容始终是裸字节序列(bytes 类型),而不是 Python 的字符串(str)。因此:

  • 发送数据:必须先通过 .encode('utf-8') 或 b'...' 转换为 bytes 后再调用 ser.write()。
  • 接收数据:从 ser.read() 或 ser.readline() 获取的是 bytes,需要通过 .decode('utf-8') 解码为字符串展示。

以下示例演示了打开串口、发送请求、同步等待回复并安全释放资源的完整流程:

import serial
import time

def run_serial_communication():
    # 1. 串口配置参数
    port_name = "COM3"       # 根据实际系统调整,Linux可写为 "/dev/ttyUSB0"
    baud_rate = 9600        # 波特率需与下位机完全一致
    timeout_sec = 2.0       # 设置超时时间为 2 秒

    print(f"正在尝试打开串口: {port_name}...")
    
    # 2. 建立串口连接(推荐使用 with 语句实现上下文管理)
    try:
        with serial.Serial(
            port=port_name,
            baudrate=baud_rate,
            bytesize=serial.EIGHTBITS,
            parity=serial.PARITY_NONE,
            stopbits=serial.STOPBITS_ONE,
            timeout=timeout_sec
        ) as ser:
            print(f"串口 {port_name} 打开成功!")
            
            # 部分开发板(如 Arduino)在打开串口后会自动复位,需预留 2 秒初始化时间
            time.sleep(2.0)
            
            # 清空历史残留的输入与输出缓冲区
            ser.reset_input_buffer()
            ser.reset_output_buffer()

            # 3. 发送数据
            message = "PING\r\n"
            data_to_send = message.encode("utf-8")
            bytes_written = ser.write(data_to_send)
            print(f"已发送 {bytes_written} 字节数据: {repr(message)}")

            # 4. 接收响应数据
            print("等待下位机回复...")
            # 使用 readline 读取以换行符结尾的一行数据
            response_bytes = ser.readline()
            
            if response_bytes:
                # 成功接收到数据,进行解码
                response_str = response_bytes.decode("utf-8", errors="replace").strip()
                print(f"收到回复: {response_str} (原始字节: {response_bytes})")
            else:
                print("在超时时限内未收到任何有效回复。")

    except serial.SerialException as e:
        print(f"串口通信发生异常: {e}")
    except Exception as e:
        print(f"执行过程发生未知错误: {e}")

if __name__ == "__main__":
    run_serial_communication()
代码关键点说明:

1. serial.Serial 支持 Python 的上下文管理器协议(with 语句)。无论是正常结束还是中间发生异常,离开作用域时都会自动调用 ser.close(),避免串口句柄被长期占用。

2. ser.reset_input_buffer() 非常重要。物理设备在待机时可能向总线发送干扰字符,发送指令前清空缓存,可以有效避免读取到历史残存脏数据。

3. 换行符匹配:许多硬件指令依靠 \r\n(回车换行)判定指令结束。如果遗漏了 \r\n,下位机可能会持续等待,导致超时无回复。

Python pyserial库安装与基础串口通信代码示例
图 3:基于 pyserial 的完整串口请求-应答与生命周期时序交互过程

五、数据读取方式:read、readline 与 in_waiting 的选择

在不同场景下,下位机发送数据的数据流形态不同,选择合适的读取函数至关重要:

  • ser.readline():按行读取
    适用于发送以 \n(或 \r\n)结尾的 ASCII 文本协议。函数会持续读取直至遇到换行符,或者达到 timeout 超时时间。注意:如果下位机未发送换行符,该方法会一直阻塞直至超时。
  • ser.read(size):定长读取
    适用于 Modbus、传感器私有十六进制(Hex)等二进制协议。传入要读取的固定字节数(例如 ser.read(8))。若指定字节数未满且未超时,会保持等待。
  • ser.in_waiting:被动轮询非阻塞读取
    返回当前接收缓冲区中已到达且未被读取的字节总数。可以配合 time.sleep() 实现灵活的分包接收:
    # 非阻塞批量读取当前已到达的所有字节
    if ser.in_waiting > 0:
        raw_data = ser.read(ser.in_waiting)
        print("收到原始字节数据:", raw_data.hex())

六、常见报错分析与排查矩阵

在实际串口通信过程中,往往会遇到各类硬件占线、权限或格式问题。以下总结了最高频的报错现象与直接解决方案:

Python pyserial库安装与基础串口通信代码示例
图 4:pyserial 常见通信故障根因剖析与排查解决决策矩阵

七、总结

使用 Python 实现串口通信的核心步骤可以归纳为:“装对包名、查准端口、参数对齐、字节收发、超时兜底”。在编写实际工程代码时,建议始终遵循以下规范:

  1. 使用 pip install pyserial 并在代码中通过 import serial 调用,避免第三方库命名冲突。
  2. 通过 serial.tools.list_ports 自动发现端口或在配置文件中灵活配置,保证多平台部署的兼容性。
  3. 初始化 serial.Serial 时务必设置合理的 timeout,并通过 with 上下文管理器确保系统句柄及时安全释放。
  4. 在发送前统一转换成 bytes,在接收后根据下位机固件特征(UTF-8 或 GBK)安全解码,并结合 reset_input_buffer() 保持信道纯净。
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表