相机软件（十）

Unicam

Raspberry Pi SoC 都有两个摄像头接口，支持 CSI-2 D-PHY 1.1 或紧凑型摄像头端口 2 （CCP2） 源。此接口的代号为 Unicam。Unicam 的第一个实例支持两个 CSI-2 数据通道，而第二个实例支持四个。每个通道可以以高达 1Gbit/s （DDR） 的速度运行，因此最大链路频率为 500MHz。
计算模块和 Raspberry Pi 5 从两个外围设备路由出所有通道。Raspberry Pi 5 之前的其他型号仅公开第二个实例，仅将两个数据通道路由到相机连接器。

软件接口

V4L2 软件接口是与 Unicam 外设通信的唯一方式。曾经也有固件和 MMAL rawcam 组件接口，但现在不再支持这些接口。

V4L2型

注意：Unicam 的 V4L2 接口仅在使用 libcamera 时可用。
有一个完全开源的内核驱动程序可用于 Unicam 块;此内核模块称为 BCM2835-Unicam，可与 V4L2 子设备驱动程序连接以提供原始帧。此 bcm2835-unicam 驱动程序控制传感器并配置摄像头串行接口 2 （CSI-2） 接收器。外设将原始帧（在Debayer之后）写入SDRAM，用于V4L2，以交付给应用程序。捕获图像的相机传感器和将图像数据放入 SDRAM 的 bcm2835-unicam 驱动程序之间没有图像处理，但拜耳解包为 16 位/像素。

|------------------------|
|     bcm2835-unicam     |
|------------------------|
     ^             |
     |      |-------------|
 img |      |  Subdevice  |
     |      |-------------|
     v   -SW/HW-   |
|---------|   |-----------|
| Unicam  |   | I2C or SPI|
|---------|   |-----------|
csi2/ ^             |
ccp2  |             |
    |-----------------|
    |     sensor      |
    |-----------------|

主线 Linux 包含一系列现有驱动程序。Raspberry Pi 内核树有一些额外的驱动程序和设备树覆盖来配置它们：

由于子设备驱动程序也是具有标准化 API 的内核驱动程序，因此第三方可以自由地为他们选择的任何源编写自己的驱动程序。

编写第三方驱动程序

这是通过 Unicam 进行接口的推荐方法。
为要与bcm2835-unicam 模块一起使用的新设备开发驱动程序时，需要驱动程序和相应的设备树覆盖。理想情况下，驱动程序应该提交到 linux-media 邮件列表进行代码审查并合并到主线中，然后移动到 Raspberry Pi 内核树上;但可能会有例外情况，以便将驱动程序审查并直接合并到 Raspberry Pi 内核。
注意：所有内核驱动程序都是在 GPLv2 许可证下授权的，因此源代码必须可用。仅发布二进制模块违反了 Linux 内核许可所依据的 GPLv2 许可证。
编写 bcm2835-unicam 模块是为了尝试适应当前在主线 Linux 内核中找到的所有类型的 CSI-2 源驱动程序。这些可以大致分为相机传感器和桥接芯片。桥接芯片允许在一些其他格式和 CSI-2 之间进行转换。

相机传感器

相机传感器的传感器驱动程序负责器件的所有配置，通常通过 I2C 或 SPI。与从头开始编写驱动程序相比，将现有驱动程序作为基础并根据需要对其进行修改通常更容易。
IMX219 驱动程序是一个很好的起点。此驱动程序支持 8 位和 10 位拜耳读出，因此枚举帧格式和帧大小稍微复杂一些。
传感器通常支持 V4L2 用户控制。并非所有这些控件都需要在驱动程序中实现。IMX219 驱动程序仅实现下面列出的一小部分子集，其实现由 imx219_set_ctrl 函数处理。

• V4L2_CID_PIXEL_RATE / V4L2_CID_VBLANK / V4L2_CID_HBLANK：允许应用程序设置帧速率

• V4L2_CID_EXPOSURE：以行为单位设置曝光时间;应用程序需要使用V4L2_CID_PIXEL_RATE、V4L2_CID_HBLANK和帧宽来计算行时间

• V4L2_CID_ANALOGUE_GAIN：以传感器特定单位表示的模拟增益

• V4L2_CID_DIGITAL_GAIN：传感器特定单元的可选数字增益

