本文详解如何配置 esp32-cam 以 jpeg 格式捕获彩色图像，并通过 websocket 高效传输至 python 客户端，解决原灰度显示问题，实现真彩色、高分辨率图像接收与本地保存。
在嵌入式视觉应用中，ESP32-CAM 常被用作轻量级图像采集终端，但默认配置（如 PIXFORMAT_GRAYSCALE）或客户端解析逻辑不当，极易导致接收到的图像显示为灰度、失真甚至无法解码。本教程基于真实调试经验，系统性地重构了 ESP32-CAM 固件与 Python 客户端，确保端到端支持 标准 JPEG 编码的彩色图像（非原始 RGB/YUV 数据流），兼顾兼容性、效率与易用性。
✅ 关键修改点说明
1. ESP32-CAM 端：启用 JPEG 编码与合理帧尺寸
核心在于 camera_config_t 中的两项配置：
- config.pixel_format = PIXFORMAT_JPEG;
替代 PIXFORMAT_GRAYSCALE，让摄像头硬件直接输出 JPEG 压缩字节流（含完整色彩信息）； - config.frame_size = FRAMESIZE_SVGA;（800×600）或 FRAMESIZE_QVGA（320×240）
同时配合 config.jpeg_quality = 10;（取值 10–63，数值越小压缩越强、体积越小，10 是清晰度与带宽的良好平衡点）。
⚠️ 注意：若使用 PIXFORMAT_RGB565 或 PIXFORMAT_YUV422，需在 Python 端手动解析原始像素并转为 RGB，不仅代码复杂、内存占用高，且易因字节序/步长错误导致花屏；而 JPEG 是自包含的标准化格式，由 libjpeg 底层保障解码鲁棒性。
2. Python 客户端：使用异步 WebSocket + 直接写入二进制文件
原同步 websocket-client 库存在 recv_frame() 接口不适用于 JPEG 流、且未校验数据完整性的问题。新版采用 websockets（异步标准库）：
- await ws.recv() 直接获取完整二进制帧（WebSocket 自动处理分帧与重组）；
- 使用 aiofiles.open(..., 'wb') 安全写入原始字节，避免编码干扰；
- 文件后缀明确为 .jpg，确保后续可用 OpenCV/PIL/系统看图工具直接打开。
import websockets
import asyncio
import aiofiles
async def ws_client():
url = "ws://192.168.1.3:80" # 确保端口与 ESP32 WebSocketsServer 构造一致（此处为 80）
async with websockets.connect(url) as ws:
cmd = input("Enter 'capture' to take photo, or 'exit': ").strip()
if cmd != "capture":
print("Exited.")
return
await ws.send(cmd)
print("Capture command sent.")
# 接收 JPEG 二进制流（自动拼接完整帧）
jpeg_data = await ws.recv()
if isinstance(jpeg_data, bytes) and len(jpeg_data) > 1024: # 粗略校验：JPEG 文件头为 b'\xff\xd8', 且长度合理
async with aiofiles.open("received_image.jpg", "wb") as f:
await f.write(jpeg_data)
print(f"✅ JPEG received ({len(jpeg_data)} bytes). Saved as 'received_image.jpg'.")
else:
print("❌ Invalid or empty image data received.")
asyncio.run(ws_client())3. 进阶建议（可选优化）
- 添加超时与重连：在 ws.recv() 外包裹 asyncio.wait_for(..., timeout=10)，防止网络异常卡死；
- 实时预览（非保存）：用 cv2.imdecode(np.frombuffer(jpeg_data, np.uint8), cv2.IMREAD_COLOR) 解码后 cv2.imshow()；
- 多图连续采集：服务端增加计数逻辑，客户端循环发送 capture 并按序命名文件（如 img_001.jpg）；
- 安全加固：ESP32 端验证 payload 长度与内容合法性，避免恶意指令注入。
✅ 验证与排错提示
- 串口监控：上传 ESP32 固件后，观察串口输出是否打印 Image captured. Returning frame buffer data. 及具体字节数（SVGA JPEG 通常为 15–40 KB）；
- 网络连通性：确保 PC 与 ESP32 在同一局域网，ping 192.168.1.3 必须通；
- 端口检查：ESP32 代码中 WebSocketsServer(80) 对应 Python 的 ws://...:80，若改用其他端口（如 81），URL 必须同步更新；
- 防火墙：临时关闭 Windows/macOS 防火墙测试，排除拦截可能。
通过以上配置，您将获得一张标准、可直接查看的彩色 JPEG 图片——无需 Matplotlib 灰度映射，无需手动解析 RGB 通道，真正实现“即采即得”的工业级图像传输体验。
立即学习“Python免费学习笔记（深入）”；
