GX Camera Application Development Guide on Rochchip/zh

English

GX系列摄像头模组在Rockchip平台的应用层使用和开发指南

1 概述

本文档适用于驱动已正确安装、硬件连接无误，且相机已经正确识别的场景。

本文主要达成一下目的：

• 查询已接入的 GX 系列摄像头的设备信息；
• 完成摄像头工作模式的设置和准备；
• 介绍几种预览、抓图的方法；
• 介绍参数配置方法；
• 对客户二次开发进行指引。

对于rockchip平台，无论使用哪种方法调用相机，均需完成设备探测和media-ctl配置格式的步骤，才可以进行后续操作。所以下面首先介绍设备探测和media-ctl配置。

注意，veye_viewer客户端已经内置了设备探测和media-ctl配置功能。因此，在完成驱动安装和硬件连接确认之后，可以直接参考后文所述veye_viewer客户端章节预览相机图像。

2 设备检测并配置环境变量

在这里，我们提供了两个脚本，可以自动检索相机的一些信息。

2.1 probe_camera_info-rk.sh

该脚本用于探测已连接并成功注册的摄像头设备，检索设备对应的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称等底层信息。

执行后，将在当前目录生成 auto_camera_index.json 文件并在文件中记录检索到的信息。

下面是一个例子：

$ ./probe_camera_info-rk.sh

cat auto_camera_index.json

[

  {

    "media_node": "/dev/media0",

    "video_node": "/dev/video0",

    "video_subnode": "/dev/v4l-subdev2",

    "media_entity_name": "m00_b_gxcam 7-003b",

    "i2c_bus": "7"

  }

]

{}内是一个摄像头的信息，如果主板支持多个摄像头模组，则会出现多组{}包含的内容。

摄像头信息解释如下：

摄像头信息

代称	名称	作用	何处使用
media_node	媒体设备节点 (Media device node)	用于访问 media-controller 框架中的设备	由media-ctl命令配置分辨率和格式时使用
video_node	视频设备节点(Video capture device node)	典型 V4L2 视频设备	v4l2-ctl或者客户开发的程序，获取图像时使用
video_subnode	视频子设备节点（V4L2 sub-device node）	配置摄像头的部分参数时使用	v4l2-ctl命令使用
media_entity_name	设备名称（Media entity name）	描述设备的名称,例如 "m00_b_gxcam 7-003b"	由media-ctl命令配置分辨率和格式时使用
i2c_bus	I²C 总线号	表示设备连接的 I²C 总线编号	对摄像头进行参数配置的底层通信信道，gx_mipi_i2c.sh脚本使用

后文中使用的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称，均可参考此探测脚本得到的json文件中的信息进行替换。

2.2 gx_probe.sh

使用gx_probe.sh脚本，可以将某一个相机对应的I²C总线编号、相机型号、宽、高、帧率等信息配置到环境变量中。

如此，则方便后续使用media-ctl配置格式使用起来更方便。

使用方法是：

$ source ./gx_probe.sh i2c_bus

一个典型的输出如下：

$ source ./gx_probe.sh 7

Found veye_gxcam camera on i2c-7.

Setenv I2C_BUS = 7

Setenv CAMERAMODEL = GX-MIPI-IMX662

Setenv FPS = 60

Setenv WIDTH = 1920

Setenv HEIGHT = 1080

可以通过 echo $CAMERAMODEL来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。

3 使用media-ctl配置格式

3.1 使用media-ctl查看拓扑结构

使用media-ctl指令，可以清晰的展现出当前的拓扑结构。

media-ctl -p -d /dev/media0

3.1.1 链接关系

gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)

应用程序可以通过/dev/video0节点获取图像。

3.1.2 gx camera entity信息

以GX-MIPI-IMX662为例：

- entity 63: m00_b_gxcam 7-003b (1 pad, 1 link)

             type V4L2 subdev subtype Sensor flags 0

             device node name /dev/v4l-subdev2

        pad0: Source

                [fmt:UYVY8_2X8/1920x1080@10000/600000 field:none colorspace:rec709

                 crop:(0,0)/1920x1080]

                -> "rockchip-csi2-dphy0":0 [ENABLED]

可以看到：

• 该Entity完整的名称是： m00_b_gxcam 7-003b。（在ROC-RK3566-PC上该Entity名称是m00_b_gxcam 4-003b）。
• 它是一个 V4L2 subdev (Sub-Device) Sensor。
• 它对应的节点是 /dev/v4l-subdev2 ，应用程序（如v4l2-ctl）可以打开它，并进行配置。
• 它的输出格式是 [UYVY8_2X8/1920x1080@10000/600000 field:none] ，其中UYVY8_2X8是一种mbus-code的简写，下一小节会列出支持的mbus-code。
• 当前分辨率是1920x1080 。
• 当前帧间隔是10000/600000,即帧率是60。

摄像机输出的数据格式，可以通过media-ctl指令修改。

3.2 相机支持的mbus-code

GX系列相机使用UYVY数据格式能力，具体请参考每个型号的相机的数据手册。

格式对应关系

Format on datasheet	mbus-code for media-ctl	FourCC pixelformat for v4l2-ctl
UYVY	UYVY8_2X8	UYVY

3.3 使用media-ctl配置图像格式

可以通过下面的命令，配置摄像机的数据格式，分辨率，帧率。

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

其中："m00_b_gxcam 7-003b"指的相机的entity完整名称，UYVY8_2X8为mbus-code，'"$WIDTH"'x'"$HEIGHT"'指明了分辨率，1/'"$FPS"'指明了帧率。

比如，对于GX-MIPI-IMX662,这个命令经过变量替换后的结果是：

$ media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'