• V4L2_CID_HFLIP / V4L2_CID_VFLIP：水平或垂直翻转图像;此操作可能会更改帧中数据的拜耳顺序，就像 IMX219 上的情况一样。

• V4L2_CID_TEST_PATTERN / V4L2_CID_TEST_PATTERN_*：能够从传感器输出各种测试模式;可用于调试

在 IMX219 的情况下，其中许多控件直接映射到传感器本身的寄存器写入。
可以在 libcamera 传感器驱动程序要求和 Raspberry Pi 相机调整指南的第 3 章中找到更多指导。

设备树

设备树用于选择传感器驱动器并配置CSI-2通道数、连续时钟通道操作和链路频率（通常只支持一个）等参数。
GitHub 上提供了 6.1 内核的 IMX219 设备树覆盖。

桥接芯片

这些设备将传入的视频流（例如 HDMI 或复合）转换为 Raspberry Pi CSI-2 接收器可以接受的 CSI-2 流。
桥式芯片的处理更加复杂。与相机传感器不同，它们必须响应输入信号并将其报告给应用程序。
桥接芯片的处理机制可分为两类：模拟或数字。
在以下各节中使用 ioctls 时，ioctl 名称中的 S 表示它是一个集合函数，而 G 是一个 get 函数，ENUM 枚举一组允许的值。

模拟视频源

模拟视频源使用标准 ioctls 来检测和设置视频标准。提供VIDIOC_G_STD、VIDIOC_S_STD、VIDIOC_ENUMSTD和VIDIOC_QUERYSTD。
选择错误的标准通常会导致图像损坏。设置标准通常还会设置 V4L2 CAPTURE 队列的分辨率。它不能通过VIDIOC_S_FMT设置。通常，通过 VIDIOC_QUERYSTD 请求检测到的标准，然后在流式传输之前使用 VIDIOC_S_STD 设置它是一个好主意。

数字视频源

对于数字视频源（如 HDMI），有一组备用调用，允许指定所有数字定时参数：VIDIOC_G_DV_TIMINGS、VIDIOC_S_DV_TIMINGS、VIDIOC_ENUM_DV_TIMINGS 和 VIDIOC_QUERY_DV_TIMINGS。
与模拟网桥一样，时序通常固定 V4L2 CAPTURE 队列分辨率，并且在流式传输之前调用VIDIOC_S_DV_TIMINGS并得到VIDIOC_QUERY_DV_TIMINGS结果，应确保格式正确。
根据桥接芯片和驱动程序的不同，输入源的更改可能会通过VIDIOC_SUBSCRIBE_EVENT和V4L2_EVENT_SOURCE_CHANGE报告给应用程序。

当前支持的设备

Raspberry Pi Linux 内核目前支持两种桥接芯片：用于模拟视频源的 Analog Devices ADV728x-M 和用于 HDMI 源的 Toshiba TC358743。
ADI公司的ADV728x（A）-M模拟视频转CSI2桥接芯片将复合S视频（Y/C）或分量（YPrPb）视频转换为单通道CSI-2接口，并受ADV7180内核驱动程序支持。
有关该芯片各种版本的产品详细信息，请访问ADI公司网站：ADV7280A、ADV7281A和ADV7282A。
由于当前核心 V4L2 实现中缺少一些代码，选择源失败，因此 Raspberry Pi 内核版本在ADV7180内核驱动程序中添加了一个名为 dbg_input 的内核模块参数，该参数在每次调用VIDIOC_S_STD时设置输入源。在某个时候，主流将修复根本问题（内核 API 调用s_routing和用户空间调用VIDIOC_S_INPUT之间的分离），并且此修改将被删除。
不支持接收隔行扫描视频，因此该芯片的 ADV7281（A）-M 版本用途有限，因为它没有必要的 I2P 去隔行扫描块。此外，请确保在选择设备时指定 -M 选项。否则，您将获得无法连接到 Raspberry Pi 的并行输出总线。
目前尚无已知的商用电路板使用这些芯片，但该驱动器已通过ADI公司的EVAL-ADV7282-M评估板进行了测试。
如果您使用的是 ADV7282-M 芯片变体，则可以使用 config.txt dtoverlay adv7282m 加载此驱动程序;或 ADV728X-M，参数为 ADV7280M=1、ADV7281M=1 或 ADV7281MA=1（如果您使用的是其他变体）。

