GX Camera Application Development Guide on Rochchip/zh
GX系列摄像头模组在Rockchip平台的应用层使用和开发指南
1 概述
本文档适用于驱动已正确安装、硬件连接无误，且相机已经正确识别的场景。
本文主要达成一下目的：
- 查询已接入的 GX 系列摄像头的设备信息；
- 完成摄像头工作模式的设置和准备；
- 介绍几种预览、抓图的方法；
- 介绍参数配置方法；
- 对客户二次开发进行指引。
对于rockchip平台，无论使用哪种方法调用相机，均需完成设备探测和media-ctl配置格式的步骤，才可以进行后续操作。所以下面首先介绍设备探测和media-ctl配置。
注意，veye_viewer客户端已经内置了设备探测和media-ctl配置功能。因此，在完成驱动安装和硬件连接确认之后，可以直接参考后文所述veye_viewer客户端章节预览相机图像。
2 设备检测并配置环境变量
在这里，我们提供了两个脚本，可以自动检索相机的一些信息。
2.1 probe_camera_info-rk.sh
该脚本用于探测已连接并成功注册的摄像头设备，检索设备对应的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称等底层信息。
执行后，将在当前目录生成 auto_camera_index.json 文件并在文件中记录检索到的信息。
下面是一个例子：
$ ./probe_camera_info-rk.sh
cat auto_camera_index.json
[
{
"media_node": "/dev/media0",
"video_node": "/dev/video0",
"video_subnode": "/dev/v4l-subdev2",
"media_entity_name": "m00_b_gxcam 7-003b",
"i2c_bus": "7"
}
]
{}内是一个摄像头的信息，如果主板支持多个摄像头模组，则会出现多组{}包含的内容。
摄像头信息解释如下：
| 代称 | 名称 | 作用 | 何处使用 |
|---|---|---|---|
| media_node | 媒体设备节点 (Media device node) | 用于访问 media-controller 框架中的设备 | 由media-ctl命令配置分辨率和格式时使用 |
| video_node | 视频设备节点(Video capture device node) | 典型 V4L2 视频设备 | v4l2-ctl或者客户开发的程序，获取图像时使用 |
| video_subnode | 视频子设备节点（V4L2 sub-device node） | 配置摄像头的部分参数时使用 | v4l2-ctl命令使用 |
| media_entity_name | 设备名称（Media entity name） | 描述设备的名称,例如 "m00_b_gxcam 7-003b"
|
由media-ctl命令配置分辨率和格式时使用 |
| i2c_bus | I²C 总线号 | 表示设备连接的 I²C 总线编号 | 对摄像头进行参数配置的底层通信信道，gx_mipi_i2c.sh脚本使用 |
后文中使用的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称，均可参考此探测脚本得到的json文件中的信息进行替换。
2.2 gx_probe.sh
使用gx_probe.sh脚本，可以将某一个相机对应的I²C总线编号、相机型号、宽、高、帧率等信息配置到环境变量中。
如此，则方便后续使用media-ctl配置格式使用起来更方便。
使用方法是：
$ source ./gx_probe.sh i2c_bus
一个典型的输出如下：
$ source ./gx_probe.sh 7
Found veye_gxcam camera on i2c-7.
Setenv I2C_BUS = 7
Setenv CAMERAMODEL = GX-MIPI-IMX662
Setenv FPS = 60
Setenv WIDTH = 1920
Setenv HEIGHT = 1080
可以通过 echo $CAMERAMODEL来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。
3 使用media-ctl配置格式
3.1 使用media-ctl查看拓扑结构
使用media-ctl指令，可以清晰的展现出当前的拓扑结构。
media-ctl -p -d /dev/media0
3.1.1 链接关系
gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)
应用程序可以通过/dev/video0节点获取图像。
3.1.2 gx camera entity信息
以GX-MIPI-IMX662为例：
- entity 63: m00_b_gxcam 7-003b (1 pad, 1 link)
type V4L2 subdev subtype Sensor flags 0
device node name /dev/v4l-subdev2
pad0: Source
[fmt:UYVY8_2X8/1920x1080@10000/600000 field:none colorspace:rec709
crop:(0,0)/1920x1080]
-> "rockchip-csi2-dphy0":0 [ENABLED]
可以看到：
- 该Entity完整的名称是：
m00_b_gxcam 7-003b。（在ROC-RK3566-PC上该Entity名称是m00_b_gxcam 4-003b）。 - 它是一个 V4L2 subdev (Sub-Device) Sensor。
- 它对应的节点是
/dev/v4l-subdev2，应用程序（如v4l2-ctl）可以打开它，并进行配置。 - 它的输出格式是 [
UYVY8_2X8/1920x1080@10000/600000 field:none] ，其中UYVY8_2X8是一种mbus-code的简写，下一小节会列出支持的mbus-code。 - 当前分辨率是
1920x1080。 - 当前帧间隔是
10000/600000,即帧率是60。
摄像机输出的数据格式，可以通过media-ctl指令修改。
3.2 相机支持的mbus-code
GX系列相机使用UYVY数据格式能力，具体请参考每个型号的相机的数据手册。
| Format on datasheet | mbus-code for media-ctl | FourCC pixelformat for v4l2-ctl |
|---|---|---|
| UYVY | UYVY8_2X8 | UYVY |
3.3 使用media-ctl配置图像格式
可以通过下面的命令，配置摄像机的数据格式，分辨率，帧率。
media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'
其中："m00_b_gxcam 7-003b"指的相机的entity完整名称，UYVY8_2X8为mbus-code，'"$WIDTH"'x'"$HEIGHT"'指明了分辨率，1/'"$FPS"'指明了帧率。
比如，对于GX-MIPI-IMX662,这个命令经过变量替换后的结果是：
$ media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'
不仅可以在一个命令中同时配置数据格式，分辨率，帧率，也可以单独修改某一项或某几项。
注意，media-ctl中的各个node名称，均可参考前述json文件的内容调整，以配置不同的摄像头。
4 veye_viewer客户端
veye_viewer是一个基于QT的开源的客户端软件，可以方便客户进行相机评测、参数配置。另外其操作日志、寄存器清单以及开源的特性，方便客户进行参考，二次开发。
可通过veye_viewer下载源码，或在其发行版中直接下载对应平台的可执行程序。
5 yavta应用范例
5.1 yavta安装
git clone git://git.ideasonboard.org/yavta.git
$ cd yavta;make
5.2 保存图片到文件
配置完数据格式，分辨率，帧率之后，执行：
./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0
6 将相机数据导入OpenCV的范例
$ sudo apt install python3-opencv
详见github上的samples目录。
$ python3 ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7
注意需要使用合适的参数来执行上述程序。
7 gstreamer应用范例
我们提供了几个gstreamer例程，实现了预览功能。详见github上的samples目录。
8 v4l2-ctl应用范例
下面以/dev/v4l-subdev2 /dev/media0 /dev/video0 为例子，介绍直接用命令行配置相机和获取图像的方式。
8.1 安装v4l2-utils
sudo apt-get install v4l-utils
8.2 使用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
可以使用下面的方法设置和获取参数。
v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl [ctrl_type]=[val]
v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]
以上所有功能，均可使用gx_mipi_i2c.sh实现。
需要指出的是，以上参数在取图过程中均不可修改。下面进行逐个说明：
8.2.1 配置触发模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=[0-2]
0：流模式
1：普通触发模式
4：多相机同步模式
8.2.2 配置触发源
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=[0-1]
0: 软触发
1: 硬触发
8.2.3 软触发一次
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1
8.2.4 设置帧率
v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=[1-max]
随分辨率的调整，最大帧率会自动更新。
8.3 流模式
8.3.1 设置数据格式，分辨率，帧率
media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'
8.3.2 帧率统计
v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null
或者
./yavta -c-1 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0
8.3.3 保存图片到文件
- UYVY格式
v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-${WIDTH}x${HEIGHT}.yuv
图片格式请参考前面章节的描述。
8.4 触发模式
8.4.1 设置数据格式，分辨率，帧率
media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'
例：$ media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60]'
8.4.2 软触发模式
8.4.2.1 设置模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=1
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=0
8.4.2.2 开始取图
v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-${WIDTH}x${HEIGHT}.yuv
8.4.2.3 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1
8.4.3 硬触发模式
8.4.3.1 设置模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=1
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=1
可以使用gx_mipi_i2c.sh脚本进行丰富的触发参数设置。
8.4.3.2 开始取图
v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-${WIDTH}x${HEIGHT}.yuv
8.4.3.3 进行硬触发操作
将合适的触发信号连接到摄像机的trigger引脚并进行触发。
8.5 同步模式
下面的各node和subdev要根据实际情况区分。
8.5.1 设置数据格式，分辨率，帧率
media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'
8.5.2 设置同步模式
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work_mode=4
8.5.3 设置主从相机
主相机：
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=0
从相机：
$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=1
8.5.4 开始取图
同步模式下的取图方式与视频流模式下完全一致。
9 i2c脚本使用说明
我们提供了shell脚本来配置参数。
10 客户集成开发的几点建议
10.1 初始化阶段
需要完成分辨率、帧率的配置。建议客户在程序初始化阶段，直接集成media-ctl和v4l2-ctl命令的调用，完成分辨率帧率以及数据格式的配置。
不要使用gx_mipi_i2c.sh直接设置相机寄存器，因为直接设置相机寄存器的话，Rockchip的linux驱动层次并不能同步到设置值。
在Rockchip平台，对于一个指定的主板，./probe_camera_info-rk.sh所探测到的节点是固定不变的。建议客户直接使用此脚本输出的json文件作为自己程序的配置文件。
客户也可以以此脚本的输出作为参考直接在代码中写死节点名称。
10.2 工作阶段
客户根据自己开发语言的不同，可以参考本文前述的代码、工具。
关于时间戳，v4l2_buffer.timestamp会带有RK芯片接收到一个完整数据帧的准确时间，可以用于做相机同步或者与其他外部传感器同步的参考时间戳。
10.3 参数配置
GX系列相机的参数非常丰富和灵活，主要使用gx_mipi_i2c.sh直接进行寄存器配置的方式实现。具体请参考寄存器文档和gx_mipi_i2c.sh的说明文档。
gx_mipi_i2c.sh具有paramsave功能，作用是将客户所有的配置参数保存的相机flash中，但是不建议客户在程序中频繁调用。
11 本文修改记录
- 2025-12-06
调试文档结构，增加一些章节。
- 2025-11-28
第一个版本。