# 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** 接口。

硬件连接位置示意图：

```{image} images/image_RektbNpLUoa2fkx1X37cp8sCnLg.webp
:width: 617px
:height: 323px
```

# 查看设备信息

## 查看USB设备识别信息

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

```shell
dmesg | grep usb
```

输出示例：

```{image} images/image_LxJqbX8YgotZhzxgC4pcpaErnwc.webp
:width: 877px
:height: 619px
```

## 查看节点信息

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

```shell
v4l2-ctl --list-devices
```

输出示例：

```{image} images/image_SfvpbAPzJo3svbxTOUscxGETnzd.webp
:width: 876px
:height: 273px
```

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

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

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

## 查看支持的格式

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

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

输出示例：

```{image} images/image_PDfqbUNuMo7voNxwDflcru0lnbg.webp
:width: 876px
:height: 588px
```

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

# 功能使用

## 前提条件

1. 连接 **HDMI** 屏幕。

2. 在 **SSH** 终端中运行以下命令：

```shell
mount -o rw,remount /
export XDG_RUNTIME_DIR=/dev/socket/weston
export WAYLAND_DISPLAY=wayland-1
```

## 实时预览

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

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

```shell
# 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** 终端中运行以下命令启动录制：

```shell
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** 显示器等待数据流，从而提高显示性能。

2. **gst** 管道状态更改为 **“PLAYING”**，则表示摄像头正在运行。

3. 录制结束时，按"**Ctrl**" + "**C**"停止录制。

### 视频播放

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

```shell
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** 终端中运行以下命令启动拍照：

```shell
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** 张，旧文件被自动删除。

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

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

```shell
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** 合成器全屏显示。

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