dtoverlay=adv728x-m,adv7280m=1

东芝 TC358743 是一款 HDMI 转 CSI-2 桥接芯片，能够转换高达 1080p60 的视频数据。
有关此桥接芯片的信息可在东芝网站上找到 web网站。
该TC358743将 HDMI 连接到 CSI-2 和 I2S 输出。它由 TC358743 内核模块支持。
该芯片支持 RGB888、YUV444 或 YUV422 等输入的 HDMI 信号，最高可达 1080p60。它可以转发 RGB888，或将其转换为 YUV444 或 YUV422，并在 YUV444 和 YUV422 之间进行任一转换。仅测试了 RGB888 和 YUV422 支持。使用两个 CSI-2 通道时，可支持的最大速率为 RGB888 的 1080p30 或 YUV422 的 1080p50。在计算模块上使用四个通道时，可以以任一格式接收 1080p60。
HDMI 通过接收设备通告其可以支持的所有模式的 EDID 来协商分辨率。内核驱动程序不知道您希望接收的分辨率、帧速率或格式，因此用户可以通过 ioctl VIDIOC_S_EDID提供合适的文件，或者更轻松地使用 v4l2-ctl --fix-edid-checksums --set-edid=file=filename.txt（添加 --fix-edid-checksums 选项意味着您不必在源文件中获取正确的校验和值）。生成所需的 EDID 文件（二进制 EDID 文件的文本十六进制转储）并不太繁琐，并且有一些工具可用于生成它们，但它超出了本页的范围。
如上所述，使用DV_TIMINGS ioctls 配置驱动程序以匹配传入视频。最简单的方法是使用命令 v4l2-ctl --set-dv-bt-timings 查询。驱动程序支持生成SOURCE_CHANGED事件，如果你希望编写一个应用程序来处理不断变化的源。通过VIDIOC_S_FMT设置输出像素格式可以更改输出像素格式，但由于分辨率由 DV 时序配置，因此只会更新像素格式字段。
有几块市售板将该芯片连接到 Raspberry Pi。Auvidea B101 和 B102 是最广泛获得的，但也有其他等效的板。
此驱动程序是使用 config.txt dtoverlay tc358743 加载的。
该芯片还支持通过 I2S 捕获立体声 HDMI 音频。Auvidea 板将相关信号分解到一个接头上，该接头可以连接到 Raspberry Pi 的 40 引脚接头。所需的接线是：

除了 tc358743 覆盖之外，还需要 tc358743-audio 覆盖。这应该为 HDMI 音频创建一个 ALSA 录制设备。
没有对音频进行重新采样。音频的存在反映在 V4L2 控制TC358743_CID_AUDIO_PRESENT（音频存在）中，传入音频的采样率反映在 V4L2 控制TC358743_CID_AUDIO_SAMPLING_RATE（音频采样频率）中。当不存在音频或采样率与报告的采样率不同时进行录制会发出警告。

rpicam 和 raspicam 之间的区别

rpicam-apps 模拟了传统 raspicam 应用程序的大多数功能。但是，用户可能会注意到以下差异：

• Boost program_options不允许使用多字符的短版本选项，因此在存在这些选项的地方，必须删除它们。长格式选项的命名方式相同，并且保留任何单字符短格式。

• rpicam-still 和 rpicam-jpeg 不会在预览窗口中显示捕获的图像。

• rpicam-apps 删除了以下 raspicam 功能：

  • 不透明度 （--opacity）

  • 图像效果 （--IMXFX）

  • 色彩效果 （--colfx）

  • 注释 （--annotate， --annotateex）

  • 动态范围压缩或 DRC （--drc）

  • 立体声（--stereo、--decimate 和 --3dswap）

  • 图像稳定 （--vstab）

  • 演示模式 （--demo）
    后处理取代了其中的许多功能。

• rpicam-apps 删除了对 90° 和 270° 旋转的旋转选项支持。

• Raspicam将测光和曝光混为一谈;rpicam-apps 将这些选项分开。

• 要在 rpicam-apps 中禁用自动白平衡 （AWB），请使用 awbgains 设置一对色彩增益（例如 1.0、1.0）。

