Difference between revisions of "GX Camera Application Development Guide on Rochchip/zh"

From wiki_veye
Jump to navigation Jump to search
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
==== 概述 ====
+
[[GX Camera Application Development Guide|English]]
−
本文档适用于 驱动已正确安装、硬件连接无误 的场景，旨在指导用户完成以下操作：
 
  
−
* 查询已接入 GX 系列摄像头的设备信息；
+
'''<big>GX系列摄像头模组在Rockchip平台的应用层使用和开发指南</big>'''
−
* 识别对应的媒体设备、视频节点及 I²C 总线；
 
−
* 根据需求选择合适的图像采集模式（流模式、触发模式、同步模式）；
 
−
* 配置分辨率、帧率、数据格式等关键参数。
 
  
−
通过配套脚本和标准 V4L2 工具（如 <code>v4l2-ctl</code>、<code>media-ctl</code>、<code>yavta</code> 等）或veye_viewer工具，用户可快速完成设备探测、环境配置与图像采集全流程。
+
===概述===
 +
本文档适用于驱动已正确安装、硬件连接无误，且相机已经正确识别的场景。
  
−
====状态检测并配置环境变量====
+
本文主要达成一下目的：
−
在[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/gx_tools 这里]，我们提供了两个脚本，可以自动检索下相机的一些信息。
 
  
−
首先试用 probe_camera_info-rk.sh脚本，该脚本用于探测已连接并成功注册的摄像头设备，检索设备对应的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备标识等底层信息。执行后，将在当前目录生成 <code>auto_camera_index.json</code> 文件并在文件中记录检索到的信息。
+
*查询已接入的 GX 系列摄像头的设备信息；
 +
*完成摄像头工作模式的设置和准备；
 +
*介绍几种预览、抓图的方法；
 +
*介绍参数配置方法；
 +
*对客户二次开发进行指引。
 +
 
 +
'''对于rockchip平台，无论使用哪种方法调用相机，均需完成设备探测和<code>media-ctl</code>配置格式的步骤，才可以进行后续操作。'''所以下面首先介绍设备探测和<code>media-ctl</code>配置。
 +
 
 +
注意，veye_viewer客户端已经内置了设备探测和<code>media-ctl</code>配置功能。'''因此，在完成驱动安装和硬件连接确认之后，可以直接参考后文所述veye_viewer客户端章节预览相机图像'''。
 +
 
 +
===设备检测并配置环境变量===
 +
在[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/gx_i2c_tools 这里]，我们提供了两个脚本，可以自动检索相机的一些信息。
 +
 
 +
====probe_camera_info-rk.sh====
 +
该脚本用于探测已连接并成功注册的摄像头设备，检索设备对应的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称等底层信息。
 +
 
 +
执行后，将在当前目录生成 <code>auto_camera_index.json</code> 文件并在文件中记录检索到的信息。
 +
 
 +
下面是一个例子：
  
 
<code>$ ./probe_camera_info-rk.sh</code>
 
<code>$ ./probe_camera_info-rk.sh</code>
Line 36: Line 50:
 
<code>]</code>
 
<code>]</code>
  
−
通过索引信息，我们可以看到"i2c_bus": "7"对应的i2c_bus信息，以及接入了多少台设备，当前索引显示只接入一台设备，并且i2c_bus号是7，如果接入多个设备，索引信息可能会有"i2c_bus": "10"，"i2c_bus": "11"等信息。
+
{}内是一个摄像头的信息，如果主板支持多个摄像头模组，则会出现多组{}包含的内容。
 +
 
 +
摄像头信息解释如下：
 +
{| class="wikitable"
 +
|+摄像头信息
 +
!代称
 +
!名称
 +
!作用
 +
!何处使用
 +
|-
 +
|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）
 +
|描述设备的名称,例如 <code>"m00_b_gxcam 7-003b"</code>
 +
|由media-ctl命令配置分辨率和格式时使用
 +
|-
 +
|i2c_bus
 +
|I²C 总线号
 +
|表示设备连接的 I²C 总线编号
 +
|对摄像头进行参数配置的底层通信信道，gx_mipi_i2c.sh脚本使用
 +
|}
 +
后文中使用的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称，均可参考此探测脚本得到的json文件中的信息进行替换。
 +
 
 +
