Python PySerial 库-深圳市維司達科技有限公司

PySerial 是 Python 中用于串口（UART）通信的跨平台第三方库，支持 Windows、Linux、macOS 等多种操作系统，提供了简洁、一致的 API 用于串口设备的读写和控制。

1. 安装 PySerial

在开始使用前，需要通过 pip 安装该库。

pip install pyserial

安装完成后，可以在 Python 脚本中验证是否成功：

import serial print("pyserial version:", serial.__version__)

2. 基本使用流程

使用 PySerial 进行串口通信通常遵循以下步骤：导入库 -> 配置并打开串口 -> 读写数据 -> 关闭串口。

2.1 导入库并打开串口

首先导入serial模块，然后创建Serial对象来初始化并打开串口。

import serial # 初始化串口连接，参数可在此处设置 ser = serial.Serial( port='COM3', # Windows 端口名，如 COM1；Linux/macOS 为 /dev/ttyUSB0 等[1](@ref)[6](@ref) baudrate=9600, # 波特率，常见值有 9600, 115200 等[5](@ref) bytesize=serial.EIGHTBITS, # 数据位，8位 parity=serial.PARITY_NONE, # 校验位，无校验 stopbits=serial.STOPBITS_ONE, # 停止位，1位 timeout=1 # 读超时时间（秒），None为无限等待，0为非阻塞[1](@ref) )

创建Serial对象时，若指定了port，串口通常会立即打开。你也可以先创建对象，后续再配置参数并手动打开：

ser = serial.Serial() ser.port = 'COM3' ser.baudrate = 115200 ser.open()

2.2 检查串口状态

可以使用is_open属性检查串口是否成功打开。

if ser.is_open: print(f"串口 {ser.port} 已打开") else: print("串口打开失败")

2.3 读写数据

写入数据：使用write()方法，参数必须是字节类型（bytes）。

# 发送字符串（需编码为字节） ser.write("Hello, Serial!".encode('utf-8')) # 或直接发送字节数据 ser.write(b'\x01\x02\x03')

读取数据：有多种读取方法。
- read(size=1)：读取指定大小的字节数。
- readline()：读取一行，以换行符\n结束。
- read_all()：读取接收缓冲区中的所有数据。
```
data = ser.read(10) # 读取最多10个字节 line = ser.readline() # 读取一行 print(line.decode('utf-8')) # 将字节数据解码为字符串
```
在读取前，可用in_waiting属性检查接收缓冲区中的字节数。
```
if ser.in_waiting: data = ser.read(ser.in_waiting)
```

2.4 关闭串口

通信完成后，应关闭串口以释放资源。

ser.close()

为了确保串口被正确关闭，推荐使用with语句（上下文管理器），它会在代码块执行完毕后自动关闭串口。

with serial.Serial('COM3', 9600, timeout=1) as ser: ser.write(b'Hello') data = ser.readline()

3. 常用方法与属性

除了基本的读写，PySerial 还提供了其他有用的方法和属性：

flushInput()：清空输入缓冲区，丢弃所有待读取数据。
flushOutput()：清空输出缓冲区，终止当前写操作。
flush()：等待所有数据写出。
串口参数获取与设置：创建对象后，仍可动态修改部分属性，如ser.baudrate = 115200。

获取端口列表：可以使用serial.tools.list_ports来列出当前可用的串口。

import serial.tools.list_ports ports = serial.tools.list_ports.comports() for port in ports: print(port.device)

4. 实际应用示例

以下是一个完整的简单示例，实现了打开串口、发送指令并读取回复的功能：

import serial import time def main(): # 1. 配置并打开串口 ser = serial.Serial( port='COM3', baudrate=9600, bytesize=serial.EIGHTBITS, parity=serial.PARITY_NONE, stopbits=serial.STOPBITS_ONE, timeout=2 # 设置读超时为2秒 ) try: if not ser.is_open: ser.open() # 2. 发送数据 command = b'READ_DATA\r\n' # 示例指令，通常需要根据设备协议定义 ser.write(command) print(f"Sent: {command}") # 3. 等待并读取回复 time.sleep(0.1) # 根据设备响应时间适当等待 if ser.in_waiting: response = ser.readline() print(f"Received: {response.decode('utf-8').strip()}") except serial.SerialException as e: print(f"串口通信错误: {e}") except Exception as e: print(f"发生错误: {e}") finally: # 4. 确保关闭串口 if ser and ser.is_open: ser.close() print("串口已关闭") if __name__ == '__main__': main()

5. 常见问题与注意事项

串口无法打开：可能原因是端口号错误、端口被其他程序占用，或在 Linux/macOS 上权限不足。请检查端口名并使用serial.tools.list_ports.comports()确认可用端口。
数据读写异常或无数据：
- 确保通信双方的波特率、数据位、停止位、校验位等参数完全一致。
- 检查物理连接（如 USB 转串口线）是否正常。
- 适当调整timeout参数，避免因设备响应慢导致读超时。
数据格式处理：串口传输的是原始字节流。发送字符串前需用.encode()编码，接收后需用.decode()解码。务必确认设备使用的字符编码（通常为 UTF-8 或 ASCII）。
跨平台兼容性：PySerial 是跨平台的，但端口名称因系统而异：Windows 为COMx，Linux 通常为/dev/ttyUSBx或/dev/ttySx，macOS 为/dev/tty.usbserialxxx。