MV Camera on Orange Pi's RK35XX Boards/zh

English

怎样在Orange Pi的RK35XX板子上使用MV系列和RAW系列相机

1 概述

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

本文以Orange Pi的CM4和CM5以及CM5 tablet主板为例，介绍怎样将MV和RAW系列摄像机接入RK3566/3K3568和RK3588S/RK3588系统。

我们提供了Linux操作系统下的驱动。

1.1 支持的模组

系列	型号	状态
MV系列	MV-MIPI-IMX178M	完成
MV系列	MV-MIPI-SC130M	完成
MV系列	MV-MIPI-IMX287M	完成
MV系列	MV-MIPI-IMX296M	完成
MV系列	MV-MIPI-IMX265M	完成
MV系列	MV-MIPI-IMX264M	完成
MV系列	MV-MIPI-IMXGMAX4002M	完成
RAW系列	RAW-MIPI-SC132M	完成
RAW系列	RAW-MIPI-IMX462M	完成
RAW系列	RAW-MIPI-AR0234M	完成
RAW系列	RAW-MIPI-SC535M	完成

2 硬件准备及安装

我们使用Orange Pi的CM4和CM5的官方底板，这两个底板提供了兼容树莓派的15Pin端子。对于RAW系列相机，无需使用转接板即可将我们的相机安装到其主板上。对于MV系列相机，则需要使用ADP-MV1转接板进行连接。

2.1 相机与OrangePi CM4的连接

ADP-MV1和OrangePi之间使用15P的FFC异面线连接，注意接触面方向。请注意，只有下图所示的CAM1支持VEYE相机。

OrangePi CM4 to MV cam

OrangePi CM4 to RAW CAM

2.2 相机与OrangePi CM5的连接

OrangePi CM5最多支持4个VEYE摄像头，下图是同时连接多种摄像头的硬件连接方法展示。

OrangePi CM5 to all cam overview

OrangePi CM5 to all cam backview

2.3 相机与OrangePi CM5 tablet的连接

由于接插件格式的差异，OrangePi CM5 tablet上我们调通了CAM2和CAM3两个接口的模组，下图是连接RAW系列和MV系列的连接方法。

3 github库介绍

https://github.com/veyeimaging/rk35xx_veye_bsp

https://github.com/veyeimaging/rk35xx_orangepi

包括以下主要内容：

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

此外，在releases中，提供了编译好的烧写镜像和linux内核的deb安装包。

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

https://gitee.com/veyeimaging/rk35xx_veye_bsp

https://gitee.com/veyeimaging/rk35xx_orangepi

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

4 更新主板的Ubuntu系统

我们提供了发布系统的烧写镜像，同时提供了linux内核的deb安装包。

参考OrangePi CM4用户手册，或者OrangePi CM5的用户手册烧写系统。当然，也可以使用通用的dpkg命令，安装deb包。

5 系统状态检测

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

sudo dmesg | grep mvcam

5.1 CM4

CM4只支持通过cam1接口，接入相机。以RAW-MIPI-SC132M为例，dmesg信息中包含如下内容

mvcam 1-003b: camera is: RAW-MIPI-SC132M

mvcam 1-003b: firmware version: 0x1040000

执行如下命令，检查video设备节点

ls /dev/video0

可以看到

video0

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

5.2 CM5

CM5 支持接入4个相机，以RAW-MIPI-SC132M为例，dmesg信息中包含如下内容dmesg信息中包含如下内容:

mvcam 3-003b: camera is: RAW-MIPI-SC132M

mvcam 3-003b: firmware version: 0x1040000

mvcam 4-003b: camera is: RAW-MIPI-SC132M

mvcam 4-003b: firmware version: 0x1040000

mvcam 5-003b: camera is: RAW-MIPI-SC132M

mvcam 5-003b: firmware version: 0x1040000  

mvcam 6-003b: camera is: RAW-MIPI-SC132M

mvcam 6-003b: firmware version: 0x1040000

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

在这里，我们提供了一个mv_probe.sh脚本，用于自动检测识别到的相机并将相机默认的型号、宽、高、帧率等信息配置到环境变量中。

使用方法是：

source ./mv_probe.sh

一个典型的输出如下：

$ source ./mv_probe.sh

The mvcam driver is loaded on i2c-10, but the camera is not detected!

Found veye_mvcam camera on i2c-11.

Setenv CAMERAMODEL = RAW-MIPI-SC535M

Setenv FPS = 49

Setenv WIDTH = 2432

Setenv HEIGHT = 2048

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

注意：此脚本需要mvcam的驱动版本大于等于1.1.06才可以支持。

