Gx series camera appnotes 4 rpi/zh

English

1 概述

GX系列相机是为嵌入式的AI应用推出的相机，具备卓越的ISP性能，多种工作模式，丰富的功能选项，可靠的稳定性设计。其使用MIPI CSI-2接口，尤其适合嵌入式运算平台使用。

本文介绍了如何在树莓派平台使用GX系列相机。

1.1 支持的模组

系列	型号	状态
GX系列	GX-MIPI-IMX662	完成

2 硬件准备及安装

GX系列相机使用树莓派兼容的22pin接口，但是需要独立的5V DC供电。

2.1 GX系列摄像头与22pin接口树莓派连接方式

GX Camera to RaspberryPi5

2.2 GX系列相机与 15pin接口的树莓派之间的连接方式

GX Camera to RaspberryPi4

3 驱动安装及验证

我们在这个github仓库保存了驱动代码，i2c工具集，配置脚本等内容。

国内用户可以使用gitee仓库。

3.1 下载驱动包

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

国内用户可通过gitee下载：

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

3.2 安装驱动

tar -xzvf raspberrypi_v4l2.tgz

cd raspberrypi_v4l2/release/

chmod +x *

• 对于树莓派5

sudo ./install_driver_rpi5.sh veye_gxcam

会在/boot/config.txt中安装CAM1和CAM0两个dtvoerlay。

• 其他树莓派

sudo ./install_driver.sh veye_gxcam

然后重启树莓派。

备注：如果提示无法找到对应版本的驱动，说明我们没有提供对应您的piOS版本编译后的驱动程序。请尝试从源码编译。

3.3 卸载驱动

如需更换成其他摄像头模组型号的驱动，必须要先卸载现在的驱动。

sudo ./uninstall_driver.sh veye_gxcam

3.4 系统状态验证

以GX-MIPI-IMX662为例：

dmesg | grep gxcam

可以看到linux启动阶段probe到的相机型号：

camera is: GX-MIPI-IMX662

并且/dev/video0 节点存在，证明摄像头状态正常。

4 状态检测并配置环境变量

在这里，我们提供了一个gx_probe.sh脚本，用于自动检测识别到的相机并将相机默认的型号、宽、高、帧率等信息配置到环境变量中。

使用方法是：

$ source ./gx_probe.sh i2c_bus

一个典型的输出如下：

$ 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

可以通过 echo $CAMERAMODEL来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。

5 树莓派5的配置

在树莓派5上，驱动程序现在使用media control API，我们必须先正确设置media graph。这包括正确设置media pad的格式并正确链接它们。

我们提供了一系列脚本实现这个功能，保存在rpi5_scripts目录。

• ./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.

树莓派5重启之后，相机的media node，video node可能发生变化，因此，建议执行后续操作前执行./find_entity.sh以明确设备节点。

上述提示信息中，可以看到系统插入了两个相机，以及每个相机的对应的设备节点。

i2c-10对应板子上的CAM0插口，i2c-11对应板子上的CAM1插口。

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

在进行后续操作前，必须执行此脚本以完成参数的配置。

举例来说，对于接到CAM0口的GX-MIPI-IMX662:

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

6 实时预览

6.1 使用veye_viewer播放图像

veye_viewer是一个基于QT的开源的客户端软件，可以方便客户进行相机评测、参数配置。另外其操作日志、寄存器清单以及开源的特性，方便客户进行参考，二次开发。

可通过veye_viewer下载源码，或在其发行版中直接下载对应平台的可执行程序。

国内用户可访问gitee仓库。

6.2 使用qv4l2播放图像

首先安装qv4l2

sudo apt install qv4l2

注：对于树莓派5，需要在执行qv4l2播放图像前先执行前面所述media_setting_rpi5.sh脚本，以进行准备工作。

1. 在命令行中输入qv4l2以启动 V4L2 播放器。

2. 点击 ▶（播放）按钮以调出打开的媒体窗口。

Play gx camera using qv4l2 on RPI

7 Gstreamer应用范例

export DISPLAY=:0

7.1 安装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 使用gstreamer

通过gstreamer中的脚本，可实现图像预览，图片抓拍，h264视频编码保存成mp4/mkv格式等功能。

7.3 网络传输 TCP streaming

树莓派（Server）一侧执行

gst-launch-1.0 -v v4l2src device=/dev/video0 num-buffers=-1 ! "video/x-raw,format=(string)UYVY, width=(int)1920, height=(int)1080,framerate=(fraction)30/1" ! v4l2h264enc extra-controls="controls, h264_profile=4, video_bitrate=4000000" ! 'video/x-h264, profile=high, level=(string)4' ! h264parse ! rtph264pay config-interval=1 pt=96 ! gdppay ! tcpserversink  host=x.x.x.x port=5000

