Gx series camera appnotes 4 rpi/zh

English

1 概述

GX系列相机是为工业领域的AI应用推出的相机。其使用MIPI CSI-2接口，尤其适合嵌入式运算平台使用。它具备丰富的数据格式和触发特性，极高的带宽和可靠的稳定性。

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

1.1 支持的模组

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

2 硬件准备及安装

2.1 GX系列摄像头使用ADP-MV1的连接方式

MV系列相机需要使用ADP-MV1转接板才能连接到树莓派。

2.1.1 MV系列摄像头与ADP-MV1的连接

二者使用0.5mm间距*30P的FFC异面线连接，注意接触面向外。

TOP	BOTTOM
ADP-MV1 to MV-MIPI-X	ADP-MV1 to MV-MIPI-X

2.1.2 供电

ADP-MV1需要独立的5V供电，可以使用杜邦线直接从树莓派主板取电。

ADP-MV1 power supply

2.1.3 树莓派5

二者使用15P转22P的FFC同面线连接，注意接触面安装方向。

TOP	BOTTOM
ADP-MV1 to RPI5	ADP-MV1 to RPI5_2

2.1.4 树莓派Model B和Model B+

二者使用1mm间距*15P的FFC异面线连接，注意接触面安装方向。

MV camera and RPI connection

2.1.5 树莓派Zero,Zero W和Computer Module

二者使用15P转22P的FFC同面线连接，注意接触面安装方向。

MV camera and Raspberry Pi zero connection

MV camera and Raspberry Pi CM4

MV camera connect to CM5

2.2 RAW系列摄像头连接到树莓派

2.2.1 树莓派5

RAW-MIPI-SC132M使用15to22pin同面FFC线，其他RAW系列相机使用22pin异面FFC线。

RAW CAM to RPI5

2.2.2 树莓派Model B和Model B+

RAW-MIPI-SC132M使用15pin异面FFC线，其他RAW系列相机使用15to22pin同面FFC线。

RAW series camera and RPI connection

2.2.3 树莓派Zero,Zero W和Computer Module

RAW-MIPI-SC132M使用15to22pin同面FFC线，其他RAW系列相机使用22pin异面FFC线。

RAW-MIPI-AR0234-RPI ZERO

RAW-MIPI-SC535M connect to CM5

V4L2模式用法

我们在这个github仓库保存了v4l2模式的代码。

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

2.3 下载驱动包

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

国内用户可通过gitee下载：

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

2.4 安装驱动

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版本编译后的驱动程序。请尝试从源码编译。

2.5 卸载驱动

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

sudo ./uninstall_driver.sh veye_gxcam

2.6 系统状态验证

以GX-MIPI-IMX662为例：

dmesg | grep gxcam

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

camera is: GX-MIPI-IMX662

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

Note:触发脚本链接。

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

在这里，我们提供了一个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来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。

4 树莓派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

5 实时预览

使用qv4l2播放，或者我们提供的veye_viewer

5.1 使用qv4l2播放图像

首先安装qv4l2

sudo apt install qv4l2

注：执行qv4l2播放图像前先执行

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

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

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

Play mv camera using qv4l2 on RPI

5.2 使用veye_viewer播放图像

veye_viewer是一个开源的，基于QT5的客户端软件。

代码以及使用请参考：https://github.com/veyeimaging/veye_viewer。

国内用户可访问gitee仓库。

6 Gstreamer应用范例

export DISPLAY=:0

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

6.2 运行 gstreamer videotest 命令

gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink

6.3 抓拍一张图片(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

6.4 帧率测试(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

6.5 视频预览(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

或者：

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 ! autovideosink sync=false -v

6.6 视频预览并加时间戳显示(GX-MIPI-IMX662 @1080p mode)

gst-launch-1.0 v4l2src device=/dev/video0 ! "video/x-raw,format=UYVY, width=1920, height=1080,framerate=30/1" ! videoconvert ! videoscale ! clockoverlay time-format="%D %H:%M:%S" ! video/x-raw, width=640, height=360 ! autovideosink sync=false -v

/////////264相关没测，缺少v4l2h264enc

6.7 h.264编码并保存为mkv文件(VEYE-MIPI-X,CS-MIPI-IMX307 @1080p mode)

gst-launch-1.0 -e v4l2src io-mode=dmabuf device=/dev/video0 num-buffers=300 ! "video/x-raw,format=(string)UYVY, width=(int)1920, height=(int)1080,framerate=(fraction)30/1" ! v4l2h264enc capture-io-mode=dmabuf output-io-mode=dmabuf extra-controls="controls, h264_profile=4, video_bitrate=6200000" ! 'video/x-h264, profile=high, level=(string)4' ! h264parse ! matroskamux ! filesink location=output.mkv

6.8 h.264编码并保存为mp4文件(VEYE-MIPI-X,CS-MIPI-IMX307 @1080p mode)

gst-launch-1.0 -e v4l2src io-mode=dmabuf device=/dev/video0  num-buffers=300 ! "video/x-raw,format=(string)UYVY, width=(int)1920, height=(int)1080,framerate=(fraction)30/1" ! v4l2h264enc capture-io-mode=dmabuf output-io-mode=dmabuf extra-controls="controls, h264_profile=4, video_bitrate=6200000" ! 'video/x-h264, profile=high, level=(string)4' ! h264parse ! mp4mux ! filesink location=video.mp4

6.9 网络传输 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即可。

7 v4l2-ctl 应用范例

7.1 安装v4l2-utils

$ sudo apt-get install v4l-utils

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

7.3 列出相机支持的数据格式

v4l2-ctl --list-formats-ext

ioctl: VIDIOC_ENUM_FMT

        Type: Video Capture

        [0]: 'GREY' (8-bit Greyscale)

                Size: Discrete 3088x2064

        [1]: 'Y10P' (10-bit Greyscale (MIPI Packed))

                Size: Discrete 3088x2064

        [2]: 'Y10 ' (10-bit Greyscale)

                Size: Discrete 3088x2064

        [3]: 'Y12P' (12-bit Greyscale (MIPI Packed))

                Size: Discrete 3088x2064

        [4]: 'Y12 ' (12-bit Greyscale)

                Size: Discrete 3088x2064

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

7.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实现。

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

7.4.1 配置触发模式

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

0：流模式

1：普通触发模式

4：多相机同步模式

7.4.2 配置触发源

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

0: 软触发

1: 硬触发

7.4.3 软触发一次

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

7.4.4 设置帧率

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

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

7.5 触发模式

7.5.1 软触发模式

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

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

7.5.1.3 进行软触发操作

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

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

7.5.2 硬触发模式

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

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

7.5.2.1 硬件连接

MV camera hardware trigger connection

7.5.2.2 设置模式

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

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

7.5.2.3 开始取图

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

7.5.2.4 进行硬触发操作

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

$ python gpio_trigger.py

Note:触发脚本链接。

7.6 流模式

7.6.1 设置帧率

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

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

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

7.7 同步模式

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

7.7.1 设置同步模式

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

7.7.2 设置主从相机

主相机：

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

从相机：

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

7.7.3 开始取图

可采用流模式中的几种方式取图。

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

由于Raspberry Pi为图像申请的内存，宽度为32对齐，高度为16对齐，所以3088*2064的图像将被保存为3104*2064大小。

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 gx辅助工具

10.1 下载软件包

git clone git@github.com:veyeimaging/raspberrypi_v4l2.git

增加可执行权限

$ cd raspberrypi_v4l2/gx_i2c_tools

$ chmod +x -R ./*

10.2 软件包主要内容介绍

gx_mipi_i2c.sh：通过i2c协议读取和设置相机参数的脚本。

veye_gx_upgrade：相机固件升级工具。

相机上电后，可以执行：

$ i2cdetect -y 10

出现0x3b的设备，则表明相机已启动，并且i2c通道正常工作。

10.2.1 进行硬触发操作

$ python gpio_trigger.py

11 shell脚本进行参数配置

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

https://github.com/veyeimaging/raspberrypi_v4l2/tree/main/gx_i2c_tools

gx_mipi_i2c.sh user guide

12 参考资料

• 树莓派系统的安装

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

13.1 初始化阶段

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

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

13.2 工作阶段

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

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

13.3 参数配置

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

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

14 树莓派官方对于压缩格式和未压缩格式的解释

14.1 压缩格式

这种压缩格式在存储像素数据时所占用的空间更少。

在 Raspberry Pi 4 及更早版本的设备上，这种封装格式是按照 MIPI CSI-2 标准来对像素进行封装的。这意味着：

10 位相机模式将 4 个像素压缩成 5 个字节。前 4 个字节包含每个像素的 8 个最高有效位（MSB），最后一个字节包含两个像素的 4 对最低有效位（LSB）。

12 位相机模式将 2 个像素压缩成 3 个字节。前 2 个字节包含每个像素的 8 个最高有效位（MSB），最后一个字节包含两个像素的 4 个最低有效位（LSB）。

在 Raspberry Pi 5 及更高版本的设备上，压缩格式会采用一种视觉上无损的压缩方案将像素值压缩为每个像素 8 位（1 个字节）。

14.2 未压缩格式

这种未压缩的格式提供了更便于手动操作的像素值，但代价是需要占用更多的存储空间来保存像素数据。

在所有设备上，未压缩格式每像素使用 2 个字节。

在 Raspberry Pi 4 及更早版本的设备上，应用程序会在最左侧应用零填充。在未解包格式中，10 位相机模式下的一个像素值不能超过 1023。

在 Raspberry Pi 5 及更高版本的设备上，应用程序会在最低有效位处进行零填充，因此图像能够充分利用传感器提供的像素深度的完整 16 位动态范围。

15 问题反馈

我们致力于为嵌入式平台的图像应用提供更丰富的可能性。因此，我们在嵌入式平台的软件基于开源的原则而进行。

如对我们现有软件有任何的问题、建议，欢迎提交到论坛:,或者给我们的技术人员发邮件xumm#csoneplus.com。

16 本文修改记录

• 2025-12-06

第一个版本