GX Camera Application Development Guide on Raspberry/zh
1 状态检测并配置环境变量
在这里，我们提供了一个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来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。
2 树莓派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
3 实时预览
使用qv4l2播放，或者我们提供的veye_viewer
3.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. 点击 ▶（播放）按钮以调出打开的媒体窗口。
3.2 使用veye_viewer播放图像
veye_viewer是一个开源的，基于QT5的客户端软件。
代码以及使用请参考：https://github.com/veyeimaging/veye_viewer。
国内用户可访问gitee仓库。
4 Gstreamer应用范例
export DISPLAY=:0
4.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
4.2 运行 gstreamer videotest 命令
gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink
4.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
4.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
4.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
4.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
4.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
4.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
4.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即可。
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配置参数
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.4.1 配置触发模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=[0-2]
0：流模式
1：普通触发模式
4：多相机同步模式
5.4.2 配置触发源
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=[0-1]
0: 软触发
1: 硬触发
5.4.3 软触发一次
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1
5.4.4 设置帧率
v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=[1-max]
随分辨率的调整，最大帧率会自动更新。
5.5 触发模式
5.5.1 软触发模式
5.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
5.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"
5.5.1.3 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1
5.5.2 硬触发模式
下面以使用树莓派GPIO21为模拟触发源，上升沿触发为例。
可以使用gx_mipi_i2c.sh脚本进行丰富的触发参数设置。
5.5.2.1 硬件连接
5.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
5.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"
5.5.2.4 进行硬触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
$ python gpio_trigger.py
Note:触发脚本链接。
5.6 流模式
5.6.1 设置帧率
v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=$FPS
5.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
5.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
5.7 同步模式
下面的subdev要根据实际情况区分。
5.7.1 设置同步模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=4
5.7.2 设置主从相机
主相机：
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=0
从相机：
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=1
5.7.3 开始取图
可采用流模式中的几种方式取图。
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 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大小。
7 使用opencv获取图片
7.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。
8 gx辅助工具
8.1 下载软件包
git clone git@github.com:veyeimaging/raspberrypi_v4l2.git
增加可执行权限
$ cd raspberrypi_v4l2/gx_i2c_tools
$ chmod +x -R ./*
8.2 软件包主要内容介绍
camera_i2c_config：自动识别不同的树莓派板型，并控制power on 引脚给摄像机供电。
veye_raspipreview：实现图像预览、图片保存等功能。
gx_mipi_i2c.sh：通过i2c协议读取和设置相机参数的脚本。
veye_gx_upgrade：相机固件升级工具。
8.3 相机上电
$ ./camera_i2c_config
相机上电后，可以执行：
$ i2cdetect -y 10
出现0x3b的设备，则表明相机已启动，并且i2c通道正常工作。
8.4 视频预览
$ ./veye_raspipreview -t -1 -md 0
其中 -md指明像素数据格式：
| -md option | data type |
|---|---|
| 0 | 8bit Y |
| 1 | 10bit Y |
| 2 | 12bit Y |
8.5 保存图片
$ ./veye_raspipreview -t 1000 -md 0 -sr 10 -o /dev/shm/uyvy-1920x1080_%04d.yuv
-sr是存储图片的间隔，这里每间隔10张图片保存一张。
-t 1000，单位是ms，这里表示1秒。
完成后在/dev/shm/目录下会保存下几个文件。
8.6 触发模式
本章节需要使用gx_mipi_i2c.sh，请参考下面相关i2c参数配置方法章节。
8.6.1 软触发
8.6.1.1 设置模式
$ ./gx_mipi_i2c.sh -w -f trgmode -p1 1
$ ./gx_mipi_i2c.sh -w -f trgsrc -p1 0
8.6.1.2 设置触发属性
可以设置触发数量，触发间隔等。下面设置单次触发5张，每张间隔1毫秒。
$ ./gx_mipi_i2c.sh -w -f trgnum -p1 5
$ ./gx_mipi_i2c.sh -w -f trginterval -p1 1000
8.6.1.3 开始取图
$ ./veye_raspipreview -t -1 -md 0
8.6.1.4 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
$ ./gx_mipi_i2c.sh -w -f trgone
8.6.2 硬触发
8.6.2.1 设置模式
本次以普通触发为例
$ ./gx_mipi_i2c.sh -w -f trgmode -p1 1
$ ./gx_mipi_i2c.sh -w -f trgsrc -p1 1
8.6.2.2 设置触发属性
设置触发数量为2张。
$ ./gx_mipi_i2c.sh -w -f trgnum -p1 2
设置上升沿触发
$ ./gx_mipi_i2c.sh -w -f trgedge -p1 0
此外，还可以对硬触发设置丰富的触发属性，如触发延迟、信号过滤等。
8.6.2.3 开始取图
$ ./veye_raspipreview -t -1 -md 0
8.6.2.4 进行硬触发操作
$ python gpio_trigger.py