码流带宽为4Mbps,持续传输，监听端口为5000。

Client一侧执行

gst-launch-1.0 -v tcpclientsrc host=x.x.x.x port=5000 ! gdpdepay ! rtph264depay ! avdec_h264 ! autovideosink sync=false

其中x.x.x.x为树莓派(Server)的IP地址。

Client一侧，如为windows系统，建议使用powershell。gstreamer的windows版本下载地址。只安装runtime files即可。

8 yavta 应用范例

8.1 下载并编译yavta

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

$ cd yavta;make

8.2 yavta 例程

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

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

9 使用opencv获取图片

9.1 使用opencv预览UYVY格式图像

• install opencv

$ sudo apt install python3-opencv

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

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

对于树莓派5，需要增加一个--ctldev /dev/v4l-subdev*参数用于指明配置参数的subdev。

10 v4l2-ctl 应用范例

10.1 安装v4l2-utils

$ sudo apt-get install v4l-utils

10.2 v4l2-ctl例程

• 抓拍一张UYVY原始数据图片 (1080p mode)

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

• 抓拍10张UYVY原始数据图片 (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 列出相机支持的数据格式

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)

注：对于树莓派5，实际支持的图像格式取决于相机能力，而不是此处的列表。

10.4 使用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

可以使用下面的方法设置和获取参数。

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl [ctrl_type]=[val]

v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]

注：对于树莓派5，本节的所有使用v4l2-ctl配置参数的命令需要增加 -d参数来指明配置参数使用的subdev。

比如执行./media_setting_rpi5.sh或者./find_entity.sh的时候提示使用/dev/v4l-subdev2进行参数配置。

则v4l2-ctl -L需要变更为v4l2-ctl -L -d /dev/v4l-subdev2。

注：以上所有功能，均可使用gx_mipi_i2c.sh实现。

需要指出的是，以上参数在开始取图的状态均不可修改。下面进行逐个说明：

10.4.1 配置触发模式

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

0：流模式

1：普通触发模式

4：多相机同步模式

10.4.2 配置触发源

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

0: 软触发

1: 硬触发

10.4.3 软触发一次

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

10.4.4 设置帧率

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

随分辨率的调整，最大帧率会自动更新。

10.5 触发模式

10.5.1 软触发模式

10.5.1.1 设置模式

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

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

10.5.1.2 开始取图

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

10.5.1.3 进行软触发操作

在其他的shell终端，可以多次执行下面命令进行多次触发。

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

10.5.2 硬触发模式

下面以使用树莓派GPIO21为模拟触发源，上升沿触发为例。

可以使用gx_mipi_i2c.sh脚本进行丰富的触发参数设置。

10.5.2.1 设置模式

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

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

10.5.2.2 开始取图

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

10.5.2.3 进行硬触发操作

在其他的shell终端，可以多次执行下面命令进行多次触发。

$ python gpio_trigger.py

Note:触发脚本链接。

10.6 流模式

10.6.1 设置帧率

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

10.6.2 可使用如下命令进行帧率统计

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

10.6.3 保存图片到文件

• 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"

或者

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

10.7 同步模式

下面的subdev要根据实际情况区分。

10.7.1 设置同步模式

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

10.7.2 设置主从相机

主相机：

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

从相机：

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

10.7.3 开始取图

同步模式下的取图方式与视频流模式下完全一致。

11 shell脚本进行参数配置

我们提供了shell脚本来配置参数。

gx_mipi_i2c.sh user guide

12 客户集成开发的几点建议

12.1 初始化阶段

需要完成分辨率、帧率的配置。建议客户在程序初始化阶段，直接v4l2-ctl命令以及media_setting_rpi5.sh的调用，完成分辨率帧率以及数据格式的配置。

不要使用gx_mipi_i2c.sh直接设置相机寄存器，因为直接设置相机寄存器的话，树莓派的linux驱动层次并不能同步到设置值。

12.2 工作阶段

客户根据自己开发语言的不同，可以参考本文前述的代码、工具。

关于时间戳，v4l2_buffer.timestamp会带有树莓派芯片接收到一个完整数据帧的准确时间，可以用于做相机同步或者与其他外部传感器同步的参考时间戳。

12.3 参数配置

GX系列相机的参数非常丰富和灵活，主要使用gx_mipi_i2c.sh直接进行寄存器配置的方式实现。具体请参考寄存器文档和gx_mipi_i2c.sh的说明文档。

gx_mipi_i2c.sh具有paramsave功能，作用是将客户所有的配置参数保存的相机flash中，但是不建议客户在程序中频繁调用。

13 本文修改记录

• 2025-12-06

第一个版本