====gx_probe.sh====
 +
使用<code>gx_probe.sh</code>脚本，可以将某一个相机对应的I²C总线编号、相机型号、宽、高、帧率等信息配置到环境变量中。
  
−
然后使用<code>gx_probe.sh</code>脚本，如果是多路相机，可以根据上一个脚本读出的i2c_bus执行，并将对应的相机型号、宽、高、帧率等信息配置到环境变量中。
+
如此，则方便后续使用media-ctl配置格式使用起来更方便。
  
 
使用方法是：
 
使用方法是：
  
−
<code>$ source ./gx_probe.sh 7</code>
+
<code>$ source ./gx_probe.sh i2c_bus</code>
  
 
一个典型的输出如下：
 
一个典型的输出如下：
Line 49: Line 101:
  
 
<code>Found veye_gxcam camera on i2c-7.</code>
 
<code>Found veye_gxcam camera on i2c-7.</code>
 +
 +
<code>Setenv I2C_BUS = 7</code>
  
 
<code>Setenv CAMERAMODEL = GX-MIPI-IMX662</code>
 
<code>Setenv CAMERAMODEL = GX-MIPI-IMX662</code>
Line 58: Line 112:
 
<code>Setenv HEIGHT = 1080</code>
 
<code>Setenv HEIGHT = 1080</code>
  
−
可以通过 <code>echo $CAMERAMODEL</code>来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。
+
可以通过 <code>echo $CAMERAMODEL</code>来验证环境变量的输出结果。'''注意，此环境变量只对当前会话有效。'''
−
 
 
−
====配置命令行全局变量 ====
 
−
根据主板型号，配置I2C_BUS全局变量。
 
−
 
 
−
* ROC-RK3588S-PC
 
−
 
 
−
<code>export I2C_BUS=7</code>
 
−
 
 
−
* ROC-RK3566-PC and ROC-RK3576-PC
 
  
−
<code>export I2C_BUS=4</code>
+
===使用media-ctl配置格式===
−
==== 使用media-ctl查看拓扑结构 ====
+
====使用media-ctl查看拓扑结构====
 
使用media-ctl指令，可以清晰的展现出当前的拓扑结构。
 
使用media-ctl指令，可以清晰的展现出当前的拓扑结构。
  
 
<code>media-ctl -p -d /dev/media0</code>
 
<code>media-ctl -p -d /dev/media0</code>
  
−
===== 链接关系 =====
+
=====链接关系=====
 
gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)
 
gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)
  
 
应用程序可以通过/dev/video0节点获取图像。
 
应用程序可以通过/dev/video0节点获取图像。
  
−
===== gx camera entity信息 =====
+
=====gx camera entity信息=====
 
以GX-MIPI-IMX662为例：
 
以GX-MIPI-IMX662为例：
  
Line 99: Line 144:
 
可以看到：
 
可以看到：
  
−
* 该Entity完整的名称是： <code>m00_b_gxcam 7-003b</code>。（在ROC-RK3566-PC上该Entity名称是<code>m00_b_gxcam 4-003b</code>）。
+
*该Entity完整的名称是： <code>m00_b_gxcam 7-003b</code>。（在ROC-RK3566-PC上该Entity名称是<code>m00_b_gxcam 4-003b</code>）。
−
* 它是一个 V4L2 subdev (Sub-Device) Sensor。
+
*它是一个 V4L2 subdev (Sub-Device) Sensor。
−
* 它对应的节点是 <code>/dev/v4l-subdev2</code> ，应用程序（如<code>v4l2-ctl</code>）可以打开它，并进行配置。
+
*它对应的节点是 <code>/dev/v4l-subdev2</code> ，应用程序（如<code>v4l2-ctl</code>）可以打开它，并进行配置。
−
* 它的输出格式是 [<code>UYVY8_2X8/1920x1080@10000/600000 field:none</code>] ，其中<code>UYVY8_2X8</code>是一种mbus-code的简写，下一小节会列出支持的mbus-code。
+
*它的输出格式是 [<code>UYVY8_2X8/1920x1080@10000/600000 field:none</code>] ，其中<code>UYVY8_2X8</code>是一种mbus-code的简写，下一小节会列出支持的mbus-code。
−
* 当前分辨率是<code>1920x1080</code> 。
+
*当前分辨率是<code>1920x1080</code> 。
−
* 当前帧间隔是<code>10000/600000</code>,即帧率是60。
+
*当前帧间隔是<code>10000/600000</code>,即帧率是60。
  
 
摄像机输出的数据格式，可以通过media-ctl指令修改。
 
