v4l2-ctl 完整详解（RDK X5 / Linux V4L2 USB 相机专用）

v4l2-ctl 是 v4l-utils 工具集里的命令行控制程序，直接和内核 V4L2 子系统交互，优先级高于 OpenCV 设置，是嵌入式调试摄像头的标准工具。

一、安装

bash

运行

sudo apt update
sudo apt install v4l-utils

通用调用格式：

bash

运行

v4l2-ctl -d /dev/videoX [参数]
# -d 指定设备，不指定默认使用 /dev/video0

二、信息查询类命令（最常用）

1. 查看设备基础信息

bash

运行

v4l2-ctl -d /dev/video0 --info

输出内容：驱动名称（uvcvideo）、总线地址、设备能力、采集能力。 用来确认是不是 UVC USB 摄像头。

2. 查询支持分辨率、图像格式、帧率【重中之重】

bash

运行

v4l2-ctl -d /dev/video0 --list-formats-ext

列出相机支持 MJPG / YUYV 以及每种格式下所有分辨率、支持帧率。

OpenCV 无法枚举支持规格，只能依靠本条命令。

3. 查询当前正在生效的图像格式

bash

运行

v4l2-ctl -d /dev/video0 --get-fmt-video

输出：宽高、像素格式 (MJPG/YUYV)、色彩空间。

4. 查询帧率配置

bash

运行

v4l2-ctl -d /dev/video0 --get-parm-video

5. 列出所有可调图像控制参数（曝光、亮度、白平衡等）

bash

运行

v4l2-ctl -d /dev/video0 --list-ctrls

展示每个参数：最大 / 最小值、步长、默认值、当前值。

6. 读取单个控制参数

bash

运行

v4l2-ctl -d /dev/video0 --get-ctrl brightness

三、参数设置类命令

⚠️重要前提：相机不能被 OpenCV/Python 程序占用，占用时设置不生效！

1. 设置分辨率 + 像素格式

bash

运行

# 1080P MJPG
v4l2-ctl -d /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=MJPG
# 720P YUYV
v4l2-ctl -d /dev/video0 --set-fmt-video=width=1280,height=720,pixelformat=YUYV

2. 设置帧率

bash

运行

v4l2-ctl -d /dev/video0 --set-parm=30

3. 图像画质参数设置通用模板

bash

运行

# 亮度
v4l2-ctl --set-ctrl brightness=5
# 对比度
v4l2-ctl --set-ctrl contrast=35
# 饱和度
v4l2-ctl --set-ctrl saturation=60

4. 曝光控制（工业高频使用）

bash

运行

# 0=手动曝光模式
v4l2-ctl --set-ctrl auto_exposure=0
# 设置曝光时长
v4l2-ctl --set-ctrl exposure=400

# 恢复自动曝光
v4l2-ctl --set-ctrl auto_exposure=3

5. 白平衡控制

bash

运行

# 关闭自动白平衡
v4l2-ctl --set-ctrl white_balance_automatic=0
# 开启自动白平衡
v4l2-ctl --set-ctrl white_balance_automatic=1

四、图像抓取测试（快速验证相机是否正常出图）

bash

运行

# 抓取一帧保存raw数据
v4l2-ctl -d /dev/video0 --stream-mmap --stream-to=frame.raw --stream-count=1

五、关键原理与开发注意事项

1. 生效优先级 v4l2-ctl（内核层直接配置） > OpenCV cap.set() 推荐流程：启动采集程序前，shell 脚本先用 v4l2-ctl 固化相机参数。

2. 参数生命周期 USB 摄像头重新插拔、断电后，所有设置全部丢失。 解决方案：开机启动脚本自动执行 v4l2-ctl 配置。

3. /dev/videoN 区分 UVC 摄像头生成两个设备： video0 视频采集通道 | video1 metadata 通道，不要使用 video1 采集图像。

4. OpenCV 常见坑 Linux 下cap.set()对曝光、白平衡几乎无效；图像画质调节统一交给 v4l2-ctl。

六、RDK 工程启动脚本示例参考

bash

运行

#!/bin/bash
DEV=/dev/video0
v4l2-ctl -d $DEV --set-fmt-video=width=1280,height=720,pixelformat=MJPG
v4l2-ctl -d $DEV --set-ctrl auto_exposure=0
v4l2-ctl -d $DEV --set-ctrl exposure=350
# 随后启动python采集程序
python3 camera_demo.py