10 UVC 网络摄像头应用

本章节介绍 GK7206 的 UVC（USB Video Class）网络摄像头应用示例 —— uvc_app。该应用演示了如何将开发板作为 USB 摄像头呈现给主机，使主机可以通过 USB 接口访问摄像头的视频流。

应用源码位于 SDK 目录 sample/uvc_app/，是开发 USB 摄像头相关应用的参考模板。

1 应用概述

1.1 功能特性

  • USB 摄像头模式：将开发板作为 USB 摄像头呈现给主机
  • 视频流推送：通过 USB 接口推送 MJPEG 视频流
  • Plug-and-Play：主机可自动识别并加载驱动
  • 跨平台支持：Windows、Linux、macOS 均可使用

1.2 技术参数

参数值
USB 接口USB 2.0 Device
视频格式MJPEG
分辨率640×480、320×240 等
帧率30 FPS
依赖USB 接主机；Sensor

1.3 目录结构

sample/uvc_app/
├── Makefile              # 构建脚本
├── ConfigUVC.sh          # UVC 配置脚本
├── application.c        # 主程序
└── uvc_gadget.c         # UVC gadget 实现

2 编译与部署

2.1 前置条件

在编译本应用之前，请确保已完成以下准备工作：

  1. SDK 环境已搭建：参照 SDK 编译 完成交叉编译工具链和 SDK 配置
  2. USB 接口准备：需 USB 数据线连接到主机
  3. Sensor 已连接：需连接 SC465SL 或兼容的图像传感器

2.2 编译应用

# 进入 sample 目录
cd <SDK_PATH>/sample

# 编译 uvc_app 示例
make -C uvc_app clean && make -C uvc_app

2.3 部署到板端

# 使用 SCP 传输到开发板
scp sample/uvc_app/application root@<板端IP>:/sd_card/
scp sample/uvc_app/ConfigUVC.sh root@<板端IP>:/sd_card/

2.4 运行应用

# 添加执行权限
chmod +x /sd_card/application
chmod +x /sd_card/ConfigUVC.sh

# 进入 SD 卡目录
cd /sd_card

# 配置 UVC gadget
sh ConfigUVC.sh

# 运行应用
./application

# 或指定日志级别
./application 1

2.5 主机端使用

Windows

  1. 连接 USB 后，设备管理器会识别出新的摄像头设备
  2. 打开「相机」应用或第三方软件（如 OBS、AmCap）
  3. 选择对应的 USB 摄像头

Linux

# 使用 guvcview 查看摄像头
guvcview /dev/video0

# 或使用 ffmpeg
ffmpeg -f v4l2 -i /dev/video0 -f sdl output

2.6 预期输出

成功运行后，终端会输出类似以下信息：

uvc application running
configfs gadget setup complete
USB gadget connected
streaming started...

主机端可以看到摄像头的实时画面。

3 内部执行逻辑详解

3.1 应用架构

本应用采用以下架构：

Sensor → VI → VPSS → VENC(MJPEG) → USB Gadget → 主机

3.2 UVC 初始化流程

// 步骤 1：配置 USB gadget
system("sh ConfigUVC.sh");

// 步骤 2：初始化视频管线
sample_comm_sys_init(&sys_config);
sample_comm_isp_init();
sample_comm_vi_start(...);
sample_comm_vpss_start(...);
sample_comm_venc_start(...);

// 步骤 3：初始化 UVC gadget
uvc_gadget_init();

// 步骤 4：启动视频流推送
uvc_gadget_start_streaming();

// 步骤 5：循环推送帧
while (running) {
    xmedia_venc_get_stream(venc_chn, &stream, -1);
    uvc_gadget_send_frame(&stream);
    xmedia_venc_release_stream(venc_chn, &stream);
}

// 步骤 6：清理资源
uvc_gadget_stop_streaming();
uvc_gadget_exit();
sample_comm_venc_stop(...);

3.3 USB Gadget 配置

ConfigUVC.sh 脚本配置 USB gadget：

#!/bin/sh

# 加载 USB gadget 驱动
modprobe libcomposite

# 配置 configfs
cd /sys/kernel/config/usb_gadget
mkdir g1
cd g1

# 配置设备信息
echo 0x1d6b > idVendor
echo 0x0104 > idProduct
echo "GK7206 UVC" > product

# 创建配置
mkdir configs/c.1
cd configs/c.1
echo 250 > MaxPower

# 创建 UVC 函数
cd ../../
mkdir functions/uvc.usb0
cd functions/uvc.usb0

# 链接配置到函数
ln -s configs/c.1 functions/uvc.usb0

# 启用 gadget
echo "$(ls /sys/class/udc)" > UDC

4 关键编程要点

4.1 MJPEG 编码配置

xmedia_venc_chn_attr_t venc_chn_attr;

venc_chn_attr.type = XMEDIA_PT_MJPEG;
venc_chn_attr.max_width = 640;
venc_chn_attr.max_height = 480;
venc_chn_attr.rc_mode = VENC_RC_MODE_MJPEGCBR;

xmedia_venc_create_chn(venc_chn, &venc_chn_attr);

4.2 USB 帧发送

// 从 VENC 获取帧
xmedia_venc_get_stream(venc_chn, &stream, -1);

// 通过 USB 发送帧
uvc_gadget_send_frame(stream.pack[0].vir_addr, stream.pack[0].len);

// 释放帧
xmedia_venc_release_stream(venc_chn, &stream);

5 常见问题排查

问题可能原因解决方案
主机无法识别 USB 设备USB gadget 配置失败检查 ConfigUVC.sh 是否正确执行
主机识别但无视频流视频管线初始化失败检查 Sensor 连接和 VI/VPSS/VENC 配置
视频流卡顿USB 带宽不足降低分辨率或帧率
视频颜色异常MJPEG 编码参数错误检查 VENC 编码配置

6 参考链接