USB摄像头

2026-02-28

Quectel Pi H1智能主控板支持USB接口摄像头，本文以微雪OV5693 5MP USB摄像头为例，介绍连接及功能使用方法。

硬件接口

将USB摄像头的连接线插入Quectel Pi H1的USB Type-A接口。

硬件连接位置示意图：

查看设备信息

查看USB设备识别信息

在SSH终端中运行以下命令，可查看系统识别到的USB设备信息：

dmesg | grep usb

输出示例：

查看节点信息

在SSH终端中运行以下命令，可查看新增设备节点：

v4l2-ctl --list-devices

输出示例：

  • /dev/video2 —— 主视频节点（后续gst命令主要操作此节点）。

  • /dev/video3 —— 元数据节点。

  • /dev/media3 —— 硬件拓扑控制器，控制整个pipeline。

查看支持的格式

在SSH终端中运行以下命令，可查看video节点支持的格式：

v4l2-ctl --list-formats-ext --device /dev/video2

输出示例：

  • 由上图示例可知，该摄像头支持MJPG和YUYV两种格式的图片输出。

功能使用

前提条件

  1. 连接HDMI屏幕。
  2. 在SSH终端中运行以下命令：
mount -o rw,remount /
export XDG_RUNTIME_DIR=/dev/socket/weston
export WAYLAND_DISPLAY=wayland-1

实时预览

在设备终端执行以下命令启动预览（根据支持格式选择其一）：

# MJPG格式，分辨率和帧率需和video节点支持的格式对应
gst-launch-1.0 v4l2src device=/dev/video2 ! image/jpeg,width=1280,height=720,framerate=30/1 ! jpegdec ! videoconvert ! waylandsink fullscreen=true

# YUV格式，分辨率和帧率需和video节点支持的格式对应
gst-launch-1.0 v4l2src device=/dev/video2 ! video/x-raw,format=YUY2,width=1280,height=720,framerate=10/1 ! videoconvert ! waylandsink fullscreen=true

命令详细说明：

  • gst-launch-1.0 -e：启动管线；-e保证按"Ctrl" + "C"停止时能正确收尾（EOS）。
  • v4l2src device=/dev/video2：从V4L2设备 /dev/video2 节点采集数据。
  • image/jpeg,width=1280,height=720,framerate=30/1：要求摄像头输出1280×720@30 fps的MJPEG；若摄像头不支持，pipeline会直接报错。
  • jpegdec：将MJPEG帧解码成原始YUV/RGB像素数据。
  • videoconvert：把像素格式转成waylandsink能接受的格式（通常是NV12/BGRx）。
  • waylandsink fullscreen=true：用Wayland作为显示后端，并把窗口设置为全屏（无标题栏、铺满屏幕）。

视频录制与播放

视频录制

  1. 在device终端中运行以下命令启动录制：
gst-launch-1.0 -e v4l2src device=/dev/video2 io-mode=2 ! \
  image/jpeg,width=1280,height=720,framerate=30/1 ! \
  jpegdec ! videoconvert ! tee name=t \
  t. ! queue ! v4l2h264enc ! h264parse ! mp4mux ! filesink location=/opt/out.mp4 \
  t. ! queue ! videoconvert ! waylandsink  fullscreen=true sync=false

命令详细说明：

  • v4l2src device=/dev/video2 io-mode=2：

从 /dev/video2 设备捕获视频流，io-mode=2表示使用内存映射（mmap）模式，提高性能。

  • image/jpeg,width=1280,height=720,framerate=30/1：

指定捕获的视频流格式为MJPEG，分辨率为1280×720，帧率为30fps。

  • jpegdec：

解码MJPEG格式的视频流，将其转换为原始的RGB/YUV格式。

  • videoconvert：

将解码后的视频格式转换为适合后续处理的格式（例如，从YUV转换为RGBA）。

  • tee name=t：

将一路视频流分成两路，后续可以通过t.引用这两路流。

  • t. ! queue：

从tee元素中取出一路流，并通过queue元素进行缓冲。

  • v4l2h264enc：

