Python使用pyserial发送图片文件的完整代码示例
本文详解如何使用 Python 的 pyserial 库通过串口发送图片文件,提供完整的发送端与接收端代码示例,深入分析裸字节直发与分包帧协议的差异,并提供可靠传输的最佳工程实践。
在嵌入式开发、单片机屏幕显示或工业设备交互场景中,经常需要通过串行接口向目标终端传输图像。使用 Python 的 pyserial 模块发送图片,本质是以二进制读取图像文件并分发字节流;但由于图片数据体积大且串口底层存在硬件缓冲区限制,直接裸发极易引起缓冲区溢出与字节错乱。本文将先说明核心解决路径,通过方案对比阐述为什么必须使用分块帧协议,再给出包含握手、分片校验与 ACK 确认的完整 Python 代码实现。
方案选择:裸字节直发与分包帧协议的关键差异
通过串口发送图片通常有两种技术路径。明确这两种方式的机制差异与适用边界,是写出稳定代码的前提。
如对比图所示,单纯调用 ser.write(image_bytes) 只能在波特率极低、图片极小且接收端主频极高的理想状态下勉强工作。实际工程中,单片机(如 STM32、ESP32 或 Arduino)内部的 UART 接收缓冲区通常仅为 64 至 256 字节。一旦 Python 端全速写入数万字节,接收端处理速度赶不上硬件中断,就会发生溢出丢失,还原后的图片将严重花屏或无法解析。因此,构建一个轻量的“分包与确认机制”是解决该问题的必要手段。
通信协议设计:轻量级数据帧结构
为了保证传输可控,我们定义一个简洁而健壮的数据帧格式。整个传输过程分为三个阶段:元数据握手(声明图片大小与总包数)、数据包传输(按固定大小切片传输)和传输结束确认。
通过这套帧格式,我们不仅能准确传递图片内容,还能在串口收到噪声杂波时迅速重同步。每次发送完一个数据帧,发送端等待接收端返回一个单字节响应(0x06 表示 ACK 成功,0x15 表示 NAK 校验失败重试)。
整体操作与执行流程
在编写代码前,梳理完整的程序执行流。整个发送过程由五个标准操作步骤构成:
环境准备
运行示例前,需要安装 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 脚本中)必须遵循相同的状态机进行解包并回复。接收端的工作流程非常直观:
- 寻找帧头:在串口接收循环中持续读取字节,直到连续匹配到
0xAA 0x55。 - 解析头部:读取接下来的 5 个字节,拆解出
CMD、Seq和Len。 - 读取载荷:精准读取
Len指定长度的字节。 - 验证校验和:读取 1 字节校验和,与接收端本地对
CMD+Seq+Len+Payload计算的累加和比对。若一致则发送0x06 (ACK),否则发送0x15 (NAK)。 - 数据拼装:收到
CMD=0x01时开辟指定大小的缓冲区或新建文件;收到CMD=0x02时将载荷写入;收到CMD=0x03时关闭文件保存。
关键工程总结与避坑要点
在实际高波特率或长时间串口传输中,开发者常遇到因软硬件限制带来的稳定性问题。以下四个维度的要点能够帮助避免常见故障:
实战建议:如果传输的图片是用于彩屏(如 TFT-LCD 或墨水屏)直接展示,可以在 Python 发送前使用 Pillow 库先将图片转换为屏幕原生支持的 RGB565 裸数据或二值单色点阵,不仅能减小图片数据量,还能免除单片机端解码 JPEG/PNG 的巨大计算负担与内存消耗。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









