3. pyserial库安装与基础配置

好了，到了真正动手的环节了。这一章我们搞定 pyserial 的安装和基础配置。别小看这一步，我见过太多人在串口参数上栽跟头——波特率设错、超时没配，折腾半天还以为硬件坏了。

3.1 安装 pyserial：两种方式

安装其实很简单，两条命令的事。但我建议你用第二种，尤其是做项目的时候。

方式一：直接 pip 安装

pip install pyserial

这条命令会把 pyserial 装到系统全局的 Python 环境里。方便是方便，但如果你同时做多个项目，依赖版本打架就麻烦了。

方式二：虚拟环境安装（我推荐）

python -m venv uart_env
source uart_env/bin/activate   # Linux/Mac
uart_env\Scripts\activate      # Windows
pip install pyserial

3.2 验证安装

装完之后，进 Python 交互环境敲一行：

import serial
print(serial.__version__)

能正常输出版本号，就说明装好了。如果报错 ModuleNotFoundError，检查一下是不是在虚拟环境里装的，或者 pip 装到了不同的 Python 版本上。

3.3 串口参数设置：核心五要素

串口通信说白了就是两边约好「怎么说话」。参数对不上，数据就是乱码。我当年第一次调 Modbus 设备，波特率设成了 9600，设备是 19200，出来的数据跟天书一样。

下面这五个参数，一个都不能错：

代码里怎么配？看这个例子：

import serial

ser = serial.Serial(
    port='/dev/ttyAMA0',   # 树莓派上的串口设备
    baudrate=9600,
    bytesize=serial.EIGHTBITS,
    parity=serial.PARITY_NONE,
    stopbits=serial.STOPBITS_ONE,
    timeout=1               # 这个后面重点讲
)

3.4 超时处理：最容易忽略的坑

超时这个参数，说白了就是「等多久不等了」。不设超时，程序可能卡死；设得太短，数据没读完就被丢了。

pyserial 支持三种超时模式：

• None：阻塞模式，一直等到数据来。慎用，一旦设备没响应，程序就卡死了。
• 0：非阻塞模式，立即返回。适合轮询场景，但需要自己处理数据拼包。
• 正数（秒）：等待指定时间，超时返回已读取的数据。最常用。

我一般这么设：

# 读超时 1 秒，写超时 0.5 秒
ser = serial.Serial(
    port='/dev/serial0',
    baudrate=115200,
    timeout=1,
    write_timeout=0.5
)

3.5 完整示例：打开与关闭串口

写代码要养成好习惯——用完就关。不然下次打开会报 Permission denied。

import serial

try:
    ser = serial.Serial(
        port='/dev/serial0',
        baudrate=9600,
        timeout=1
    )
    print(f"串口已打开: {ser.port}")
    print(f"参数: {ser.baudrate} {ser.bytesize} {ser.parity} {ser.stopbits}")
    
    # 这里做你的通信逻辑...
    
except serial.SerialException as e:
    print(f"打开串口失败: {e}")
finally:
    if 'ser' in locals() and ser.is_open:
        ser.close()
        print("串口已关闭")

嗯，这里要注意：finally 块里一定要判断 is_open，不然重复关闭会报错。

3.6 本章知识体系

下面这张图把 pyserial 的基础配置流程串起来了，你照着这个思路走，基本不会漏东西：

这张图把从安装到关闭的完整链路画清楚了。你每次配串口，按这个流程走一遍，基本不会漏参数。