• rpicam-apps 无法将 NoIR 相机模块的自动白平衡 （AWB） 设置为灰色世界模式。相反，将 tuning-file 选项传递特定于 NoIR 的调整文件，如 imx219_noir.json。

• rpicam-apps 不提供对数字增益的显式控制。相反，增益选项会隐式设置它。

• rpicam-apps 删除了 --ISO 选项。相反，计算与所需 ISO 值相对应的增益。供应商可以提供增益到 ISO 的映射。

• rpicam-apps 不支持设置闪烁周期。

• rpicam-still 不支持突发捕获。相反，请考虑在 MJPEG 模式下使用 rpicam-vid 和 --segment 1 来强制将每一帧放入单独的文件中。

• rpicam-apps 对所有图像传感器都使用开源驱动程序，因此启用或禁用传感器缺陷像素校正 （DPC） 的机制是不同的。默认情况下，Raspberry Pi HQ Camera 上的 imx477 驱动程序启用传感器上的 DPC。要在 HQ 摄像机上禁用传感器上的 DPC，请运行以下命令：

  sudo echo 0 > /sys/module/imx477/parameters/dpc_enable
  

故障排除

如果您的相机模块无法按预期工作，请尝试以下一些修复：

• 在运行 Raspberry Pi OS Bullseye 或更早版本的 Raspberry Pi 3 及更早版本的设备上：

  • 要启用硬件加速的相机预览，请启用 Glamor。要启用 Glamor，请在终端中输入 sudo raspi-config，选择“高级选项”>“Glamor >”是“。然后使用 sudo reboot 重新启动您的 Raspberry Pi。

  • 如果看到与显示驱动程序相关的错误，请将 dtoverlay=vc4-fkms-v3d 或 dtoverlay=vc4-kms-v3d 添加到 /boot/config.txt。然后使用 sudo reboot 重新启动您的 Raspberry Pi。

• 在 Raspberry Pi 3 及更早版本上，图形硬件只能支持高达 2048×2048 像素的图像，这限制了可以调整到预览窗口中的相机图像。因此，对宽度大于 2048 像素的图像进行视频编码会产生损坏或丢失的预览图像。

• 在 Raspberry Pi 4 上，图形硬件只能支持高达 4096×4096 像素的图像，这限制了可以调整到预览窗口中的相机图像。因此，对宽度大于 4096 像素的图像进行视频编码会产生损坏或丢失的预览图像。

• 预览窗口可能会显示桌面环境中的显示器撕裂。这是一个已知的、无法修复的问题。

• 检查 FFC（扁平柔性电缆）是否牢固就位、完全插入，并且触点朝向正确的方向。FFC 应均匀插入，而不是倾斜。

• 如果您在相机和 Raspberry Pi 之间使用连接器，请检查连接器上的端口是否牢固就位、完全插入，以及触点是否朝向正确的方向。

• 检查以确保 FFC（扁平柔性电缆）连接到 CSI（相机串行接口），而不是 DSI（显示串行接口）。连接器适合任一端口，但只有 CSI 端口为摄像机供电和控制。查找印在端口附近电路板上的 CSI 标签。

• 更新到最新软件。

• 尝试使用其他电源。相机模块为 Raspberry Pi 的电源要求增加了约 200-250mA。如果您的电源质量低下，您的 Raspberry Pi 可能无法为相机模块供电。

• 如果您已经检查了上述所有问题，但您的相机模块仍然无法正常工作，请尝试在我们的论坛上发帖以获得更多帮助。

获取帮助

有关 libcamera 和 rpicam-apps 的进一步帮助，请查看 Raspberry Pi Camera 论坛。发布前：

• 记下您的操作系统版本 （uname -a）。

• 记下你的 libcamera 和 rpicam-apps 版本 （rpicam-hello --version）。

• 报告您正在使用的相机模块的品牌和型号。

• 报告您尝试使用的软件。我们不支持第三方摄像头模块供应商软件。

• 报告您的 Raspberry Pi 型号，包括内存大小。

• 包括应用程序控制台输出中的任何相关摘录。

如果相机软件中存在特定问题（例如崩溃），请考虑在 rpicam-apps GitHub 存储库中创建问题，包括上面列出的相同详细信息。