如你使用的驱动版本小于1.1.06，或者你希望使用不同于当前值的宽、高、帧率。请参考相机模组的手册，手动配置如下WIDTH HEIGHT FPS环境变量，否则可能导致后面的程序运行不正常。如：

export WIDTH=2432

export HEIGHT=2048

export FPS=50

5.4 配置命令行全局变量

根据主板型号，配置I2C_BUS全局变量。下面对两个主板各举一个摄像头作为例子。

• OrangePi CM4

export I2C_BUS=1

• OrangePi CM5

export I2C_BUS=6

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

下面以CM5的CAM1为例进行解释。

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

media-ctl -p -d /dev/media2

5.5.1 链接关系

mv camera->rockchip-csi2-dphy1->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video22)

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

5.5.2 mv camera entity信息

以RAW-MIPI-SC132M为例：

- entity 63: m00_b_mvcam 4-003b (1 pad, 1 link)

             type V4L2 subdev subtype Sensor flags 0

             device node name /dev/v4l-subdev8

        pad0: Source

                [fmt:Y8_1X8/1080x1280@100/12000 field:none]

                -> "rockchip-csi2-dphy1":0 [ENABLED]

可以看到：

• 该Entity完整的名称是： m00_b_mvcam 4-003b。
• 它是一个 V4L2 subdev (Sub-Device) Sensor。
• 它对应的节点是 /dev/v4l-subdev8 ，应用程序（如v4l2-ctl）可以打开它，并进行配置。
• 它的输出格式是 [fmt:Y8_1X8/1080x1280@100/12000 field:none] ，其中Y8_1X8是一种mbus-code的简写，下一小节会列出支持的mbus-code。
• 当前分辨率是1080x1280。
• 当前帧间隔是100/12000,即帧率是120。

摄像机输出的数据格式，可以通过media-ctl指令修改。

各个信息对应关系如下表：

- CM4

CAM num	I2C	media node	media entity name	video node	subdev node
1	1	/dev/media0	m00_b_mvcam 1-003b	/dev/video0	/dev/v4l-subdev2

- CM5

CAM num	I2C	media node	media entity name	video node	subdev node
1	4	/dev/media2	m00_b_mvcam 4-003b	/dev/video22	/dev/v4l-subdev8
2	3	/dev/media3	m01_b_mvcam 3-003b	/dev/video33	/dev/v4l-subdev11
3	5	/dev/media1	m00_b_mvcam 5-003b	/dev/video11	/dev/v4l-subdev5
4	6	/dev/media0	m00_b_mvcam 6-003b	/dev/video0	/dev/v4l-subdev2

5.6 相机支持的mbus-code

MV系列和RAW系列相机具备不同的数据格式能力，具体请参考每个型号的相机的数据手册。

格式对应关系

Format on datasheet	mbus-code for media-ctl	FourCC pixelformat for v4l2-ctl
RAW8	Y8_1X8	GREY
RAW10	Y10_1X10	'Y10 '
RAW12	Y12_1X12	'Y12 '
UYVY	UYVY8_2X8	UYVY

6 raw图片格式说明

RK35xx的VICAP模块支持两种数据保存格式，Compact和Noncompact RAW。可以通过RKCIF的RKCIF_CMD_SET_CSI_MEMORY_MODE ioctl指令修改模式。默认情况下，输出的是Compact RAW格式。

Compact raw and noncompact raw of rk3588 VICAP

6.1 具有填充位的图片格式（Noncompact RAW）

对于10bit深度、12bit深度的像素数据，总是使用两个字节来存储一个像素。这种存储方式方便软件处理，缺点是空间占用较大。根据数据有效数据保存在高位还是低位，又分为high align和low align两种。

6.1.1 Noncompact RAW(high align)

数据保存到高位，用不到的低位以0填充。RK VICAP支持的一种数据格式。

6.1.2 Noncompact RAW(low align)

数据保存到低位，用不到的高位以0填充。V4L2标准的'Y10 ' (10-bit Greyscale),'Y12 ' (12-bit Greyscale)格式都是以这种方式存储的。

后文提到的pixel_layer_convert转换工具，也是将Compact RAW转换为此种存储方式。方便使用图片播放器打开显示。

6.2 紧密排列的图片格式（Compact RAW）

如上图所示，像素和像素之间不会进行空bit位填充。

6.3 行对齐（line stride）

为了方便对图像进行快速操作，系统通常为每行数据提供行对齐的buffer大小。RK3588使用256字节对齐。

line_stride = ALIGN_UP（image_width*bits_per_pixel/8,256）

比如当图像宽度是1456时：

8bit depth，line_stride=1536。

10bit depth，preferred_stride=2048。

12bit depth，preferred_stride=2304。

6.4 转换工具

