GX Camera Application Development Guide

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 tools

It can be downloaded from veye_viewer

We can use this tool to configure some parameters of the camera (directly operate and change the parameters of the register), switch the mode (stream mode, trigger mode, synchronization mode), and view some basic information of the camera (resolution, frame rate, etc.)

7 Application examples

7.1 Configure parameters using 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

Parameters can be set and get using the following methods.

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

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

All the above functions can be implemented using gx_mipi_i2c.sh.

Note that the above parameters cannot be modified during the capture process.

The following is an explanation of each parameter:

7.1.1 Trigger Mode

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

0：Video streaming mode

1：Normal trigger mode.

4：Multi-camera synchronization mode.

7.1.2 Trigger Source

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

0: Software trigger mode.

1: Hardware trigger mode.

7.1.3 Software trigger command

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

7.1.4 Set frame rate

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

The maximum frame rate is automatically updated as the resolution changed.

7.2 Set image format using media-ctl

use the following command to configure the camera's data format, resolution, and frame rate using media-ctl:

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

Among them: "m00_b_gxcam '"$I2C_BUS"'-003b" refers to the complete name of the camera entity, UYVY8_2X8 is the mbus-code, '"$WIDTH"'x'"$HEIGHT"' indicates the resolution, 1/'"$FPS"' indicates the resolution frame rate.

For example, for GX-MIPI-IMX662, the command after variable replacement would be:

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

You can not only configure the data format, resolution, and frame rate in one command, but also modify them separately as needed.

7.3 Video Streaming mode

7.3.1 Set data format, resolution, frame rate

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 Frame rate statistics

In streaming mode, the following commands can be used for frame rate statistics：

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

Or：

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

7.3.3 Save image to file

• 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

Please refer to the description in the previous section for the image format.

7.3.4 Example of yavta

7.3.4.1 Install yavta

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

cd yavta;make

7.3.4.2 Save image to file

After setting data format, resolution, frame rate，run:

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

7.3.5 Example of import image to OpenCV

sudo apt install python3-opencv

See the samples directory on github for details.

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

7.3.6 Example of gstreamer application

We provide several gstreamer routines that implement the preview function. See the samples directory on github for details.

7.4 Trigger mode

7.4.1 Set data format, resolution, frame rate

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

7.4.2 Software trigger mode

7.4.2.1 Set mode

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 Start acquisition

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 Perform soft trigger operation

In other shell terminals, you can execute the following command multiple times for multiple triggers.

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

7.4.3 Hardware trigger mode

7.4.3.1 Set mode

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

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

The gx_mipi_i2c.sh script can be used to set rich trigger parameters.

7.4.3.2 Start acquisition

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 Perform hardware trigger operation

Connect the appropriate trigger signal to the trigger pin of the camera and trigger it.

7.5 synchronous mode

7.5.1 Set data format, resolution, frame rate

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 Switch to synchronous mode

Note: The RK platform only supports one camera connection. Perform the following operations on both mainboard terminals to switch to synchronous mode.

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

7.5.3 Set the camera as the master or slave.

master camera：

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

slave camera：

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

7.5.4 Start taking pictures

Several methods in the streaming mode can be used to take pictures.

8 i2c script for parameter configuration

We provide shell scripts to configure the parameters.

gx_mipi_i2c.sh user guide

9 Question Feedback

We are committed to providing richer possibilities for image applications on embedded platforms. Therefore, our software for embedded platforms is based on the principle of open source.

If you have any questions or suggestions about our existing software, please feel free to submit them to the forum or email our technical staff at xumm#csoneplus.com.

10 References

• ROC-RK3566-PC Manual

https://wiki.t-firefly.com/en/ROC-RK3566-PC/

• ROC-RK3588S-PC Manual

https://wiki.t-firefly.com/en/ROC-RK3588S-PC/

• ROC-RK3576-PC Manual

https://wiki.t-firefly.com/en/ROC-RK3576-PC/

• Firefly Linux User Guide

https://wiki.t-firefly.com/en/Firefly-Linux-Guide/index.html

11 Document History

• 2025-11-28

Release 1st version.