Mv series camera appnotes 4 jetson/zh
1 概述
MV系列相机是为工业领域的AI应用推出的相机。其使用MIPI CSI-2接口，尤其适合嵌入式运算平台使用。它具备丰富的数据格式和触发特性，极低的延时，极高的带宽和可靠的稳定性。
本文介绍了如何在英伟达Jetson平台使用MV系列相机。
1.1 支持的摄像机模组
| 系列 | 型号 | 状态 |
|---|---|---|
| MV系列 | MV-MIPI-IMX178M | 完成 |
| MV系列 | MV-MIPI-SC130M | 完成 |
1.2 支持的Jetson Board
| Jetson型号 | 状态 |
|---|---|
| Nano A02 | 完成 |
| Nano B01 | 完成 |
| Nano 2GB | 完成 |
| TX2 NX | 完成 |
| XAVIER NX | 完成 |
| TX2 Devkit | 完成 |
| AGX Xavier | 完成 |
| AGX Orin | 开发中 |
1.3 支持的L4T版本
- Jetpack4.6.1,L4T版本r32.7.1
- Jetpack5.0.2,L4T版本r35.1
1.3.1 怎样查看当前L4T版本
在jetson板子上，查看当前L4T版本，尽量使用同一版本进行替换。
cat /etc/nv_tegra_release
如显示：
# R32 (release), REVISION: 7.1......
则表示当前L4T版本为32.7.1，对应的Jetpack版本是Jetpack32.6.1。
2 硬件准备以及安装
MV系列相机需要转接板才可以接入Jetson平台。支持情况如下表：
| Jetson型号 | 转接板 | 摄像机数量 | 供电 |
|---|---|---|---|
| Nano A02 | ADP-MV1 | 1 | 5V DC（必须） |
| Nano B01 | ADP-MV1 | 1 | 5V DC（必须） |
| Nano 2GB | ADP-MV1 | 2 | 5V DC（必须） |
| TX2 NX | ADP-MV1 | 2 | 5V DC（必须） |
| XAVIER NX | ADP-MV1 | 2 | 5V DC（必须） |
| TX2 Devkit | ADP-N4 | 6 | 5V或12V DC (必须) |
| AGX Xavier | ADP-N4 | 6 | 5V或12V DC (必须) |
| AGX Orin | ADP-N4 | 6 | 5V或12V DC (必须) |
下面以MV-MIPI-IMX178M为例，介绍硬件的安装方法。
2.1 MV-MIPI-CAM与ADP-MV1的连接
二者使用0.5mm间距*30P的FFC异面线连接，注意接触面向外。
2.2 使用ADP-MV1的连接方式
2.2.1 供电
ADP-MV1需要独立的5V供电，可以使用杜邦线直接从Jetson主板取电。
2.2.2 使用ADP-MV1连接到Nano和NX
Nano系列和NX系列采用这种连接方式。
2.3 MV-MIPI-CAM与ADP-N4的连接
二者使用0.5mm间距*30P的FFC同面线连接，注意接触面向外。
2.4 使用ADP-N4的连接方式
2.4.1 供电
ADP-N4需要独立的供电。它支持两种供电方式，二选其一即可。
- 5V DC 接到 J19-9。可以使用杜邦线直接从Jetson主板取电。
- 12V DC 接到J11。需使用外置适配器供电。
2.4.2 使用ADP-N4的连接到TX2和AGX
3 更新Jetson系统
本章节描述怎样更新Jetson的L4T系统以支持MV摄像头模组。操作系统更新方法，请参考更新Jetson操作系统。
特别的，对于MV系列相机，除了在linux系统中增加了摄像头的驱动，我们还增加了一个内核补丁——veye_mv_l4t_<verion>.patch，并提供编译好的Image文件。
这个patch具备两个功能：
- 增加了黑白相机的Y10和Y12两种数据格式的支持。
- 增加了trigger模式的支持。
3.1 raw data图片格式说明
在TX2和XAVIER上，10 bit depth和12 bit depth的raw data在内存中的存储格式是不符合V4L2标准的。我们扩展了linux内核中的定义以支持这种情况。
TY10、TY12、XY10和XY12是我们新增的类型。
3.1.1 Nano
| Depth | Bit order | FourCC | Enumerator |
|---|---|---|---|
| 8 | B7 B6 B5 B4 B3 B2 B1 B0 | GREY | V4L2_PIX_FMT_GREY |
| 10 | 0 0 0 0 0 0 B9 B8 B7 B6 B5 B4 B3 B2 B1 B0 | 'Y10 ' | V4L2_PIX_FMT_Y10 |
| 12 | 0 0 0 0 B11 B10 B9 B8 B7 B6 B5 B4 B3 B2 B1 B0 | 'Y12 ' | V4L2_PIX_FMT_Y12 |
3.1.2 TX2
| Depth | Bit order (X is undefined) | FourCC | Enumerator |
|---|---|---|---|
| 8 | B7 B6 B5 B4 B3 B2 B1 B0 | GREY | V4L2_PIX_FMT_GREY |
| 10 | 0 0 B9 B8 B7 B6 B5 B4 B3 B2 B1 B0 X X X X | TY10 | V4L2_PIX_FMT_TX2_Y10 |
| 12 | 0 0 B11 B10 B9 B8 B7 B6 B5 B4 B3 B2 B1 B0 X X | TY12 | V4L2_PIX_FMT_TX2_Y12 |
3.1.3 XAVIER
| Depth | Bit order (X is undefined) | FourCC | Enumerator |
|---|---|---|---|
| 8 | B7 B6 B5 B4 B3 B2 B1 B0 | GREY | V4L2_PIX_FMT_GREY |
| 10 | 0 B9 B8 B7 B6 B5 B4 B3 B2 B1 B0 X X X X X | XY10 | V4L2_PIX_FMT_XAVIER_Y10 |
| 12 | 0 B11 B10 B9 B8 B7 B6 B5 B4 B3 B2 B1 B0 X X X | XY12 | V4L2_PIX_FMT_XAVIER_Y12 |
同时，我们提供了工具软件，以便将特殊的数据格式转为标准格式。https://github.com/veyeimaging/pixel_layer_convert。
推荐使用vooya作为播放器。
3.2 Trigger模式的支持
Jetson系统的默认驱动只支持视频流模式。在其VI驱动中，数据接收功能具有超时机制。我们增加了一个可设的vi_time_out_disable选项，可以动态打开和关闭这个超时机制。
具体应用参考下面的应用范例。
4 系统状态检测
完成系统更新后，重启Jetson主板。
Jetson系统启动过程中，会检测所有i2c bus上摄像头是否存在，如果存在则生成/dev/videoX设备节点。
在Jetson板端执行以下命令来检测是否正确连接摄像头。
dmesg | grep mvcam
可以看到linux启动阶段probe到的相机型号和以及相机的版本号：
比如下面这个提示，表示在i2c-10总线上检测到了MV-MIPI-IMX178M摄像机。
mvcam 10-003b: camera is: MV-MIPI-IMX178M
mvcam 10-003b: firmware version: 0x1080103
4.1 /dev/videoX设备节点
摄像头模组在Jetson系统中映射为/dev/videoX设备节点。
操作系统启动过程中，按照i2c bus从小到大的顺序探测摄像头。X值是按照探测的逻辑顺序从0开始递增的。
举例说，如果只接入一个摄像头，无论硬件连接到哪个位置，X都为0。如果接入5个，则按照i2c bus从小到大，X为[0-4]。
v4l2-ctl命令中，使用-d /dev/videoX来访问不同的摄像头。
gstreamer中，v4l2src可以通过指明device=/dev/videoX来访问不同的摄像头。
5 配置命令行全局变量
为了后面描述方便，此处根据sensor尺寸，配置全局变量。
- MV-MIPI-IMX178M
export WIDTH=3088
export HEIGHT=2064
- MV-MIPI-SC130M
export WIDTH=1280
export HEIGHT=1024
6 v4l2-ctl 应用范例
6.1 安装v4l2-utils
sudo apt-get install v4l-utils
6.2 使用v4l2-ctl配置参数
6.2.1 列出相机支持的数据格式
v4l2-ctl --list-formats-ext
下面是在XAVIER系统下，MV-MIPI-IMX178M的例子：
ioctl: VIDIOC_ENUM_FMT
Index : 0
Type : Video Capture
Pixel Format: 'UYVY'
Name : UYVY 4:2:2
Size: Discrete 3088x2064
Interval: Discrete 0.045s (22.000 fps)
Index : 1
Type : Video Capture
Pixel Format: 'NV16'
Name : Y/CbCr 4:2:2
Size: Discrete 3088x2064
Interval: Discrete 0.045s (22.000 fps)
Index : 2
Type : Video Capture
Pixel Format: 'GREY'
Name : 8-bit Greyscale
Size: Discrete 3088x2064
Interval: Discrete 0.045s (22.000 fps)
Index : 3
Type : Video Capture
Pixel Format: 'XY10'
Name : XAVIER 10-bit/16-bit Greyscale
Size: Discrete 3088x2064
Interval: Discrete 0.045s (22.000 fps)
Index : 4
Type : Video Capture
Pixel Format: 'XY12'
Name : XAVIER 12-bit/16-bit Greyscale
Size: Discrete 3088x2064
Interval: Discrete 0.045s (22.000 fps)
需要特别说明的是，MV系列相机提供的UYVY和NV16模式仅作调试使用，且最大宽度不能超过2880。
6.2.2 列出驱动中实现的相机的可配置参数
v4l2-ctl -L
User Controls
horizontal_flip 0x00980914 (bool) : default=0 value=0
vertical_flip 0x00980915 (bool) : default=0 value=0
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=22 step=1 default=22 value=22 flags=volatile, execute-on-write
roi_x 0x00981905 (int) : min=0 max=2712 step=8 default=0 value=0
roi_y 0x00981906 (int) : min=0 max=1744 step=4 default=0 value=0
Camera Controls
low_latency_mode 0x009a206d (bool) : default=0 value=0
preferred_stride 0x009a206e (int) : min=0 max=65535 step=1 default=0 value=0
vi_time_out_disable 0x009a2078 (bool) : default=0 value=0
可以使用下面的方法设置和获取参数。
v4l2-ctl --set-ctrl [ctrl_type]=[val]
v4l2-ctl --get-ctrl [ctrl_type]
以上所有功能，均可使用mv_mipi_i2c.sh实现。
需要指出的是，以上参数在开始取图的状态均不可修改。下面进行逐个说明：
6.2.3 配置翻转
- 水平翻转
v4l2-ctl --set-ctrl horizontal_flip=1
- 垂直翻转
v4l2-ctl --set-ctrl vertical_flip=1
6.2.4 配置触发模式
v4l2-ctl --set-ctrl trigger_mode=[0-2]
0：流模式
1：普通触发模式
2：快速连续触发模式
6.2.5 配置触发源
v4l2-ctl --set-ctrl trigger_src=[0-1]
0: 软触发
1: 硬触发
6.2.6 软触发一次
v4l2-ctl --set-ctrl soft_trgone=1
6.2.7 设置帧率
v4l2-ctl --set-ctrl frame_rate=[1-max]
随分辨率的调整，最大帧率会自动更新。
6.2.8 设置ROI和数据格式
举例:
v4l2-ctl --set-ctrl roi_x=0
v4l2-ctl --set-ctrl roi_y=0
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY
设置roi后，最大帧率会自动调整。请注意，摄像机roi参数需要符合摄像机手册中的要求。
6.2.9 preferred_stride
preferred_stride指一行图像数据需要的内存大小。Jetson平台的图像数据是unpacked存储的，即10bit depth和12 bit depth的数据格式下，一个像素占用两个字节。
- 普通情况下，buffer需要64字节对齐。
preferred_stride= ALIGN_UP（width*bytes_per_pixel,64）
比如宽度为3088时：
8bit depth，preferred_stride=3136。
10bit depth，preferred_stride=6208。
12bit depth，preferred_stride=6208。
- 如果使用VIC buffer，则需要256字节对齐。
preferred_stride= ALIGN_UP（width*bytes_per_pixel,256）
6.3 流模式
6.3.1 设置图像格式
以最大画面为例：
v4l2-ctl --set-ctrl roi_x=0
v4l2-ctl --set-ctrl roi_y=0
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY
6.3.2 帧率统计
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=/dev/null
6.3.3 保存图片到文件
6.3.3.1 MV-MIPI-IMX178M
- raw8格式
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=3136
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=1 --stream-to=y8-3136x2064.raw
- raw10格式
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=6208
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=XY10 --stream-mmap --stream-count=1 --stream-to=y10-3104x2064.raw
- raw12格式
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=6208
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=XY12 --stream-mmap --stream-count=1 --stream-to=y12-3104x2064.raw
图片格式请参考上面：raw data图片格式说明 章节。
6.3.3.2 MV-MIPI-SC130M
由于宽度1280是64和256的整数倍，不需要设置preferred_stride。
- raw8格式
v4l2-ctl --set-fmt-video=width=1280,height=1024,pixelformat=GREY --stream-mmap --stream-count=1 --stream-to=y8-1280x1024.raw
- raw10格式
v4l2-ctl --set-fmt-video=width=1280,height=1024,pixelformat=XY10 --stream-mmap --stream-count=1 --stream-to=y10-1280x1024.raw
6.3.4 实时预览
UYVY模式支持的最大宽度为2880，使用如下命令可以进行实时预览。
6.3.4.1 MV-MIPI-IMX178M
v4l2-ctl -d /dev/video0 --set-fmt-video=width=2816,height=2064,pixelformat=UYVY
gst-launch-1.0 v4l2src device=/dev/video0 ! "video/x-raw,format=(string)UYVY, width=(int)2816, height=(int)2064, framerate=(fraction)22/1" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nv3dsink sync=false
6.3.4.2 MV-MIPI-SC130M
v4l2-ctl -d /dev/video0 --set-fmt-video=width=1280,height=1024,pixelformat=UYVY
v4l2-ctl -d /dev/video0 --set-ctrl frame_rate=108
gst-launch-1.0 v4l2src device=/dev/video0 ! "video/x-raw,format=(string)UYVY, width=(int)1280, height=(int)1024, framerate=(fraction)108/1" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nv3dsink sync=false
6.4 触发模式
6.4.1 准备工作
v4l2-ctl --set-ctrl roi_x=0
v4l2-ctl --set-ctrl roi_y=0
v4l2-ctl --set-ctrl low_latency_mode=1
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY
如为MV-MIPI-IMX178M，3088*2064：
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=3136
6.4.2 软触发
6.4.2.1 设置模式
v4l2-ctl --set-ctrl trigger_mode=1
v4l2-ctl --set-ctrl trigger_src=0
v4l2-ctl --set-ctrl vi_time_out_disable=1
6.4.2.2 开始取图
- MV-MIPI-IMX178M
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=y8-3104x2064.raw
- MV-MIPI-SC130M
v4l2-ctl --set-fmt-video=width=1280,height=1024,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=y8-1280x1024.raw
6.4.2.3 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
v4l2-ctl --set-ctrl soft_trgone=1
6.4.2.4 停止触发和采集
由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。
v4l2-ctl --set-ctrl vi_time_out_disable=0
在取图命令的终端中，按Ctrl+C退出采集操作。
6.4.3 硬触发
使用jetson-gpio进行触发操作，首先请安装并配置好jetson-gpio。
下面以使用jetson GPIO40（Board num）为模拟触发源，上升沿触发为例。
可以使用mv_mipi_i2c.sh脚本进行丰富的触发参数设置。
6.4.3.1 硬件连接
- 使用ADP-MV1时
- 使用ADP-N4时
如采用公共触发源连接，则首先激将J7成对短接，然后将jetson GPIO40接到J19-1。
如采用独立触发源连接，则直接将 GPIO40接到J7-1---J7-11。
6.4.3.2 设置模式
v4l2-ctl --set-ctrl trigger_mode=1
v4l2-ctl --set-ctrl trigger_src=1
v4l2-ctl --set-ctrl vi_time_out_disable=1
6.4.3.3 开始取图
- MV-MIPI-IMX178M
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=y8-3104x2064.raw
- MV-MIPI-SC130M
v4l2-ctl --set-fmt-video=width=1280,height=1024,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=y8-1280x1024.raw
6.4.3.4 进行硬触发操作
python gpio_trigger_jetson.py
Note:触发脚本链接。
6.4.3.5 停止触发和采集
由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。
v4l2-ctl --set-ctrl vi_time_out_disable=0
在取图命令的终端中，按Ctrl+C退出采集操作。
7 Application demo
7.1 v4l2grab_mvcam_jetson
v4l2grab_mvcam是一个C语言开发的sample，支持流模式和触发模式。
7.2 yavta(仅支持流模式)
7.2.1 yavta安装
git clone https://github.com/veyeimaging/yavta.git
cd yavta;make
7.2.2 设置图像格式
v4l2-ctl --set-ctrl roi_x=0
v4l2-ctl --set-ctrl roi_y=0
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=GREY
7.2.3 保存图片到文件
7.2.3.1 MV-MIPI-IMX178M
- raw8格式
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=3136
./yavta -c1 -Fy8-3136x2064.raw --skip 0 -f Y8 -s 3088x2064 /dev/video0
- raw10格式
以XAVIER平台为例
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=6208
./yavta -c1 -Fy10-3104x2064.raw --skip 0 -f XY10 -s 3088x2064 /dev/video0
- raw12格式
以XAVIER平台为例
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=6208
./yavta -c1 -Fy12-3104x2064.raw --skip 0 -f XY12 -s 3088x2064 /dev/video0
7.2.3.2 MV-MIPI-IMX178M
- raw8格式
./yavta -c1 -Fy8-1280x1024.raw --skip 0 -f Y8 -s 1280x1024 /dev/video0
- raw10格式
以XAVIER平台为例
./yavta -c1 -Fy10-1280x1024.raw --skip 0 -f XY10 -s 1280x1024 /dev/video0
图片格式请参考上面：raw data图片格式说明 章节。
8 i2c脚本使用说明
我们提供了shell脚本来配置参数。
9 参考资料
10 本文修改记录
- 2022-08-31
支持Jetpack5.0.2
- 2022-06-23
增加ADP-N4的相关描述
- 2022-05-20
第一个发布版本