我们编写了一个小工具：pixel_layer_convert，可以很方便的将紧密排列的图片（Compact RAW）转为具有填充位的图片(Noncompact RAW(low align))。

比如下面的命令，可以将一个1456宽度的compact raw10 图片转为noncompact raw10。

./pixel_layer_convert -I R10C -i y10-1456x1088_0001.raw -o y10-1456x1088_0001_new.raw -w 1456

6.5 raw图片播放器

推荐使用vooya作为播放器，支持GREY, 和具有填充位的图片格式。

Y8文件可以用这个播放器： YUV Displayer Deluxe。

7 应用范例

请注意，下面章节中的/dev/media0,/dev/video0,/dev/v4l-subdev2根据实际需要替换为前面章节的描述进行替换。

7.1 使用v4l2-ctl配置参数

$ v4l2-ctl -d /dev/v4l-subdev2 -L

User Controls

                   trigger_mode 0x00981901 (int)    : min=0 max=2 step=1 default=0 value=0 flags=volatile, execute-on-write

                    trigger_src 0x00981902 (int)    : min=0 max=1 step=1 default=1 value=1 flags=volatile, execute-on-write

                    soft_trgone 0x00981903 (button) : flags=write-only, execute-on-write

                     frame_rate 0x00981904 (int)    : min=1 max=60 step=1 default=60 value=60 flags=volatile, execute-on-write

                          roi_x 0x00981905 (int)    : min=0 max=1376 step=8 default=0 value=0

                          roi_y 0x00981906 (int)    : min=0 max=1024 step=4 default=0 value=0

可以使用下面的方法设置和获取参数。

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl [ctrl_type]=[val]

v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]

以上所有功能，均可使用mv_mipi_i2c.sh实现。

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

7.1.1 配置触发模式

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

0：流模式

1：普通触发模式

2：快速连续触发模式

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.1.5 设置ROI起始位置

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

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

ROI其实位置设置之后，需要通过media-ctl命令完成完整的ROI配置。

设置roi后，最大帧率会自动调整。请注意，摄像机roi参数需要符合摄像机手册中的要求。

7.2 使用media-ctl配置图像格式

可以通过下面的命令，配置摄像机的数据格式，分辨率，帧率。

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

其中："m00_b_mvcam 7-003b"指的相机的entity完整名称，Y8_1X8为mbus-code，'"$WIDTH"'x'"$HEIGHT"'指明了分辨率，1/'"$FPS"'指明了帧率。

此处的width和height配合v4l2-ctl命令的roi_x和roi_y共同组成了ROI参数。

比如，对于MV-MIPI-IMX296M,这个命令经过变量替换后的结果是：

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_mvcam 6-003b":0[fmt:Y8_1X8/1456x1088@1/60 field:none]'

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

7.3 流模式

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

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

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

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

7.3.2 帧率统计

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=/dev/null

或者

./yavta -c-1 --skip 0 -f Y8 -s ${WIDTH}x${HEIGHT} /dev/video0

7.3.3 保存图片到文件

• raw8格式

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY --stream-mmap --stream-count=1 --stream-to=y8-${WIDTH}x${HEIGHT}.raw

• raw10格式

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat='Y10 ' --stream-mmap --stream-count=1 --stream-to=y10-${WIDTH}x${HEIGHT}.raw

• raw12格式

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat='Y12 ' --stream-mmap --stream-count=1 --stream-to=y12-${WIDTH}x${HEIGHT}.raw

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

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 -Fy8-${WIDTH}x${HEIGHT}.raw --skip 0 -f Y8 -s ${WIDTH}x${HEIGHT} /dev/video0

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

sudo apt install python3-opencv

详见github上的samples目录。

python3 ./v4l2dev_2_opencv_show_grey.py --width 1456 --height 1088 --fps 60 --i2c 6

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

7.3.6 gstreamer应用范例

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

7.4 触发模式

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

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

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

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

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=GREY --stream-mmap --stream-count=1 --stream-to=y8-${WIDTH}x${HEIGHT}.raw

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

可以使用mv_mipi_i2c.sh脚本进行丰富的触发参数设置。

7.4.3.2 开始取图

v4l2-ctl -d /dev/video0 --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY --stream-mmap --stream-count=1 --stream-to=y8-${WIDTH}x${HEIGHT}.raw

7.4.3.3 进行硬触发操作

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

8 i2c脚本使用说明

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

mv_mipi_i2c.sh user guide

9 参考资料

• OrangePi CM4

http://www.orangepi.cn/orangepiwiki/index.php/Orange_Pi_CM4

• OrangePi CM5

http://www.orangepi.cn/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-CM5.html

10 本文修改记录

• 2025-01-09

发布第一个版本。