GX Camera Application Development Guide on Rochchip

Application Layer Usage and Development Guide for GX Series Camera Modules on the Rockchip Platform

1 Outline

This document is applicable to scenarios where the driver has been correctly installed, the hardware connections are correct, and the camera has been properly recognized.

This article mainly aims to achieve the following goals:

• Query the device information of the GX series cameras that have been connected.
• Complete the setting and preparation of the camera working mode;
• Introduce several methods for previewing and taking screenshots;
• Introduce the method of parameter configuration;
• Guide the customer for further development.

For the Rockchip platform, regardless of the method used to call the camera, the steps of device detection and media-ctl configuration format must be completed before proceeding with the subsequent operations. Therefore, the following will first introduce the device detection and media-ctl configuration.

Note that the veye_viewer client has already incorporated device detection and media-ctl configuration functions. Therefore, after completing the driver installation and confirming the hardware connection, you can directly refer to the veye_viewer client section described later to preview the camera images.

2 The equipment detects and configures the environment variables.

Here, we have provided two scripts that can automatically retrieve some information about the camera.

2.1 probe_camera_info-rk.sh

This script is used to detect the connected and successfully registered camera devices, and retrieve the underlying information such as the media device nodes, video device nodes, sub-device nodes, I²C bus and device names corresponding to the devices.

After execution, an "auto_camera_index.json" file will be generated in the current directory, and the retrieved information will be recorded in this file.

Here is an example:

$ ./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"

  }

]

The content within {} represents information about a camera. If the motherboard supports multiple camera modules, multiple sets of {} will appear, each containing the corresponding camera information.

The explanation of the camera information is as follows:

Camera information

antonomasia	designation	effect	Where used
media_node	Media device node	Used for accessing devices within the media-controller framework	Used when configuring the resolution and format through the "media-ctl" command
video_node	Video capture device node	Typical V4L2 video device	v4l2-ctl or the programs developed by the customers, are used to obtain the images.
video_subnode	V4L2 sub-device node	When configuring the parameters of the camera, use	The v4l2-ctl command is used
media_entity_name	Media entity name	Describe the name of the equipment, for example "m00_b_gxcam 7-003b"	Used when configuring the resolution and format through the "media-ctl" command
i2c_bus	I²C bus number	The I²C bus number indicating the device connection	The underlying communication channel for configuring the camera parameters, the gx_mipi_i2c.sh script uses

The media device nodes, video device nodes, sub-device nodes, I²C bus and device names used in the following text can all be replaced with the information in the JSON file obtained from this detection script.

2.2 gx_probe.sh

By using the gx_probe.sh script, the I²C bus number corresponding to a certain camera, the camera model, width, height, frame rate, etc. can be configured into the environment variables.

In this way, it will facilitate the subsequent use of the media-ctl configuration format, making it easier to use.

The usage method is:

$ source ./gx_probe.sh i2c_bus

A typical output is as follows:

$ 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

You can verify the output result of the environment variable by using the command "echo $CAMERAMODEL". Note that this environment variable is only valid for the current session.

3 Using the media-ctl configuration format

3.1 Use media-ctl to view the topology structure

By using the "media-ctl" command, the current topology structure can be clearly displayed.

media-ctl -p -d /dev/media0

3.1.1 Link relationship

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

The application can obtain images through the /dev/video0 node.

3.1.2 gx camera entity information

Take GX-MIPI-IMX662 as an example:

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

can see:

• The complete name of this Entity is: m00_b_gxcam 7-003b. (On the ROC-RK3566-PC, the name of this Entity is m00_b_gxcam 4-003b).
• It is a V4L2 subdev (Sub-Device) Sensor.
• The corresponding node is /dev/v4l-subdev2. Applications (such as v4l2-ctl) can open it and configure it.
• Its output format is [UYVY8_2X8/1920x1080@10000/600000 field:none], where UYVY8_2X8 is a shorthand for an mbus-code. The supported mbus-codes will be listed in the next section. The current resolution is 1920x1080.
• The current frame interval is 10000/600000, which means the frame rate is 60.

The data format output by the camera can be modified through the "media-ctl" command.

3.2 Camera-supported MBUS code

The GX series cameras utilize the UYVY data format capability. For specific details, please refer to the data manuals of each model of the cameras.

Format correspondence relationship

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

3.3 Configure the image format using media-ctl

The data format, resolution and frame rate of the camera can be configured through the following command.

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

Here: "m00_b_gxcam 7-003b" refers to the complete entity name of the camera. "UYVY8_2X8" is the mbus-code, and "$WIDTH"x"$HEIGHT" indicates the resolution, while 1/"$FPS" indicates the frame rate.

