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
2.2 The connection diagram between the GX series cameras and the 15-pin interface Raspberry Pi
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.
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.
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