将视频流编码为H.264格式。

  • h264parse：

解析H.264编码的视频流，使其符合MP4文件格式的要求。

  • mp4mux：

将H.264视频流封装为MP4文件格式。

  • filesink location=/opt/out.mp4：

将封装好的MP4文件保存到 /opt/out.mp4。

  • t. ! queue：

从tee元素中取出另一路流，并通过queue元素进行缓冲。

  • videoconvert：

将视频格式转换为适合Wayland显示器显示的格式。

  • waylandsink fullscreen=true sync=false：

将视频流输出到Wayland显示器，以全屏模式显示视频，禁用同步模式，避免Wayland显示器等待数据流，从而提高显示性能。

  1. gst管道状态更改为 “PLAYING”，则表示摄像头正在运行。
  2. 录制结束时，按"Ctrl" + "C"停止录制。

视频播放

播放视频文件，请在device终端中运行以下命令：

gst-launch-1.0 -e filesrc location=/opt/out.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=5 output-io-mode=5 !  videocrop top=0 bottom=40 left=0 right=0 ! videoconvert ! waylandsink  fullscreen=true enable-last-sample=false

命令详细说明：

  • filesrc location=/opt/out.mp4：

从 /opt/out.mp4文件读取数据。

  • qtdemux：

将MP4文件中的视频和音频流分离出来。

  • queue：

缓冲数据，避免处理过程中的数据丢失。

  • h264parse：

解析视频流中的H.264编码数据。

  • v4l2h264dec capture-io-mode=5 output-io-mode=5：

使用V4L2解码器解码H.264视频流，capture-io-mode=5和output-io-mode=5是硬件加速相关的参数。

  • videocrop top=0 bottom=40 left=0 right=0：

由于视频流自动对齐，填充额外的像素信息，导致视频底部有绿边，因此裁剪底部40像素。

  • videoconvert：

格式转换元素，确保裁剪后的视频流格式适合Wayland显示器。

  • waylandsink fullscreen=true enable-last-sample=false：

将解码后的视频输出到Wayland显示器上，并设置为全屏模式，同时禁用最后一帧显示。

拍照

  1. 在device终端中运行以下命令启动拍照：
gst-launch-1.0 -e v4l2src device=/dev/video2 io-mode=2 ! \
  image/jpeg,width=1280,height=720,framerate=30/1 ! \
  tee name=t \
  t. ! queue ! jpegdec ! videoconvert ! waylandsink sync=false \
  t. ! queue ! multifilesink location=/opt/shot-%05d.jpg max-files=5

命令详细说明：

  • v4l2src device=/dev/video2 io-mode=2：

从USB摄像头采集MJPEG数据。

  • image/jpeg,width=1280,height=720,framerate=30/1：

要求摄像头输出1280×720@30 fps的MJPEG流。

  • tee name=t：

把同一路流一分为多，后面用t.引用。

  • t. ! queue ! jpegdec ! videoconvert ! waylandsink sync=false：

预览分支：解码MJPEG → 转成RGB → 送到Wayland窗口实时显示。sync=false可减少延迟。

  • t. ! queue ! multifilesink location=shot-%05d.jpg max-files=5：

拍照分支：每一帧原封不动保存为JPG，文件名自动编号 %05d（5位数字）。max-files=5只保留最近5张，旧文件被自动删除。

  1. 按下"Ctrl" + "C"，自动保存最后5张图片。

  2. 要查看照片，请在device终端中输入以下命令：

gst-launch-1.0 filesrc location=/opt/shot-00036.jpg ! jpegdec ! imagefreeze ! waylandsink fullscreen=true

命令详细说明：

  • filesrc location=/opt/shot-00036.jpg：

从文件系统读取 /opt/shot-00036.jpg。

  • jpegdec：

把JPEG压缩数据解码成原始RGB/YUV像素帧。

  • imagefreeze：

只保留第一帧，后续不断重复这一帧 → 实现“静止图片”效果。

  • waylandsink fullscreen=true：

把图像送到Wayland合成器全屏显示。

  1. 退出查看，请按下"Ctrl" + "C"。