GX Camera Application Development Guide

From wiki_veye
Revision as of 11:38, 20 December 2025 by Xumm (talk | contribs)
Jump to navigation Jump to search

查看中文

1 GX Camera Application Development Guide

1.1 summarize

This document is applicable to scenarios where the driver has been correctly installed and the hardware connections are correct. It is intended to guide users through the following operations:

  • Query the device information of the cameras that have been connected to the GX series;
  • Identify the corresponding media devices, video nodes and I²C bus;
  • Select the appropriate image acquisition mode (streaming mode, trigger mode, synchronous mode) according to the requirements;
  • Configure key parameters such as resolution, frame rate, and data format.

By using the accompanying scripts and standard V4L2 tools (such as v4l2-ctl, media-ctl, yavta, etc.) or the veye_viewer tool, users can quickly complete the entire process of device detection, environment configuration and image acquisition.

1.2 Detect the status and configure the environment variables

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

First, try using the probe_camera_info-rk.sh script. This script is used to detect the connected and successfully registered camera devices, and retrieve the underlying information such as the media device node, video device node, sub-device node, I²C bus and device identifier corresponding to the device. After execution, an auto_camera_index.json file will be generated in the current directory and the retrieved information will be recorded in the file.

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

  }

]

By referring to the index information, we can see the "i2c_bus": "7" corresponding i2c_bus information, as well as the number of devices connected. The current index shows that only one device is connected, and the i2c_bus number is 7. If multiple devices are connected, the index information may include "i2c_bus": "10", "i2c_bus": "11" and so on.

Then, use the gx_probe.sh script. If there are multiple cameras, the i2c_bus read from the previous script can be used, and the corresponding camera model, width, height, frame rate, etc. information can be configured in the environment variables.

The usage method is:

$ source ./gx_probe.sh 7

A typical output is as follows:

$ 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

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.

1.3 Configure global variables for the command line

Based on the motherboard model, configure the I2C_BUS global variable.

  • ROC-RK3588S-PC

export I2C_BUS=7

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

export I2C_BUS=4

1.4 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

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

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

It can be seen that:

  • 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. The application (such as v4l2-ctl) can open it and make configurations.
  • Its output format is [UYVY8_2X8/1920x1080@10000/600000 field:none], where UYVY8_2X8 is a shortened form of 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.

1.5 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

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

2 Application examples

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

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

2.1.2 Trigger Source

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

0: Software trigger mode.

1: Hardware trigger mode.

2.1.3 Software trigger command

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

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

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

2.3 Video Streaming mode

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

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

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

2.3.4 Example of yavta
2.3.4.1 Install yavta

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

cd yavta;make

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

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

2.3.6 Example of gstreamer application

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

2.4 Trigger mode

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

2.4.2 Software trigger mode
2.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

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

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

2.4.3 Hardware trigger mode
2.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.

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

2.4.3.3 Perform hardware trigger operation

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

2.5 synchronous mode

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

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

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

2.5.4 Start taking pictures

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

3 i2c script for parameter configuration

We provide shell scripts to configure the parameters.

gx_mipi_i2c.sh user guide

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

5 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

6 Document History

  • 2025-11-28

Release 1st version.

Retrieved from "http://wiki.veye.cc/index.php?title=GX_Camera_Application_Development_Guide&oldid=8678"