摄像机输出的数据格式，可以通过media-ctl指令修改。
−
==== 相机支持的mbus-code ====
+
====相机支持的mbus-code====
 
GX系列相机使用UYVY数据格式能力，具体请参考每个型号的相机的数据手册。
 
GX系列相机使用UYVY数据格式能力，具体请参考每个型号的相机的数据手册。
 
{| class="wikitable"
 
{| class="wikitable"
Line 120: Line 165:
 
|}
 
|}
  
−
=== veye_viewer工具 ===
+
====使用media-ctl配置图像格式====
−
可通过[https://gitee.com/veyeimaging/veye_viewer veye_viewer]下载。
+
可以通过下面的命令，配置摄像机的数据格式，分辨率，帧率。
  
−
我们可以使用该工具对相机进行一些参数配置(对寄存器直接操作更改参数)，模式更换(流模式，触发模式，同步模式)，查看相机的一些基本信息(分辨率，帧率等)。
+
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
  
−
=== 应用范例 ===
+
其中：<code>"m00_b_gxcam 7-003b"</code>指的相机的<code>entity</code>完整名称，<code>UYVY8_2X8</code>为<code>mbus-code</code>，<code>'"$WIDTH"'x'"$HEIGHT"'</code>指明了分辨率，<code>1/'"$FPS"'</code>指明了帧率。
−
==== 使用v4l2-ctl配置参数 ====
 
−
注：<code>/dev/v4l-subdev2</code> <code>/dev/media0</code> <code>/dev/video0</code> 中的编号"2", "0", "0"是内核动态分配的，不代表固定设备。
 
  
 +
比如，对于GX-MIPI-IMX662,这个命令经过变量替换后的结果是：
 +
 +
<code>$ media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'</code>
 +
 +
不仅可以在一个命令中同时配置数据格式，分辨率，帧率，也可以单独修改某一项或某几项。
 +
 +
注意，media-ctl中的各个node名称，均可参考前述json文件的内容调整，以配置不同的摄像头。
 +
 +
===veye_viewer客户端===
 +
veye_viewer是一个基于QT的开源的客户端软件，可以方便客户进行相机评测、参数配置。另外其操作日志、寄存器清单以及开源的特性，方便客户进行参考，二次开发。
 +
 +
可通过[https://gitee.com/veyeimaging/veye_viewer veye_viewer]下载源码，或在其[https://gitee.com/veyeimaging/veye_viewer/releases 发行版]中直接下载对应平台的可执行程序。
 +
 +
===yavta应用范例===
 +
 +
====yavta安装====
 +
<code>git clone <nowiki>git://git.ideasonboard.org/yavta.git</nowiki></code>
 +
 +
<code>$ cd yavta;make</code>
 +
 +
====保存图片到文件====
 +
配置完数据格式，分辨率，帧率之后，执行：
 +
 +
<code>./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
 +
 +
===将相机数据导入OpenCV的范例===
 +
<code>$ sudo apt install python3-opencv</code>
 +
 +
详见github上的[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples/opencv/veye%20camera samples]目录。
 +
 +
<code>$ python3 ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7</code>
 +
 +
注意需要使用合适的参数来执行上述程序。
 +
 +
===gstreamer应用范例===
 +
我们提供了几个gstreamer例程，实现了预览功能。详见github上的[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples/gstreamer/veye_camera samples]目录。
 +
 +
===v4l2-ctl应用范例===
 +
下面以<code>/dev/v4l-subdev2</code>  <code>/dev/media0</code>  <code>/dev/video0</code> 为例子，介绍直接用命令行配置相机和获取图像的方式。
 +
 +
====安装v4l2-utils====
 +
<code>sudo apt-get install v4l-utils</code>
 +
====使用v4l2-ctl配置参数====
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 -L</code>  
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 -L</code>  
  
 
<code>User Controls</code>
 
<code>User Controls</code>
  
−
<code>                   work_mode 0x00981a01 (int)    : min=0 max=4 step=1 default=0 value=0 flags=volatile, execute-on-write</code>
+
<code>                   trigger_mode 0x00981a01 (int)    : min=0 max=4 step=1 default=0 value=0 flags=volatile, execute-on-write</code>
  
 
<code>                    trigger_src 0x00981a02 (int)    : min=0 max=1 step=1 default=1 value=1 flags=volatile, execute-on-write</code>
 
<code>                    trigger_src 0x00981a02 (int)    : min=0 max=1 step=1 default=1 value=1 flags=volatile, execute-on-write</code>
Line 149: Line 235:
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]</code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]</code>
  