不仅可以在一个命令中同时配置数据格式，分辨率，帧率，也可以单独修改某一项或某几项。

注意，media-ctl中的各个node名称，均可参考前述json文件的内容调整，以配置不同的摄像头。

4 veye_viewer客户端

veye_viewer是一个基于QT的开源的客户端软件，可以方便客户进行相机评测、参数配置。另外其操作日志、寄存器清单以及开源的特性，方便客户进行参考，二次开发。

可通过veye_viewer下载源码，或在其发行版中直接下载对应平台的可执行程序。

5 yavta应用范例

5.1 yavta安装

git clone git://git.ideasonboard.org/yavta.git

$ cd yavta;make

5.2 保存图片到文件

配置完数据格式，分辨率，帧率之后，执行：

./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0

6 将相机数据导入OpenCV的范例

$ sudo apt install python3-opencv

详见github上的samples目录。

$ python3 ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7

注意需要使用合适的参数来执行上述程序。

7 gstreamer应用范例

我们提供了几个gstreamer例程，实现了预览功能。详见github上的samples目录。

8 v4l2-ctl应用范例

下面以/dev/v4l-subdev2 /dev/media0 /dev/video0 为例子，介绍直接用命令行配置相机和获取图像的方式。

8.1 安装v4l2-utils

sudo apt-get install v4l-utils

8.2 使用v4l2-ctl配置参数

$ v4l2-ctl -d /dev/v4l-subdev2 -L

User Controls

                   trigger_mode 0x00981a01 (int)    : min=0 max=4 step=1 default=0 value=0 flags=volatile, execute-on-write

                    trigger_src 0x00981a02 (int)    : min=0 max=1 step=1 default=1 value=1 flags=volatile, execute-on-write

                    soft_trgone 0x00981a03 (button) : value=0 flags=write-only, execute-on-write

                      sync_role 0x00981a04 (int)    : min=0 max=1 step=1 default=0 value=0 flags=volatile, execute-on-write

                     frame_rate 0x00981a05 (int)    : min=0 max=60 step=1 default=60 value=60 flags=volatile, execute-on-write

可以使用下面的方法设置和获取参数。

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl [ctrl_type]=[val]

v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]

以上所有功能，均可使用gx_mipi_i2c.sh实现。

需要指出的是，以上参数在取图过程中均不可修改。下面进行逐个说明：

8.2.1 配置触发模式

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=[0-2]

0：流模式

1：普通触发模式

4：多相机同步模式

8.2.2 配置触发源

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=[0-1]

0: 软触发

1: 硬触发

8.2.3 软触发一次

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1

8.2.4 设置帧率

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=[1-max]

随分辨率的调整，最大帧率会自动更新。

8.3 流模式

8.3.1 设置数据格式，分辨率，帧率

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

8.3.2 帧率统计

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null

或者

./yavta -c-1 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0

8.3.3 保存图片到文件

• UYVY格式

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-${WIDTH}x${HEIGHT}.yuv

图片格式请参考前面章节的描述。

8.4 触发模式

8.4.1 设置数据格式，分辨率，帧率

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

例：$ media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60]'

8.4.2 软触发模式

8.4.2.1 设置模式

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=1

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=0

8.4.2.2 开始取图

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-${WIDTH}x${HEIGHT}.yuv

8.4.2.3 进行软触发操作

在其他的shell终端，可以多次执行下面命令进行多次触发。

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1

8.4.3 硬触发模式

8.4.3.1 设置模式

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=1

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=1

可以使用gx_mipi_i2c.sh脚本进行丰富的触发参数设置。

8.4.3.2 开始取图

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-${WIDTH}x${HEIGHT}.yuv

8.4.3.3 进行硬触发操作

将合适的触发信号连接到摄像机的trigger引脚并进行触发。

8.5 同步模式

下面的各node和subdev要根据实际情况区分。

8.5.1 设置数据格式，分辨率，帧率

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

8.5.2 设置同步模式

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=4

8.5.3 设置主从相机

主相机：

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=0

从相机：

$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=1

8.5.4 开始取图

同步模式下的取图方式与视频流模式下完全一致。

9 i2c脚本使用说明

我们提供了shell脚本来配置参数。

gx_mipi_i2c.sh user guide

10 客户集成开发的几点建议

10.1 初始化阶段

需要完成分辨率、帧率的配置。建议客户在程序初始化阶段，直接集成media-ctl和v4l2-ctl命令的调用，完成分辨率帧率以及数据格式的配置。

不要使用gx_mipi_i2c.sh直接设置相机寄存器，因为直接设置相机寄存器的话，Rockchip的linux驱动层次并不能同步到设置值。

在Rockchip平台，对于一个指定的主板，./probe_camera_info-rk.sh所探测到的节点是固定不变的。建议客户直接使用此脚本输出的json文件作为自己程序的配置文件。

客户也可以以此脚本的输出作为参考直接在代码中写死节点名称。

10.2 工作阶段

客户根据自己开发语言的不同，可以参考本文前述的代码、工具。

关于时间戳，v4l2_buffer.timestamp会带有RK芯片接收到一个完整数据帧的准确时间，可以用于做相机同步或者与其他外部传感器同步的参考时间戳。

10.3 参数配置

GX系列相机的参数非常丰富和灵活，主要使用gx_mipi_i2c.sh直接进行寄存器配置的方式实现。具体请参考寄存器文档和gx_mipi_i2c.sh的说明文档。

gx_mipi_i2c.sh具有paramsave功能，作用是将客户所有的配置参数保存的相机flash中，但是不建议客户在程序中频繁调用。

11 本文修改记录

• 2025-12-06

调试文档结构，增加一些章节。

• 2025-11-28

第一个版本。