USB摄像头¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
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 两种格式的图片输出。
功能使用¶
前提条件¶
连接 HDMI 屏幕。
在 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 作为显示后端，并把窗口设置为 全屏（无标题栏、铺满屏幕）。
视频录制与播放¶
视频录制¶
在 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 显示器等待数据流，从而提高显示性能。
gst 管道状态更改为 “PLAYING”，则表示摄像头正在运行。
录制结束时，按"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 显示器上，并设置为全屏模式，同时禁用最后一帧显示。
拍照¶
在 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 张，旧文件被自动删除。
按下"Ctrl" + “C”，自动保存最后5张图片。
要查看照片，请在 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 合成器全屏显示。
退出查看，请按下"Ctrl" + “C”。