−
以上所有功能，均可使用[https://wiki.veye.cc/index.php/Gx_mipi_i2c.sh_user_guide/zh gx_mipi_i2c.sh]实现。
+
以上所有功能，均可使用[[Gx mipi i2c.sh user guide/zh|gx_mipi_i2c.sh]]实现。
  
 
需要指出的是，以上参数在取图过程中均不可修改。下面进行逐个说明：
 
需要指出的是，以上参数在取图过程中均不可修改。下面进行逐个说明：
  
 
=====配置触发模式=====
 
=====配置触发模式=====
−
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>work_mode=[0-2]</small></code>
+
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=[0-2]</small></code>
  
 
0：流模式
 
0：流模式
Line 174: Line 260:
 
随分辨率的调整，最大帧率会自动更新。
 
随分辨率的调整，最大帧率会自动更新。
  
−
==== 使用media-ctl配置图像格式 ====
+
====流模式====
−
可以通过下面的命令，配置摄像机的数据格式，分辨率，帧率。
 
  
 +
=====设置数据格式，分辨率，帧率=====
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
  
−
其中：<code>"m00_b_gxcam 7-003b"</code>指的相机的<code>entity</code>完整名称，<code>UYVY8_2X8</code>为<code>mbus-code</code>，<code>'"$WIDTH"'x'"$HEIGHT"'</code>指明了分辨率，<code>1/'"$FPS"'</code>指明了帧率。
+
=====帧率统计=====
−
 
 
−
比如，对于GX-MIPI-IMX662,这个命令经过变量替换后的结果是：
 
−
 
 
−
<code>$ media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'</code>
 
−
 
 
−
不仅可以在一个命令中同时配置数据格式，分辨率，帧率，也可以单独修改某一项或某几项。
 
−
 
 
−
==== 流模式 ====
 
−
 
 
−
===== 设置数据格式，分辨率，帧率 =====
 
−
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
−
 
 
−
===== 帧率统计 =====
 
 
<code>v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null</code>
 
<code>v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null</code>
  
Line 199: Line 272:
 
<code>./yavta -c-1 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
 
<code>./yavta -c-1 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
  
−
===== 保存图片到文件 =====
+
=====保存图片到文件=====
  
−
* UYVY格式
+
*UYVY格式
  
 
<code>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</code>
 
<code>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</code>
Line 207: Line 280:
 
图片格式请参考前面章节的描述。
 
图片格式请参考前面章节的描述。
  
−
=====yavta应用范例=====
+
====触发模式====
−
 
+
=====设置数据格式，分辨率，帧率=====
−
====== yavta安装 ======
 
−
<code>git clone <nowiki>git://git.ideasonboard.org/yavta.git</nowiki></code>
 
−
 
 
−
<code>$ cd yavta;make</code>
 
−
 
 
−
====== 保存图片到文件 ======
 
−
配置完数据格式，分辨率，帧率之后，执行：
 
−
 
 
−
<code>./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
 
−
 
 
−
===== 将相机数据导入OpenCV的范例 =====
 
−
<code>$ sudo apt install python3-opencv</code>
 
−
 
 
−
详见github上的[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples samples]目录。
 
−
 
 
−
<code>$ python3 ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7</code>
 
−
 
 
−
注意需要使用合适的参数来执行上述程序。
 
−
 
 
−
===== gstreamer应用范例 =====
 
−
我们提供了几个gstreamer例程，实现了预览功能。详见github上的[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples samples]目录。
 
−
 
 
−
==== 触发模式 ====
 
−
===== 设置数据格式，分辨率，帧率 =====
 
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
  
Line 238: Line 287:
 
=====软触发模式=====
 
=====软触发模式=====
 
======设置模式======
 
======设置模式======
−
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>work_mode=1</small></code>
+
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=1</small></code>
  
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=0</small></code>
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=0</small></code>
Line 249: Line 298:
 
=====硬触发模式=====
 
=====硬触发模式=====
 
======设置模式======
 
======设置模式======
−
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>work_mode=1</small></code>
+
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=1</small></code>
  
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=1</small></code>
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=1</small></code>
Line 259: Line 308:
 
将合适的触发信号连接到摄像机的trigger引脚并进行触发。
 
将合适的触发信号连接到摄像机的trigger引脚并进行触发。
  
−
==== 同步模式 ====
+
====同步模式====
 +
下面的各node和subdev要根据实际情况区分。
  
−
===== 设置数据格式，分辨率，帧率 =====
+
=====设置数据格式，分辨率，帧率=====
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
  
−
===== 设置同步模式 =====
+
=====设置同步模式=====
−
注：rk平台只支持接一路相机，在两个主板终端都执行以下操作，切换到同步模式。
+
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger<small>_mode=4</small></code>
  
−
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl work<small>_mode=4</small></code>
+
=====设置主从相机=====
−
 
 
−
===== 设置主从相机 =====
 
 
主相机：
 
主相机：
  
Line 278: Line 326:
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>sync_role=1</small></code>
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>sync_role=1</small></code>
  
−
===== 开始取图 =====
+
=====开始取图=====
−
可采用流模式中的几种方式取图。
+
同步模式下的取图方式与视频流模式下完全一致。
−
=== i2c脚本使用说明 ===
+
===i2c脚本使用说明===
 
我们提供了shell脚本来配置参数。
 
我们提供了shell脚本来配置参数。
  
−
[https://wiki.veye.cc/index.php/Gx_mipi_i2c.sh_user_guide/zh gx_mipi_i2c.sh user guide]
+
[[Gx mipi i2c.sh user guide/zh|gx_mipi_i2c.sh user guide]]
−
=== 本文修改记录 ===
+
 
 +
===客户集成开发的几点建议===
 +
 
 +
====初始化阶段====
 +
需要完成分辨率、帧率的配置。建议客户在程序初始化阶段，直接集成media-ctl和v4l2-ctl命令的调用，完成分辨率帧率以及数据格式的配置。
 +
 
 +
不要使用gx_mipi_i2c.sh直接设置相机寄存器，因为直接设置相机寄存器的话，Rockchip的linux驱动层次并不能同步到设置值。
 +
 
 +
在Rockchip平台，对于一个指定的主板，<code>./probe_camera_info-rk.sh</code>所探测到的节点是固定不变的。建议客户直接使用此脚本输出的json文件作为自己程序的配置文件。
 +
 
 +
客户也可以以此脚本的输出作为参考直接在代码中写死节点名称。
 +
 
 +
====工作阶段====
 +
客户根据自己开发语言的不同，可以参考本文前述的代码、工具。
 +
 
 +
关于时间戳，v4l2_buffer.timestamp会带有RK芯片接收到一个完整数据帧的准确时间，可以用于做相机同步或者与其他外部传感器同步的参考时间戳。
 +
 
 +
====参数配置====
 +
GX系列相机的参数非常丰富和灵活，主要使用gx_mipi_i2c.sh直接进行寄存器配置的方式实现。具体请参考寄存器文档和gx_mipi_i2c.sh的说明文档。
 +
 
 +
gx_mipi_i2c.sh具有paramsave功能，作用是将客户所有的配置参数保存的相机flash中，但是不建议客户在程序中频繁调用。
 +
 
 +
===本文修改记录===
 +
 
 +
*2025-12-06
 +
 
 +
调试文档结构，增加一些章节。
  
 
*2025-11-28
 
*2025-11-28
  
 
第一个版本。
 
第一个版本。

Latest revision as of 13:20, 23 January 2026

English

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 trigger_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 trigger_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 trigger_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脚本来配置参数。

gx_mipi_i2c.sh user guide

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

第一个版本。

Retrieved from "http://wiki.veye.cc/index.php?title=GX_Camera_Application_Development_Guide_on_Rochchip/zh&oldid=9096"