Gx series camera appnotes 4 rpi

查看中文

How to use the GX series cameras on the Raspberry board

1 overview

The GX series cameras are designed for embedded AI applications. They offer high-performance ISP capabilities, support multiple operating modes, provide a wide range of configurable features, and are built with a robust and reliable design. The cameras use the MIPI CSI-2 interface and are well suited for embedded computing platforms.

1.1 Supported modules

series	model	state
GX系列	GX-MIPI-IMX662	complete

2 Hardware Preparation and Installation

The GX-series cameras utilize a Raspberry Pi-compatible 22-pin interface but require an independent 5 V DC power supply.

3 Drive Installation and Verification

3.1 Download the driver package

wget https://github.com/veyeimaging/raspberrypi_v4l2/releases/latest/download/raspberrypi_v4l2.tgz

Domestic users can download it from Gitee:

https://gitee.com/veyeimaging/raspberrypi_v4l2/releases/

3.2 install the driver

tar -xzvf raspberrypi_v4l2.tgz

cd raspberrypi_v4l2/release/

chmod +x *

• For Raspberry Pi 5

sudo ./install_driver.sh veye_gxcam

Then restart the Raspberry Pi.

Note: If it is indicated that the corresponding version of the driver cannot be found, it means that we do not provide the compiled driver program corresponding to your PiOS version. Please try to compile from the source code.

3.3 Uninstall the driver

If you want to switch to a different model of the camera module driver, you must first uninstall the current driver.
sudo ./uninstall_driver.sh veye_gxcam

3.4 System status verification

Take GX-MIPI-IMX662 as an example:
dmesg | grep gxcam

It can be seen that the camera model probed during the Linux startup stage is:

camera is: GX-MIPI-IMX662

And the /dev/video0 node exists, which proves that the camera is functioning properly.

Note: Trigger script link.

4 Detect the status and configure the environment variables

Here, we provide a script named gx_probe.sh, which is used to automatically detect the recognized camera and configure the default model, width, height, frame rate and other information of the camera into the environment variables.

The usage method is:
$ source ./gx_probe.sh i2c_bus

A typical output is as follows:

$ source ./gx_probe.sh 10

The gxcam driver is loaded on i2c-10, but the camera is not detected!

Found veye_gxcam camera on i2c-10.

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.

5 Configuration of Raspberry Pi 5

On the Raspberry Pi 5, the camera driver now operates via the Media Controller API, necessitating proper configuration of the media graph beforehand. This involves correctly setting the formats of the media pads and establishing appropriate pad links.

A set of scripts implementing this functionality is provided and stored in the rpi5_scripts directory.

• ./find_entity.sh

$ ./find_entity.sh

This is a Raspberry Pi 5.

Kernel version is 6.12.47, use i2c-10 for CAM0 and i2c-11 for CAM1.

Found gxcam @ i2c-10 entity on /dev/media3

Plese get frame from /dev/video0 and use /dev/v4l-subdev2 for camera setting.

After a reboot of the Raspberry Pi 5, the media node and video node assignments for the cameras may change. Therefore, it is recommended to run ./find_entity.sh prior to performing subsequent operations to explicitly identify the device nodes.

As shown in the above diagnostic output, the system has detected two connected cameras, along with their corresponding device nodes.

The CAM0 port on the board corresponds to i2c-10, and the CAM1 port on the board corresponds to i2c-11.

• media_setting_rpi5.sh

$ ./media_setting_rpi5.sh

This is a Raspberry Pi 5.

Kernel version is 6.12.47, do not support unpacked format.

Kernel version is 6.12.47, use i2c-10 for CAM0 and i2c-11 for CAM1.

Usage: ./media_setting_rpi5.sh veyecam2m/csimx307/cssc132/mvcam/gxcam -fmt [UYVY/RAW8/RAW10/RAW12] -x [roi_x] -y [roi_y] -w [width] -h [height] -c [cam 0|1]

This shell script is designed to detect the connection of a camera on Raspberry Pi 5.

    It utilizes media-ctl and v4l2-ctl commands to configure the linking relationships and data formats of the media pad.

    Once completed, you can directly use /dev/video0 or /dev/video8 to obtain image data.

Before proceeding with the subsequent operations, this script must be executed to complete the configuration of the parameters.

For example, for the GX-MIPI-IMX662 that is connected to the CAM0 port:

./media_setting_rpi5.sh gxcam -fmt UYVY -x 0 -y 0 -w 1920 -h 1080 -c 0

6 Real-time preview

6.1 Use veye_viewer to play the images

veye_viewer is an open-source client software based on QT5.

For the code and usage, please refer to:https://github.com/veyeimaging/veye_viewer。

Domestic users can access the Gitee repository.

6.2 Use qv4l2 to play images

First, install qv4l2

sudo apt install qv4l2

Note: For Raspberry Pi 5, you need to execute the aforementioned media_setting_rpi5.sh script before starting the qv4l2 image playback to complete the necessary preparations.

Enter "qv4l2" in the command line to start the V4L2 player.

2. Click the ▶ (play) button to bring up the opened media window.

Play gx camera using qv4l2 on RPI

7 Gstreamer Application Examples

export DISPLAY=:0

7.1 Install GStreamer

sudo apt-get install gstreamer1.0-tools

sudo apt-get install libx264-dev libjpeg-dev

sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev gstreamer1.0-plugins-ugly gstreamer1.0-tools gstreamer1.0-gl gstreamer1.0-gtk3

7.2 Run the gstreamer videotest command

gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink

7.3 Capture a picture (GX-MIPI-IMX662 @ 1080p mode)

gst-launch-1.0 v4l2src num-buffers=1 device=/dev/video0 ! 'video/x-raw, format=(string)UYVY, width=1920,height=1080' ! jpegenc ! filesink location=test_image.jpg

7.4 Frame rate test (GX-MIPI-IMX662 @ 1080p mode)

gst-launch-1.0 v4l2src device=/dev/video0 ! "video/x-raw,format=(string)UYVY, width=(int)1920, height=(int)1080,framerate=(fraction)30/1" ! videoconvert ! fpsdisplaysink video-sink=fakesink -v

7.5 Video preview (GX-MIPI-IMX662 @ 1080p mode)

gst-launch-1.0 v4l2src io-mode=dmabuf device=/dev/video0 ! "video/x-raw,format=(string)UYVY, width=(int)1920, height=(int)1080,framerate=(fraction)30/1" ! v4l2convert capture-io-mode=dmabuf output-io-mode=dmabuf ! autovideosink sync=false -v

8 V4L2-CTL Application Examples

8.1 Install v4l2-utils

$ sudo apt-get install v4l-utils

8.2 v4l2-ctl routine

• Capture a raw UYVY data image (in 1080p mode)

v4l2-ctl --set-fmt-video=width=1920,height=1080,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-1920x1080.yuv

• Capture 10 original UYVY data images (in 1080p mode)

v4l2-ctl --set-fmt-video=width=1920,height=1080,pixelformat=UYVY --stream-mmap --stream-count=10 --stream-to=uyvy-1920x1080_stream.yuv

8.3 List the data formats supported by the camera

v4l2-ctl --list-formats-ext

ioctl: VIDIOC_ENUM_FMT

        Type: Video Capture

        [0]: 'UYVY' (UYVY 4:2:2)

                Size: Discrete 1920x1080

        [1]: 'YUYV' (YUYV 4:2:2)

Note: For Raspberry Pi 5, the actual supported image formats depend on the camera's capabilities, rather than being limited to the list provided here.

8.4 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

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]

Note: For Raspberry Pi 5, all the commands in this section that use v4l2-ctl configuration parameters need to add the -d parameter to specify the subdevice used for the configuration parameters.

For example, when executing ./media_setting_rpi5.sh or ./find_entity.sh, it prompts to use /dev/v4l-subdev2 for parameter configuration.

Then, the command v4l2-ctl -L should be changed to v4l2-ctl -L -d /dev/v4l-subdev2

Note: All the above functions can be achieved by using the script gx_mipi_i2c.sh.

It should be noted that the above parameters cannot be modified once the image capture process begins. The following will provide detailed explanations for each one:

8.4.1 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.4.2 Trigger Source

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

0: Soft Trigger

1: Hard Trigger

8.5 Software trigger command

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

8.5.1 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.6 Trigger mode

8.6.1 Soft Trigger Mode

8.6.1.1 Set Mode

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

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

8.6.1.2 Start acquisition

v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=5 --stream-to="uyvy-${WIDTH}x${HEIGHT}.yuv"

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

8.6.2 Hardware trigger mode

Here, using GPIO21 of the Raspberry Pi as the analog trigger source and with the rising edge as the trigger condition, is exemplified.

The rich trigger parameter settings can be carried out by using the gx_mipi_i2c.sh script.

8.6.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=1

8.6.2.2 Start acquisition

v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=5 --stream-to="uyvy-${WIDTH}x${HEIGHT}.yuv"

8.6.2.3 Perform hardware trigger operation

In other shell terminals, you can execute the following command multiple times to trigger it repeatedly.

$ python gpio_trigger.py

Note: Trigger script link.

8.7 Video Streaming mode

8.7.1 Set frame rate

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=$FPS

8.7.2 The following command can be used for frame rate statistics

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

8.7.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="y8-${WIDTH}x${HEIGHT}.yuv"

or

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

8.8 Synchronous Mode

The subdevbelow needs to be differentiated based on the actual situation.

8.8.1 Set synchronous mod

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

8.8.2 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

8.8.3 Start taking pictures

The image capture method in synchronous mode is identical to that used in video streaming mode.

9 yavta

9.1 Installing yavta

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

$ cd yavta;make

9.2 yavta routine

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

example

$ ./yavta -c1 -Fuyvy_1920X1080.yuv --skip 0 -f UYVY -s 1920x1080 /dev/video0

10 Use OpenCV to obtain the image

10.1 Use OpenCV to preview images in UYVY format

• install opencv

$ sudo apt install python3-opencv

• 为了将摄像头数据从v4l2设备导入到opencv，我们提供了几个sample。

$ python ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 30

For the Raspberry Pi 5, an additional parameter --ctldev /dev/v4l-subdev*needs to be added to specify the subdev for the configuration parameters.

11 Shell script for parameter configuration

We provided shell scripts to configure the parameters.

gx_mipi_i2c.sh user guide

12 Some suggestions for client integration development

12.1 Initialization stage

The resolution and frame rate configurations need to be completed. It is recommended that customers directly use the v4l2-ctl command and the invocation of media_setting_rpi5.sh 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 Linux driver layer of the Raspberry Pi cannot synchronize to the set values.

12.2 Work 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 will contain the exact time when the Raspberry Pi chip receives a complete data frame. This can be used as a reference timestamp for camera synchronization or synchronization with other external sensors.

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

13 This document's revision history

• 2025-12-06

The first version