Python使用pyserial发送图片文件的完整代码示例

小鹿同学
小鹿同学
发布时间:2026-11-18 | 2人浏览过
原创

本文详解如何使用 Python 的 pyserial 库通过串口发送图片文件,提供完整的发送端与接收端代码示例,深入分析裸字节直发与分包帧协议的差异,并提供可靠传输的最佳工程实践。

在嵌入式开发、单片机屏幕显示或工业设备交互场景中,经常需要通过串行接口向目标终端传输图像。使用 Python 的 pyserial 模块发送图片,本质是以二进制读取图像文件并分发字节流;但由于图片数据体积大且串口底层存在硬件缓冲区限制,直接裸发极易引起缓冲区溢出与字节错乱。本文将先说明核心解决路径,通过方案对比阐述为什么必须使用分块帧协议,再给出包含握手、分片校验与 ACK 确认的完整 Python 代码实现。

方案选择:裸字节直发与分包帧协议的关键差异

通过串口发送图片通常有两种技术路径。明确这两种方式的机制差异与适用边界,是写出稳定代码的前提。

Python使用pyserial发送图片文件的完整代码示例
图 1:裸流传输与分包协议机制的可靠性及适用边界对比

如对比图所示,单纯调用 ser.write(image_bytes) 只能在波特率极低、图片极小且接收端主频极高的理想状态下勉强工作。实际工程中,单片机(如 STM32、ESP32 或 Arduino)内部的 UART 接收缓冲区通常仅为 64 至 256 字节。一旦 Python 端全速写入数万字节,接收端处理速度赶不上硬件中断,就会发生溢出丢失,还原后的图片将严重花屏或无法解析。因此,构建一个轻量的“分包与确认机制”是解决该问题的必要手段。

通信协议设计:轻量级数据帧结构

为了保证传输可控,我们定义一个简洁而健壮的数据帧格式。整个传输过程分为三个阶段:元数据握手(声明图片大小与总包数)、数据包传输(按固定大小切片传输)和传输结束确认。

Python使用pyserial发送图片文件的完整代码示例
图 2:轻量级二进制传输帧结构解析

通过这套帧格式,我们不仅能准确传递图片内容,还能在串口收到噪声杂波时迅速重同步。每次发送完一个数据帧,发送端等待接收端返回一个单字节响应(0x06 表示 ACK 成功,0x15 表示 NAK 校验失败重试)。

整体操作与执行流程

在编写代码前,梳理完整的程序执行流。整个发送过程由五个标准操作步骤构成:

Python使用pyserial发送图片文件的完整代码示例
图 3:发送端标准处理步骤流转图

环境准备

运行示例前,需要安装 pyserial 模块(注意模块导入名为 serial):

pip install pyserial

发送端完整 Python 代码实现

以下为发送图片的完整可运行代码。代码封装了协议打包、分块读取、超时应答等待与重发逻辑,并提供了实时进度显示:

import os
import struct
import time
import serial

# --- 协议常量定义 ---
MAGIC_HEADER = b'\xAA\x55'  # 2字节固定帧头
CMD_METADATA = 0x01          # 元数据包(传输文件大小)
CMD_DATA     = 0x02          # 图像数据切片包
CMD_END      = 0x03          # 传输完成包

RESP_ACK     = b'\x06'       # 确认应答 ACK
RESP_NAK     = b'\x15'       # 校验错误 NAK

CHUNK_SIZE   = 512           # 每个数据包的最大载荷字节数
MAX_RETRIES  = 3             # 单包最大重试次数


def build_frame(cmd: int, seq: int, payload: bytes) -> bytes:
    """
    构造完整的数据帧:
    [Magic:2B] + [CMD:1B] + [Seq:2B] + [Len:2B] + [Payload:NB] + [Checksum:1B]
    """
    header_fields = struct.pack('>BHH', cmd, seq, len(payload))
    frame_body = header_fields + payload
    
    # 计算校验和:将 body 中所有字节求和取低8位
    checksum = sum(frame_body) & 0xFF
    
    return MAGIC_HEADER + frame_body + bytes([checksum])


def send_packet_with_ack(ser: serial.Serial, frame: bytes, seq: int) -> bool:
    """
    发送单个数据帧并等待 ACK,支持失败重试
    """
    for attempt in range(1, MAX_RETRIES + 1):
        ser.write(frame)
        ser.flush()  # 确保数据已全部刷入底层串口物理发送队列
        
        # 等待接收端响应(依赖串口配置的 timeout)
        ack = ser.read(1)
        if ack == RESP_ACK:
            return True
        elif ack == RESP_NAK:
            print(f"\n[警告] 包 #{seq} 校验和错误,正在进行第 {attempt} 次重试...")
        else:
            print(f"\n[超时] 包 #{seq} 未收到 ACK 应答,正在进行第 {attempt} 次重发...")
        
        time.sleep(0.05)  # 重发前做微小延时,让对端恢复
        
    return False


