Gx series camera appnotes 4 rpi/zh
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 |
|---|---|
2.1.2 供电
ADP-MV1需要独立的5V供电，可以使用杜邦线直接从树莓派主板取电。
2.1.3 树莓派5
二者使用15P转22P的FFC同面线连接，注意接触面安装方向。
| TOP | BOTTOM |
|---|---|
2.1.4 树莓派Model B和Model B+
二者使用1mm间距*15P的FFC异面线连接，注意接触面安装方向。
2.1.5 树莓派Zero,Zero W和Computer Module
二者使用15P转22P的FFC同面线连接，注意接触面安装方向。
2.2 RAW系列摄像头连接到树莓派
2.2.1 树莓派5
RAW-MIPI-SC132M使用15to22pin同面FFC线，其他RAW系列相机使用22pin异面FFC线。
2.2.2 树莓派Model B和Model B+
RAW-MIPI-SC132M使用15pin异面FFC线，其他RAW系列相机使用15to22pin同面FFC线。
2.2.3 树莓派Zero,Zero W和Computer Module
RAW-MIPI-SC132M使用15to22pin同面FFC线，其他RAW系列相机使用22pin异面FFC线。
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 节点存在，证明摄像头状态正常。
2.7 veye_viewer
veye_viewer是一个开源的，基于QT5的客户端软件。
代码以及使用请参考：https://github.com/veyeimaging/veye_viewer。
国内用户可访问gitee仓库。
2.8 状态检测并配置环境变量
在这里，我们提供了一个gx_probe.sh脚本，用于自动检测识别到的相机并将相机默认的型号、宽、高、帧率等信息配置到环境变量中。
使用方法是：
source ./gx_probe.sh
一个典型的输出如下：
$ source ./gx_probe.sh
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来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。
2.9 树莓派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
2.9.1 实时预览
使用qv4l2播放，或者我们提供的veye_viewer
2.9.1.1 使用qv4l2播放图像
首先安装qv4l2
sudo apt install qv4l2
1. 在命令行中输入qv4l2以启动 V4L2 播放器。
2. 点击 ▶（播放）按钮以调出打开的媒体窗口。
2.9.1.2 使用veye_viewer播放图像
veye_viewer工具下载
3 Gstreamer应用范例
export DISPLAY=:0
3.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
3.2 运行 gstreamer videotest 命令
gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink
3.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
3.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
3.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
3.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
3.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
3.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
3.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即可。
4 使用opencv获取图片
pip uninstall opencv-python
sudo apt install python3-opencv
5 v4l2-ctl 应用范例
5.1 安装v4l2-utils
sudo apt-get install v4l-utils
5.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
5.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，实际支持的图像格式取决于相机能力，而不是此处的列表。
5.4 列出驱动中实现的相机的可配置参数
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实现。
需要指出的是，以上参数在开始取图的状态均不可修改。下面进行逐个说明：
5.5 配置工作模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=[0-2]
0：流模式
1：普通触发模式
4：多相机同步模式
5.5.1 触发模式
本节以IMX662为例，讲述一下触发模式的配置和使用。其他摄像头，参考流模式的宽高推论即可。
5.5.2 设置帧率
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=$FPS
5.5.3 软触发模式
5.5.3.1 设置模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=1
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=0
5.5.3.2 开始取图
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=5 --stream-to="uyvy-${WIDTH}x${HEIGHT}.yuv"
5.5.3.3 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1
5.5.4 硬触发模式
下面以使用树莓派GPIO21为模拟触发源，上升沿触发为例。
可以使用mv_mipi_i2c.sh脚本进行丰富的触发参数设置。
5.5.4.1 硬件连接
5.5.4.2 设置模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=1
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=1
5.5.4.3 开始取图
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=5 --stream-to="uyvy-${WIDTH}x${HEIGHT}.yuv"
5.5.4.4 进行硬触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
python gpio_trigger.py
Note:触发脚本链接。
5.5.5 流模式
5.5.5.1 设置帧率
v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=$FPS
5.5.5.2 可使用如下命令进行帧率统计
v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null
5.5.5.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"
6 yavta 应用范例
6.1 下载并编译yavta
git clone git://git.ideasonboard.org/yavta.git
cd yavta;make
6.2 yavta 例程
./yavta -c1 -F"y8-${WIDTH}x${HEIGHT}.yuv" --skip 0 -f Y8 -s "${WIDTH}x${HEIGHT}" /dev/video0
例$ ./yavta -c8 -Fuyvy_1920X1080.yuv --skip 0 -f UYVY -s 1920x1080 /dev/video0
由于Raspberry Pi为图像申请的内存，宽度为32对齐，高度为16对齐，所以3088*2064的图像将被保存为3104*2064大小。
6.2.1 使用opencv预览GREY格式图像
- install opencv
pip uninstall opencv-python
sudo apt install python3-opencv
- 我们提供了一个简单的sample实现此功能：
python ./v4l2dev_2_opencv_show_grey.py --width 640 --height 480 --fps 30
对于树莓派5，需要增加一个--ctldev /dev/v4l-subdev*参数用于指明配置参数的subdev。
7 使用opencv获取图片
pip uninstall opencv-python
sudo apt install python3-opencv
为了将摄像头数据从v4l2设备导入到opencv，我们提供了几个sample。
7.1 CM4的补充说明
cm4支持两路摄像头同时使用,采用上面的步骤安装的dtbo将只能使用CAM1。如需使用两路摄像头，请按如下步骤：
7.1.1 硬件连接
参考树莓派这个说明，将J6进行短接。
7.1.2 更新dt-blob.bin
sudo wget https://datasheets.raspberrypi.com/cmio/dt-blob-dualcam.bin -O /boot/dt-blob.bin
7.1.3 对于Buster系统（kernel5.10）
更新双摄像头的dtbo，
以mvcam为例：
sudo cp raspberrypi_v4l2/release/driver_bin/$(uname -r)/veye_mvcam-cm4.dtbo /boot/overlays/veye_mvcam.dtbo
sudo reboot
7.1.4 对于Bullseye系统（kernel5.15+）
手动编辑/boot/config.txt文件，增加一行dtoverlay=[camera],cam0，如下所示：
[all]
dtparam=i2c_vc=on
dtoverlay=veye_mvcam
dtoverlay=veye_mvcam,cam0
7.1.5 设备文件说明
CM4模块采用两路I2C分别与两个摄像头通信。
| description | i2c bus num | lane num | video node |
|---|---|---|---|
| CAM0 | 0 | 2lane | video0 |
| CAM1 | 10 | 2lane or 4lane | video2（Buster），video1（Bullseye） |
注：只连一个摄像头，无论CAM0还是CAM1，都是video0。
7.2 从源代码编译驱动方法
请参考：树莓派平台上摄像头驱动源码编译指南。
7.3 下载软件包
git clone git@github.com:veyeimaging/raspberrypi_v4l2.git
增加可执行权限
cd raspberrypi_v4l2/gx_i2c_tools
chmod +x -R ./*
7.4 软件包主要内容介绍
camera_i2c_config：自动识别不同的树莓派板型，并控制power on 引脚给摄像机供电。
veye_raspipreview：实现图像预览、图片保存等功能。
gx_mipi_i2c.sh：通过i2c协议读取和设置相机参数的脚本。
veye_gx_upgrade：相机固件升级工具。
7.5 相机上电
./camera_i2c_config
相机上电后，可以执行：
i2cdetect -y 10
出现0x3b的设备，则表明相机已启动，并且i2c通道正常工作。
7.6 视频预览
./veye_raspipreview -t -1 -md 0
其中 -md指明像素数据格式：
| -md option | data type |
|---|---|
| 0 | 8bit Y |
| 1 | 10bit Y |
| 2 | 12bit Y |
7.7 保存图片
./veye_raspipreview -t 1000 -md 0 -sr 10 -o /dev/shm/y8-3104x2064_%04d.raw
-sr是存储图片的间隔，这里每间隔10张图片保存一张。
-t 1000，单位是ms，这里表示1秒。
完成后在/dev/shm/目录下会保存下几个文件。
7.8 触发模式
本章节需要使用gx_mipi_i2c.sh，请参考下面相关i2c参数配置方法章节。
7.8.1 软触发
7.8.1.1 设置模式
./gx_mipi_i2c.sh -w -f trgmode -p1 1
./gx_mipi_i2c.sh -w -f trgsrc -p1 0
7.8.1.2 设置触发属性
可以设置触发数量，触发间隔等。下面设置单次触发5张，每张间隔1毫秒。
./gx_mipi_i2c.sh -w -f trgnum -p1 5
./gx_mipi_i2c.sh -w -f trginterval -p1 1000
7.8.1.3 开始取图
./veye_raspipreview -t -1 -md 0
7.8.1.4 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
./gx_mipi_i2c.sh -w -f trgone
7.8.2 硬触发
7.8.2.1 设置模式
本次以普通触发为例
./gx_mipi_i2c.sh -w -f trgmode -p1 1
./gx_mipi_i2c.sh -w -f trgsrc -p1 1
7.8.2.2 设置触发属性
设置触发数量为2张。
./gx_mipi_i2c.sh -w -f trgnum -p1 2
设置上升沿触发
./gx_mipi_i2c.sh -w -f trgedge -p1 0
此外，还可以对硬触发设置丰富的触发属性，如触发延迟、信号过滤等。
7.8.2.3 开始取图
./veye_raspipreview -t -1 -md 0
7.8.2.4 进行硬触发操作
python gpio_trigger.py
Note:触发脚本链接。
7.9 CM4的补充说明
关于硬件连接、dtbo以及i2cbus的描述，请参考前面的章节。
7.9.1 mv_raspicam分别访问两个camera的方法：
- 预览CAM0
./veye_raspipreview -t -1 -c 0 -y 0
- 预览CAM1
./veye_raspipreview -t -1 -c 1 -y 10
7.10 树莓派官方对于Packed format和Unpacked format的解释
7.10.1 Packed format details
The packed format uses less storage for pixel data.
On Raspberry Pi 4 and earlier devices, the packed format packs pixels using the MIPI CSI-2 standard. This means:
- 10-bit camera modes pack 4 pixels into 5 bytes. The first 4 bytes contain the 8 most significant bits (MSBs) of each pixel, and the final byte contains the 4 pairs of least significant bits (LSBs).
- 12-bit camera modes pack 2 pixels into 3 bytes. The first 2 bytes contain the 8 most significant bits (MSBs) of each pixel, and the final byte contains the 4 least significant bits (LSBs) of both pixels.
On Raspberry Pi 5 and later devices, the packed format compresses pixel values with a visually lossless compression scheme into 8 bits (1 byte) per pixel.
7.10.2 Unpacked format details
The unpacked format provides pixel values that are much easier to manually manipulate, at the expense of using more storage for pixel data.
On all devices, the unpacked format uses 2 bytes per pixel.
On Raspberry Pi 4 and earlier devices, applications apply zero padding at the most significant end. In the unpacked format, a pixel from a 10-bit camera mode cannot exceed the value 1023.
On Raspberry Pi 5 and later devices, applications apply zero padding at the least significant end, so images use the full 16-bit dynamic range of the pixel depth delivered by the sensor.
8 shell脚本进行参数配置
我们提供了shell脚本来配置参数。
https://github.com/veyeimaging/raspberrypi_v4l2/tree/main/mv_tools_rpi
9 参考资料
10 问题反馈
我们致力于为嵌入式平台的图像应用提供更丰富的可能性。因此，我们在嵌入式平台的软件基于开源的原则而进行。
如对我们现有软件有任何的问题、建议，欢迎提交到论坛:,或者给我们的技术人员发邮件xumm#csoneplus.com。
11 本文修改记录
- 2022-04-14
第一个版本