GX Camera Application Development Guide on Rochchip/zh

1 概述

本文档适用于 驱动已正确安装、硬件连接无误 的场景，旨在指导用户完成以下操作：

• 查询已接入 GX 系列摄像头的设备信息；
• 识别对应的媒体设备、视频节点及 I²C 总线；
• 根据需求选择合适的图像采集模式（流模式、触发模式、同步模式）；
• 配置分辨率、帧率、数据格式等关键参数。

通过配套脚本和标准 V4L2 工具（如 v4l2-ctl、media-ctl、yavta 等）或veye_viewer工具，用户可快速完成设备探测、环境配置与图像采集全流程。

2 状态检测并配置环境变量

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

首先试用 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"

  }

]

通过索引信息，我们可以看到"i2c_bus": "7"对应的i2c_bus信息，以及接入了多少台设备，当前索引显示只接入一台设备，并且i2c_bus号是7，如果接入多个设备，索引信息可能会有"i2c_bus": "10"，"i2c_bus": "11"等信息。

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

使用方法是：

$ source ./gx_probe.sh 7

一个典型的输出如下：

$ 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来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。

3 配置命令行全局变量

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

• ROC-RK3588S-PC

export I2C_BUS=7

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

export I2C_BUS=4

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

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

media-ctl -p -d /dev/media0

4.1 链接关系

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

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

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

5 相机支持的mbus-code

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

格式对应关系

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

6 veye_viewer工具

可通过veye_viewer下载。

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

7 应用范例

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

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

7.1.1 配置触发模式

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

0：流模式

1：普通触发模式

4：多相机同步模式

7.1.2 配置触发源

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

0: 软触发

1: 硬触发

7.1.3 软触发一次

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

7.1.4 设置帧率

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

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

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

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

7.3 流模式

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

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

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

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

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

7.3.4 yavta应用范例

7.3.4.1 yavta安装

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

$ cd yavta;make

7.3.4.2 保存图片到文件

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

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

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

$ sudo apt install python3-opencv

详见github上的samples目录。

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

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

7.3.6 gstreamer应用范例

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

7.4 触发模式

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

7.4.2 软触发模式

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

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

7.4.2.3 进行软触发操作

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

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

7.4.3 硬触发模式

7.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脚本进行丰富的触发参数设置。

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

7.4.3.3 进行硬触发操作

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

7.5 同步模式

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

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

7.5.2 设置同步模式

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

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

7.5.3 设置主从相机

主相机：

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

从相机：

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

7.5.4 开始取图

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

8 i2c脚本使用说明

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

gx_mipi_i2c.sh user guide

9 本文修改记录

• 2025-11-28

第一个版本。