def send_image(port: str, baudrate: int, image_path: str):
    """
    通过串口完整发送指定图片文件
    """
    if not os.path.isfile(image_path):
        raise FileNotFoundError(f"找不到指定的图片文件: {image_path}")

    # 1. 读取图片文件原始二进制字节
    with open(image_path, 'rb') as f:
        image_data = f.read()

    total_bytes = len(image_data)
    total_packets = (total_bytes + CHUNK_SIZE - 1) // CHUNK_SIZE

    print(f"==================================================")
    print(f"准备发送图片: {os.path.basename(image_path)}")
    print(f"文件大小: {total_bytes} 字节 ({total_bytes / 1024:.2f} KB)")
    print(f"分包大小: {CHUNK_SIZE} 字节,总计包数: {total_packets}")
    print(f"目标串口: {port},波特率: {baudrate}")
    print(f"==================================================")

    # 2. 打开串口(设置读超时 1.5 秒,写超时 1.5 秒)
    try:
        with serial.Serial(port=port, baudrate=baudrate, timeout=1.5, write_timeout=1.5) as ser:
            # 清空历史缓冲区残留杂波
            ser.reset_input_buffer()
            ser.reset_output_buffer()
            time.sleep(0.5)  # 某些硬件打开串口时会发生复位,稍作等待

            start_time = time.time()

            # 3. 发送元数据握手包(载荷为 4 字节的大端无符号整型,表示总字节数)
            print("[1/3] 发送元数据握手包...")
            meta_payload = struct.pack('>I', total_bytes)
            meta_frame = build_frame(CMD_METADATA, 0, meta_payload)
            if not send_packet_with_ack(ser, meta_frame, 0):
                print("错误:元数据握手失败,对端未就绪!")
                return

            # 4. 循环发送图片切片数据
            print("[2/3] 开始分包传输图片数据...")
            for seq in range(1, total_packets + 1):
                start_idx = (seq - 1) * CHUNK_SIZE
                end_idx = min(start_idx + CHUNK_SIZE, total_bytes)
                chunk = image_data[start_idx:end_idx]

                data_frame = build_frame(CMD_DATA, seq, chunk)
                if not send_packet_with_ack(ser, data_frame, seq):
                    print(f"\n错误:在传输第 #{seq} 个数据包时重试超过最大次数,传输终止!")
                    return

                # 打印进度条
                progress = (seq / total_packets) * 100
                print(f"\r进度: [{seq}/{total_packets}] {progress:.1f}% 已经发送 {end_idx}/{total_bytes} 字节", end='', flush=True)

            print()

            # 5. 发送结束包
            print("[3/3] 发送传输结束确认包...")
            end_frame = build_frame(CMD_END, total_packets + 1, b'')
            if not send_packet_with_ack(ser, end_frame, total_packets + 1):
                print("警告:结束包未收到确认响应。")
            else:
                elapsed = time.time() - start_time
                speed = (total_bytes / 1024) / elapsed if elapsed > 0 else 0
                print("==================================================")
                print(f"传输完成!总耗时: {elapsed:.2f} 秒,平均速度: {speed:.2f} KB/s")
                print("==================================================")

    except serial.SerialException as e:
        print(f"串口通信发生异常: {e}")


if __name__ == '__main__':
    # 示例调用参数:请根据系统实际情况修改端口号(Windows 如 'COM3',Linux/Mac 如 '/dev/ttyUSB0')
    PORT_NAME = 'COM3'
    BAUD_RATE = 115200
    IMAGE_FILE = 'sample.jpg'

    # 若测试前文件不存在,可在此临时创建占位测试文件
    if not os.path.exists(IMAGE_FILE):
        with open(IMAGE_FILE, 'wb') as test_f:
            test_f.write(b'\xFF\xD8\xFF\xE0' + b'\x00' * 4096 + b'\xFF\xD9')  # 模拟微型 JPG

    send_image(port=PORT_NAME, baudrate=BAUD_RATE, image_path=IMAGE_FILE)

配套说明:接收端核心处理逻辑

为了让该发送端能够正常运作,接收端(无论运行在单片机 C 语言中还是另一台主机的 Python 脚本中)必须遵循相同的状态机进行解包并回复。接收端的工作流程非常直观:

  1. 寻找帧头:在串口接收循环中持续读取字节,直到连续匹配到 0xAA 0x55。
  2. 解析头部:读取接下来的 5 个字节,拆解出 CMD、Seq 和 Len。
  3. 读取载荷:精准读取 Len 指定长度的字节。
  4. 验证校验和:读取 1 字节校验和,与接收端本地对 CMD+Seq+Len+Payload 计算的累加和比对。若一致则发送 0x06 (ACK),否则发送 0x15 (NAK)。
  5. 数据拼装:收到 CMD=0x01 时开辟指定大小的缓冲区或新建文件;收到 CMD=0x02 时将载荷写入;收到 CMD=0x03 时关闭文件保存。

关键工程总结与避坑要点

在实际高波特率或长时间串口传输中,开发者常遇到因软硬件限制带来的稳定性问题。以下四个维度的要点能够帮助避免常见故障:

Python使用pyserial发送图片文件的完整代码示例
图 4:串口图片可靠通信全景避坑总结

实战建议:如果传输的图片是用于彩屏(如 TFT-LCD 或墨水屏)直接展示,可以在 Python 发送前使用 Pillow 库先将图片转换为屏幕原生支持的 RGB565 裸数据或二值单色点阵,不仅能减小图片数据量,还能免除单片机端解码 JPEG/PNG 的巨大计算负担与内存消耗。

相关专题:

本站声明

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

Python 相关产品和应用

全部下载

专题列表