Python pyserial库安装与基础串口通信代码示例
详细讲解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)且无报错时,表明安装成功。
二、串口设备的识别与端口扫描
在使用代码打开串口之前,必须明确目标设备所连接的端口名称。由于底层操作系统不同,端口的表示形式存在显著差异:
- 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),避免没有数据时程序陷入死锁。 |
四、基础串口通信完整代码示例
串口通信传输的内容始终是裸字节序列(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,下位机可能会持续等待,导致超时无回复。
五、数据读取方式: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 实现串口通信的核心步骤可以归纳为:“装对包名、查准端口、参数对齐、字节收发、超时兜底”。在编写实际工程代码时,建议始终遵循以下规范:
- 使用
pip install pyserial并在代码中通过import serial调用,避免第三方库命名冲突。 - 通过
serial.tools.list_ports自动发现端口或在配置文件中灵活配置,保证多平台部署的兼容性。 - 初始化
serial.Serial时务必设置合理的timeout,并通过with上下文管理器确保系统句柄及时安全释放。 - 在发送前统一转换成
bytes,在接收后根据下位机固件特征(UTF-8 或 GBK)安全解码,并结合reset_input_buffer()保持信道纯净。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













