pyserial 是 Python 中用于串口通信最常用、最标准的库，无论是连接 Arduino、GPS 模块、各种传感器还是其他串口设备，都离不开它。

什么是 pyserial？

pyserial 是一个纯 Python 模块，它提供了对串口的访问功能，通过它，你可以：

• 打开和关闭串口。
• 从串口读取数据。
• 向串口写入数据。
• 配置串口参数（如波特率、数据位、停止位、校验位等）。

如何安装 pyserial？

安装 pyserial 非常简单，通常使用 Python 的包管理工具 pip 即可。

使用 pip (推荐)

这是最常用、最标准的方法，打开你的终端或命令提示符，然后执行以下命令：

对于 Windows 系统： 打开命令提示符 或 PowerShell。

pip install pyserial

对于 macOS 或 Linux 系统： 打开终端。

pip install pyserial

验证安装

安装完成后,你可以通过以下命令来验证是否安装成功：

pip show pyserial

如果安装成功,你会看到类似下面的输出，显示了 pyserial 的版本和位置：

Name: pyserial
Version: 3.5
Summary: Python Serial Port Extension
Home-page: https://github.com/pyserial/pyserial
Author: Chris Liechti
Author-email: cliechti@gmx.net
License: BSD
Location: /your/python/path/lib/python3.9/site-packages
Requires:
Required-by:

你还可以在 Python 交互式环境中尝试导入它：

import serial
print(serial.__version__)

如果成功打印出版本号,说明安装无误。

一个简单的使用示例

安装完成后,我们来看一个最简单的例子，它演示了如何打开一个串口，写入一行数据，然后读取一行数据。

注意： 在运行此代码之前，请确保你有一个串口设备连接到电脑（例如一个 Arduino 开发板），并且你知道它的串口号（在 Windows 上通常是 COM3, COM4 等，在 macOS/Linux 上通常是 /dev/tty.usbserial 或 /dev/ttyACM0 等），如果不知道，可以在设备管理器（Windows）或使用 ls /dev/tty.* (macOS) 命令中查找。

import serial
import time
# --- 1. 配置串口参数 ---
# 请将 'COM3' 替换为你自己的串口号
# Windows 示例: 'COM3'
# macOS/Linux 示例: '/dev/tty.usbserial-XXXX' 或 '/dev/ttyACM0'
SERIAL_PORT = 'COM3' 
BAUD_RATE = 9600  # 波特率，必须与你的设备设置一致
try:
    # --- 2. 打开串口 ---
    # serial.Serial() 会尝试打开串口
    # timeout=1 设置读取超时为1秒，如果没有数据，1秒后返回
    ser = serial.Serial(SERIAL_PORT, BAUD_RATE, timeout=1)
    print(f"成功打开串口: {ser.name}")
    # --- 3. 向串口写入数据 ---
    # 写入必须是字节串 (bytes)，所以需要用 .encode()
    message_to_send = "Hello from Python!\n"
    ser.write(message_to_send.encode('utf-8'))
    print(f"已发送: {message_to_send.strip()}")
    # --- 4. 从串口读取数据 ---
    # time.sleep(0.5) 等待设备处理并发送回数据
    time.sleep(0.5) 
    # ser.readline() 会读取一行，以换行符 '\n' 
    # 如果超时，会返回空字节串 b''
    received_data = ser.readline()
    if received_data:
        # 将接收到的字节串解码为字符串
        print(f"已接收: {received_data.decode('utf-8').strip()}")
    else:
        print("没有接收到数据（可能是超时）。")
except serial.SerialException as e:
    print(f"错误: 无法打开串口 {SERIAL_PORT}，请检查串口号和设备是否连接。")
    print(f"错误详情: {e}")
finally:
    # --- 5. 关闭串口 ---
    # 使用 finally 确保无论如何都会执行关闭操作，防止资源泄漏
    if 'ser' in locals() and ser.is_open:
        ser.close()
        print("串口已关闭。")

常见问题与解决方法

Q1: pip install pyserial 失败，提示 pip 不是内部或外部命令...

原因： Windows 系统没有将 Python 的 Scripts 目录添加到系统的环境变量 PATH 中。 解决方法：

1. 找到你的 Python 安装路径（C:\Python39）。
2. 将 C:\Python39\ 和 C:\Python39\Scripts\ 这两个路径添加到系统的 PATH 环境变量中。
3. 重新打开一个新的命令提示符窗口，再尝试安装。

Q2: 运行代码时，提示 SerialException: could not open port 'COM3': [Errno 2] The system cannot find the file specified

原因：

• 串口号写错了。
• 设备没有正确连接或没有安装驱动。
• 该串口正被其他程序（如 Arduino IDE、串口调试助手等）占用。 解决方法：

1. 检查串口号： 在 Windows 的“设备管理器” -> “端口 (COM 和 LPT)” 中查找正确的串口号。
2. 检查连接和驱动： 确保设备已插入，并且驱动安装正确。
3. 关闭占用程序： 关闭所有可能使用该串口的软件，然后重新运行你的 Python 脚本。

Q3: 运行代码时，提示 SerialException: cannot configure port, it is already open

原因： 你的 Python 脚本已经打开了这个串口，但没有正确关闭（程序中途崩溃），导致串口被锁定。 解决方法：

1. 重启电脑： 这是最简单粗暴但有效的方法。
2. 找到占用进程： 在 Windows 任务管理器中，查看是否有 python.exe 或其他可疑进程，有时重启 IDE（如 VS Code, PyCharm）也能解决问题。
3. 确保代码健壮： 使用 try...finally 结构（如上面的示例），确保无论是否发生错误，串口最终都会被关闭。

pyserial 的其他常用功能

除了基本的读写,pyserial 还有很多有用的功能：

• 获取可用串口列表：

  import serial.tools.list_ports
  ports = serial.tools.list_ports.comports()
  for port in ports:
      print(port.device) # 打印所有可用的串口号

• 检查串口状态：

  if ser.is_open:
      print("串口是打开的")
  else:
      print("串口是关闭的")

• 配置串口参数：

  ser.baudrate = 115200  # 修改波特率
  ser.bytesize = serial.EIGHTBITS  # 数据位
  ser.parity = serial.PARITY_NONE  # 校验位
  ser.stopbits = serial.STOPBITS_ONE  # 停止位

希望这份详细的指南能帮助你成功下载和使用 pyserial！