For example, for GX-MIPI-IMX662, the result after variable substitution of this command is:

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

Not only can you configure the data format, resolution and frame rate all at once in one command, but you can also modify individual items or several items separately.

Note that the names of each node in media-ctl can be adjusted according to the content of the aforementioned JSON file to configure different cameras.

4 veye_viewer client

"veye_viewer" is an open-source client software based on QT, which enables customers to conduct camera evaluations and parameter configurations conveniently. Additionally, its operation logs, register list, and open-source features facilitate customer reference and enable secondary development.

The source code can be downloaded via veye_viewer, or the corresponding platform executable program can be directly downloaded from its distribution.

5 Example of Yavta Application

5.1 Yavta Installation

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

$ cd yavta;make

5.2 Save the picture to a file

After configuring the data format, resolution and frame rate, execute:

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

6 Example of importing camera data into OpenCV

$ sudo apt install python3-opencv

Please refer to the "samples" directory on GitHub for details.

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

Make sure to use the appropriate parameters to execute the above procedure.

7 GStreamer Application Example

We have provided several GStreamer routines that implement the preview function. Please refer to the "samples" directory on GitHub for details.

8 V4L2-CTL Application Examples

Taking /dev/v4l-subdev2 /dev/media0 /dev/video0 as an example, this article introduces the method of directly configuring the camera and obtaining images using the command line.

8.1 Install v4l2-utils

sudo apt-get install v4l-utils

8.2 Configure parameters using v4l2-ctl

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

The parameters can be set and retrieved 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 of the above functions can be achieved by using the gx_mipi_i2c.sh script.

It should be noted that all the above parameters cannot be modified during the image generation process. The following will provide detailed explanations for each one:

8.2.1 Configure trigger mode

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

1: Ordinary Trigger Mode

4: Multi-camera Synchronization Mode

8.2.2 Configure trigger source

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

0: Soft Trigger

1: Hard Trigger

8.2.3 Soft trigger once

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

8.2.4 Set frame rate

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

As the resolution is adjusted, the maximum frame rate will be automatically updated.

8.3 stream mode

8.3.1 Set the data format, resolution, and frame rate

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

or

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

8.3.3 Save the picture to a file

• UYVY format

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 Trigger mode

8.4.1 Set the data format, resolution, and frame rate

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

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

8.4.2 Soft Trigger Mode

8.4.2.1 Setup Mode

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

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

8.4.2.2 Start taking pictures

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 Perform a hard trigger operation

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

8.5 synchronous mode

The following nodes and sub-devices should be differentiated according to the specific circumstances.

8.5.1 Set the data format, resolution, and frame rate

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 Set the synchronization mode

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

8.5.3 Set up the master and slave cameras

Main 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

8.5.4 Start taking pictures

The method of taking screenshots in the synchronization mode is exactly the same as that in the video stream mode.

9 I2C Script Usage Instructions

We provided shell scripts to configure the parameters.

gx_mipi_i2c.sh user guide

11 initialization phase

The resolution and frame rate configurations need to be completed. It is recommended that customers directly integrate the calls of media-ctl and v4l2-ctl commands during the program initialization stage to complete the configuration of resolution, frame rate, and data format.

Do not use gx_mipi_i2c.sh to directly set the camera registers, because if you directly set the camera registers, the Rockchip Linux driver layer cannot synchronize to the set values.

On the Rockchip platform, for a specific motherboard, the nodes detected by the script ./probe_camera_info-rk.sh remain constant. It is recommended that customers directly use the JSON file output by this script as the configuration file for their own programs.

The customer can also use the output of this script as a reference and directly hard-code the node names in the code.

11.1 working stage

Depending on the programming language they use, customers can refer to the aforementioned code and tools in this article.

Regarding the timestamp, the v4l2_buffer.timestamp field contains the exact time when the RK chip received a complete data frame. It can be used as a reference timestamp for camera synchronization or synchronization with other external sensors.

11.2 parameter configuration

The parameters of the GX series cameras are very rich and flexible. They are mainly achieved through the direct register configuration method using gx_mipi_i2c.sh. For details, please refer to the register documentation and the description document of gx_mipi_i2c.sh.

The gx_mipi_i2c.sh script has the "paramsave" function, which is designed to save all the configuration parameters of the customer into the camera's flash memory. However, it is not recommended for the customer to frequently call this function within the program.

12 This document's revision history

• 2025-12-06

Adjust the document structure and add some sections.

• 2025-11-28

The first version.