GX Camera Application Development Guide on Rochchip/zh

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

1 概述

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

本文主要达成一下目的：

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

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

注意，veye_viewer客户端已经内置了设备探测和media-ctl配置功能。

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脚本使用

2.2 gx_probe.sh

为了方便本文后续描述方便，

然后使用gx_probe.sh脚本，如果是多路相机，可以根据上一个脚本读出的i2c_bus执行，并将对应的相机型号、宽、高、帧率等信息配置到环境变量中。

使用方法是：

$ source ./gx_probe.sh i2c_bus

一个典型的输出如下：

$ source ./gx_probe.sh 7

Found veye_gxcam camera on i2c-7.

Setenv CAMERAMODEL = GX-MIPI-IMX662

Setenv FPS = 60

Setenv WIDTH = 1920

Setenv HEIGHT = 1080

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

2.3 配置命令行全局变量

根据主板型号，配置I2C_BUS全局变量。

• ROC-RK3588S-PC

export I2C_BUS=7

• ROC-RK3566-PC and ROC-RK3576-PC

export I2C_BUS=4

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

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

media-ctl -p -d /dev/media0

2.4.1 链接关系

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

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

2.4.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指令修改。

2.5 相机支持的mbus-code

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

格式对应关系

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

3 veye_viewer工具

可通过veye_viewer下载。

我们可以使用该工具对相机进行一些参数配置(对寄存器直接操作更改参数)，模式更换(流模式，触发模式，同步模式)，查看相机的一些基本信息(分辨率，帧率等)。

4 应用范例

4.1 使用v4l2-ctl配置参数

注：/dev/v4l-subdev2 /dev/media0 /dev/video0 中的编号"2", "0", "0"是内核动态分配的，不代表固定设备。

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

User Controls

                   work_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实现。

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

4.1.1 配置触发模式

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

0：流模式

1：普通触发模式

4：多相机同步模式

4.1.2 配置触发源

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

0: 软触发

1: 硬触发

4.1.3 软触发一次

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

4.1.4 设置帧率

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

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

4.2 使用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]'

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

4.3 流模式

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

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

4.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

4.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

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

4.3.4 yavta应用范例

4.3.4.1 yavta安装

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

$ cd yavta;make

4.3.4.2 保存图片到文件

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

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

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

$ sudo apt install python3-opencv

详见github上的samples目录。

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

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

4.3.6 gstreamer应用范例

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

4.4 触发模式

4.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]'

4.4.2 软触发模式

4.4.2.1 设置模式

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

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

4.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

4.4.2.3 进行软触发操作

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

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

4.4.3 硬触发模式

4.4.3.1 设置模式

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

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

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

4.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

4.4.3.3 进行硬触发操作

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

4.5 同步模式

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

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

4.5.2 设置同步模式

注：rk平台只支持接一路相机，在两个主板终端都执行以下操作，切换到同步模式。

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

4.5.3 设置主从相机

主相机：

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

从相机：

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

4.5.4 开始取图

可采用流模式中的几种方式取图。

5 i2c脚本使用说明

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

gx_mipi_i2c.sh user guide

6 本文修改记录

• 2025-11-28

第一个版本。