GX Camera on Firfly Boards/zh

English

怎样在Firefly板子上使用GX系列相机

1 概述

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

本文以Firefly的ROC-RK3588S-PC、ROC-RK3576-PC和ROC-RK3566-PC主板为例，介绍怎样将GX系列摄像机接入RK3566/3K3568、RK3576和RK3588S/RK3588系统。

我们提供了Linux(以Ubuntu为例)操作系统下的驱动。

1.1 支持的模组

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

此外，在ubuntu系统下，已经调通V-by-One HS连接模式的驱动。

2 硬件准备及安装

GX系列相机需要使用ADP-MV2转接板才能连接到ROC-RK35xx-PC主板。

2.1 新版本ADP-MV2的连接

2.1.1 GX相机与ADP-MV2的连接

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

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

2.1.2 ADP-MV2与主板的连接

二者使用0.5mm间距*30P的FFC同面线连接，注意接触面方向，ADP-MV2上向外，RK board上向内。

RK to ADP-MV2 and MV cam

2.2 V-by-One-HS-KIT摄像机连接示意图

VBYONE connection with rk3588

3 github库介绍

https://github.com/veyeimaging/rk35xx_veye_bsp

https://github.com/veyeimaging/rk35xx_firefly

包括以下主要内容：

• driver和dts源码
• i2c通信工具集
• 应用层demo

此外，在releases中，提供了编译好的linux系统镜像。

国内用户可以访问gitee仓库：

https://gitee.com/veyeimaging/rk35xx_veye_bsp

https://gitee.com/veyeimaging/rk35xx_firefly

国内用户可通过百度云下载：https://pan.baidu.com/s/1LdK0n_uCx1yGej4PB8-bxg?pwd=yft9。

4 更新ubuntu系统

对于ROC-RK3566-PC、ROC-RK3576-PC 和ROC-RK3588S-PC，我们提供了发布系统的烧写镜像。

下载https://github.com/veyeimaging/rk35xx_firefly/releases/中最新的支持GX系列的镜像。

参考Firefly文档(ROC-RK3588S-PC ROC-RK3566-PC ROC-RK3576-PC），烧写系统。

5 系统状态检测

5.1 是否正确识别到了相机

完成系统安装后，系统上电。在Firefly板端执行以下命令来检测是否正确连接相机。

dmesg | grep gxcam

应当有类似下面的提示：

[    6.667547] gxcam 7-003b: veye gx series camera driver version: 01.00.01

[    6.781681] gxcam 7-003b: camera is: GX-MIPI-IMX662

[    6.820210] gxcam 7-003b: Success to get gxcam endpoint data lanes, dts uses 2 lanes,will set to camera

[    6.834597] gxcam 7-003b: gxcam_enum_controls success

[    6.891209] rockchip-csi2-dphy csi2-dphy0: dphy0 matches m00_b_gxcam 7-003b:bus type 5

可以看到识别到当前的摄像机模组的型号，版本号。

在ROC-RK3588S-PC上，摄像机挂载在i2c-7, i2c地址是0x3b。

在ROC-RK3566-PC和ROC-RK3576-PC上，摄像机挂载在i2c-4。

• 执行如下命令检查video0设备节点

ls /dev/video0

可以看到

video0

正确识别摄像头之后，相机被识别为/dev/video0。

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

在这里，我们提供了两个脚本，可以自动检索下相机的一些信息

首先试用 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"

  }

]

通过索引信息，我们可以看到"i2c_bus": "7"对应的i2c_bus信息，以及接入了多少台设备，当前索引显示只接入一台设备，并且i2c_bus号是7，如果接入多个设备，索引信息可能会有"i2c_bus": "10"，"i2c_bus": "11"等信息

然后使用gx_probe.sh脚本，如果是多路相机，可以根据上一个脚本读出的i2c_bus执行，并将对应的相机型号、宽、高、帧率等信息配置到环境变量中。

使用方法是：

source ./gx_probe.sh 7

一个典型的输出如下：

$ source ./gx_probe.sh 7

Found veye_gxcam camera on i2c-7.

Setenv CAMERAMODEL = GX-MIPI-IMX662

Setenv FPS = 60

Setenv WIDTH = 1920

Setenv HEIGHT = 1080

可以通过 echo $CAMERAMODEL来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。

5.3 配置命令行全局变量

根据主板型号，配置I2C_BUS全局变量。

• ROC-RK3588S-PC

export I2C_BUS=7

• ROC-RK3566-PC and ROC-RK3576-PC

export I2C_BUS=4

5.4 使用media-ctl查看拓扑结构

使用media-ctl指令，可以清晰的展现出当前的拓扑结构。

media-ctl -p -d /dev/media0

5.4.1 链接关系

gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)

应用程序可以通过/dev/video0节点获取图像。

5.4.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指令修改。

5.5 相机支持的mbus-code

GX系列相机使用UYVY数据格式能力，具体请参考每个型号的相机的数据手册。

格式对应关系

Format on datasheet	mbus-code for media-ctl	FourCC pixelformat for v4l2-ctl
UYVY	UYVY8_2X8	UYVY

6 veye_viewe工具

可通过veye_viewe下载

7 应用范例

7.1 使用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实现。

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

7.1.1 配置触发模式

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

0：流模式

1：普通触发模式

4：多相机同步模式

7.1.2 配置触发源

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

0: 软触发

1: 硬触发

7.1.3 软触发一次

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

7.1.4 设置帧率

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

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

7.2 使用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]'

不仅可以在一个命令中同时配置数据格式，分辨率，帧率，也可以单独修改某一项或某几项。

7.3 流模式

7.3.1 设置数据格式，分辨率，帧率

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

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

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

图片格式请参考前面章节的描述。

7.3.4 yavta应用范例

7.3.4.1 yavta安装

git clone git://git.ideasonboard.org/yavta.git

cd yavta;make

7.3.4.2 保存图片到文件

配置完数据格式，分辨率，帧率之后，执行：

./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0

7.3.5 将相机数据导入OpenCV的范例

sudo apt install python3-opencv

详见github上的samples目录。

python3 ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7

注意需要使用合适的参数来执行上述程序。

7.3.6 gstreamer应用范例

我们提供了几个gstreamer例程，实现了预览功能。详见github上的samples目录。

7.4 触发模式

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

7.4.2 软触发模式

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

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

7.4.2.3 进行软触发操作

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

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

7.4.3 硬触发模式

7.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脚本进行丰富的触发参数设置。

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

7.4.3.3 进行硬触发操作

将合适的触发信号连接到摄像机的trigger引脚并进行触发。

7.5 同步模式

7.5.1 设置数据格式，分辨率，帧率

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

7.5.2 设置同步模式

注：rk平台只支持接一路相机，在两个主板终端都执行以下操作，切换到同步模式

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

7.5.3 设置主从相机

主相机：

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

从相机：

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

7.5.4 开始取图

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

8 i2c脚本使用说明

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

gx_mipi_i2c.sh user guide

9 参考资料

• ROC-RK3588S-PC 手册

https://wiki.t-firefly.com/zh_CN/ROC-RK3588S-PC/

• ROC-RK3576-PC 手册

https://wiki.t-firefly.com/zh_CN/ROC-RK3576-PC/

10 本文修改记录

• 2025-11-28

第一个版本。