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	Done

2 Hardware Setup

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

2.1 The connection diagramof GX series cameras with 22-pin interface Raspberry Pi

GX Camera to RaspberryPi 5

2.2 The connection diagram between the GX series cameras and the 15-pin interface Raspberry Pi

GX Camera to RaspberryPi 4

3 Driver Installation and Verification

3.1 Download the driver package

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

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

To use a driver for a different camera module model, the currently installed driver must be uninstalled first.
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 probed properly.

4 Check 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 veye_viewer

The veye_viewer is an open-source, Qt-based client application that allows users to easily evaluate cameras and configure parameters.

Its operation logs, register listings, and open-source nature provide a convenient reference for users and support custom development.

The source code of veye_viewer can be downloaded here, or platform-specific executable programs are available directly in its release packages.

6.2 qv4l2

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 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 Using GStreamer

Through the script in GStreamer, functions such as image preview, picture capture, H264 video encoding and saving in MP4/MKV format can be realized.

8 yavta

8.1 Installing yavta

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

$ cd yavta;make

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

9 Importing Camera Data into OpenCV

9.1 Use OpenCV to preview images in UYVY format

• install opencv

$ sudo apt install python3-opencv

• To import camera data from a V4L2 device into OpenCV, we provide several sample programs.

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

10 v4l2-ctl Examples

10.1 Install v4l2-utils

$ sudo apt-get install v4l-utils

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

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

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

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

10.4.2 Trigger Source

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

0: Soft Trigger

1: Hard Trigger

10.5 Software trigger command

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

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

10.6 Trigger mode

10.6.1 Soft Trigger Mode

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

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

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

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

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

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

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

10.7 Video Streaming mode

10.7.1 Set frame rate

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

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

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

10.8 Synchronous Mode

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

10.8.1 Set synchronous mod

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

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

10.8.3 Start taking pictures

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

11 Shell script for parameter configuration

We provided shell scripts to configure the parameters.

gx_mipi_i2c.sh user guide

12 Recommendations for Customer Integration and Development

12.1 Initialization Stage

Resolution and frame rate configuration must be completed. It is recommended that customers perform these configurations during the program initialization phase by invoking the v4l2-ctl commands and the media_setting_rpi5.sh script. This ensures that resolution, frame rate, and data format are properly set.

Avoid using gx_mipi_i2c.sh to directly modify camera registers, as changes made at the register level may not be properly reflected in the Raspberry Pi Linux driver stack.

12.2 Operation Stage

Depending on the programming language used, customers can refer to the code samples and tools described earlier in this document.

Regarding timestamps, v4l2_buffer.timestamp provides the exact time when the Raspberry Pi SoC receives a complete frame. This can be used as a reference timestamp for camera synchronization or for synchronizing with external sensors.

12.3 Parameter Configuration

The GX series cameras offer rich and flexible configuration options, primarily implemented through direct register settings via gx_mipi_i2c.sh. Please refer to the register documentation and the gx_mipi_i2c.sh manual for details.

The gx_mipi_i2c.sh script includes a paramsave feature, which stores all configured parameters in the camera’s flash memory. Frequent invocation of this function within programs is not recommended.

13 This document's revision history

• 2025-12-06

The first version