📚 课程目录第4章摄像头初始化调试

4、摄像头初始化调试：设备节点检测、分辨率与格式设置、帧率配置实战

摄像头驱动写完了，板子也连上了。接下来干嘛？

说白了，就是让摄像头真正“动起来”。

这一步我称之为初始化调试。很多新手容易跳过，直接去调图像质量。结果发现图像出不来，或者帧率不对，回头再查驱动，浪费大量时间。

我个人习惯，初始化阶段必须稳扎稳打。设备节点、分辨率、格式、帧率，一个一个确认。今天我就把这套流程拆开，跟你聊聊实战中的那些坑。

4.1 设备节点检测：确认摄像头“活着”

摄像头在 Linux 下通常以 V4L2 设备节点出现，路径一般是 /dev/videoX。但你怎么知道哪个节点是你的摄像头？

我的习惯：先插上摄像头，执行 ls /dev/video*，看看节点数量变化。多出来的那个，大概率就是。

但光看数量不够。我遇到过摄像头被识别成 /dev/video0，但其实是板载 ISP 的情况。这时候需要用工具确认。

# 查看设备能力
v4l2-ctl -d /dev/video0 --all

# 或者用 media-ctl 查看拓扑
media-ctl -p -d /dev/media0

输出里会包含驱动名称、设备型号、支持的格式等信息。如果看到你的传感器型号，那就对了。

注意：有些 SoC 会把摄像头和 ISP 绑定成多个节点。比如 /dev/video0 是 raw 输出，/dev/video1 是处理后的 YUV。我曾经在这上面栽过跟头，一直对着 raw 节点调格式，调了半天没反应。

确认节点后，我习惯写个小脚本，自动检测并打印节点信息。省得每次手动敲命令。

#!/bin/bash
for dev in /dev/video*; do
    echo "=== $dev ==="
    v4l2-ctl -d $dev --all 2>/dev/null | grep -E "Driver|Model|Format"
done

4.2 分辨率与格式设置：别被“支持列表”骗了

设备节点确认了，下一步就是设置分辨率和像素格式。

V4L2 里用 VIDIOC_S_FMT 来设置。但有个坑：你设置的分辨率，驱动不一定真的支持。

  核心逻辑：先查询（VIDIOC_ENUM_FRAMESIZES），再设置（VIDIOC_S_FMT），最后确认（VIDIOC_G_FMT）。

我见过不少工程师直接写死 1920x1080，结果驱动默默给你切到 1280x720，还不报错。图像出来是黑的，查了半天。

正确的做法是这样的：

struct v4l2_format fmt;
memset(&fmt, 0, sizeof(fmt));
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
fmt.fmt.pix.width = 1920;
fmt.fmt.pix.height = 1080;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;

// 设置格式
if (ioctl(fd, VIDIOC_S_FMT, &fmt) < 0) {
    perror("VIDIOC_S_FMT");
    return -1;
}

// 读取实际设置的值
printf("实际分辨率: %dx%d\n", fmt.fmt.pix.width, fmt.fmt.pix.height);
printf("实际格式: %c%c%c%c\n",
       (fmt.fmt.pix.pixelformat >> 0) & 0xFF,
       (fmt.fmt.pix.pixelformat >> 8) & 0xFF,
       (fmt.fmt.pix.pixelformat >> 16) & 0xFF,
       (fmt.fmt.pix.pixelformat >> 24) & 0xFF);

你想想看，如果实际分辨率和设置的不一样，说明驱动做了妥协。这时候要么换一个支持的分辨率，要么改驱动。

像素格式	描述	常见场景
V4L2_PIX_FMT_YUYV	YUV 4:2:2 打包格式	USB 摄像头、部分 MIPI 模组
V4L2_PIX_FMT_MJPEG	MJPEG 压缩格式	高分辨率 USB 摄像头
V4L2_PIX_FMT_SBGGR10	Bayer RAW 10bit	工业相机、ISP 前处理
V4L2_PIX_FMT_NV12	YUV 4:2:0 平面格式	视频编码、显示

避坑指南：我曾经遇到一个模组，手册上写支持 1080p，但实际驱动只支持到 720p。后来查了 datasheet 才发现，1080p 需要额外的时钟配置。所以，不要完全相信手册，以驱动实际返回为准。

4.3 帧率配置：别让摄像头“跑太快”

帧率配置是初始化里最容易出问题的一环。

V4L2 用 VIDIOC_S_PARM 来设置帧率。但很多驱动对帧率的支持是“尽力而为”的。你设置 30fps，它可能只跑到 25fps。

struct v4l2_streamparm parm;
memset(&parm, 0, sizeof(parm));
parm.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
parm.parm.capture.timeperframe.numerator = 1;
parm.parm.capture.timeperframe.denominator = 30; // 目标 30fps

if (ioctl(fd, VIDIOC_S_PARM, &parm) < 0) {
    perror("VIDIOC_S_PARM");
}

// 读取实际帧率
printf("实际帧率: %d/%d fps\n",
       parm.parm.capture.timeperframe.denominator,
       parm.parm.capture.timeperframe.numerator);

这里有个细节：timeperframe 是每帧时间，单位是秒。所以 numerator=1, denominator=30 就是 1/30 秒，即 30fps。

注意：帧率受分辨率、总线带宽、ISP 处理能力影响。比如 MIPI CSI-2 接口，2-lane 和 4-lane 的带宽差一倍。我曾经在 2-lane 上硬跑 1080p@60fps，结果图像全是撕裂。

怎么确认实际帧率？我一般用两种方法：

应用层统计：在采集循环里记录时间戳，计算每秒帧数。
驱动层调试：在驱动里加计数器，打印 VSYNC 中断次数。

我个人更推荐第二种，因为它能排除应用层 buffering 的影响。

4.4 实战流程：从节点到帧率，一步不落

好了，知识点讲完了。我把整个初始化流程画成一张图，方便你对照。

这张图里，每一步都对应一个 ioctl 调用。我建议你按这个顺序写初始化代码，不要跳步。

4.5 常见问题与排查思路

初始化阶段的问题，其实就那么几类。我列个表，你遇到问题可以对照着查。

现象	可能原因	排查方法
打开设备失败	节点不存在、权限不足	检查 `/dev/video*`，用 `sudo` 运行
设置格式失败	分辨率不支持、格式不匹配	先枚举支持列表，再设置
帧率达不到目标	带宽不足、时钟配置错误	降低分辨率，检查 MIPI lane 配置
图像全黑或花屏	格式设置错误、时钟未稳定	确认 pixel format，检查 PLL 锁定状态
ioctl 返回 EINVAL	参数无效、驱动不支持	检查驱动源码，确认支持哪些参数

  我的经验：初始化调试最怕“静默失败”。驱动不报错，但参数被悄悄改了。所以每次设置完，一定要读回来确认。这个习惯帮我省了至少一半的调试时间。

嗯，初始化这块就聊这么多。你按照这个流程走一遍，设备节点、分辨率、格式、帧率，一个一个确认。基础打牢了，后面的图像质量调优才能事半功倍。