Mv series camera appnotes 4 jetson/zh
1 概述
MV系列相机是为工业领域的AI应用推出的相机。其使用MIPI CSI-2接口，尤其适合嵌入式运算平台使用。它具备丰富的数据格式和触发特性，极低的延时，极高的带宽和可靠的稳定性。
本文介绍了如何在英伟达Jetson平台使用MV系列相机。
1.1 支持的摄像机模组
| 系列 | 型号 | 状态 |
|---|---|---|
| MV系列 | MV-MIPI-IMX178M | 完成 |
1.2 支持的Jetson Board
| Jetson型号 | 状态 |
|---|---|
| Nano A02 | 完成 |
| Nano B01 | 完成 |
| Nano 2GB | 完成 |
| TX2 NX | 完成 |
| XAVIER NX | 完成 |
| TX2 Devkit | 开发中 |
| AGX Xavier | 开发中 |
| Orin系列 | 开发中 |
1.3 支持的L4T版本
- Jetpack4.6.1,L4T版本r32.7.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 | 12V DC (可选) |
| AGX Xavier | ADP-N4 | 6 | 12V DC (可选) |
| Orin系列 | TODO | TODO | TODO |
下面以MV-MIPI-IMX178M为例，介绍硬件的安装方法。
2.1 MV-MIPI-IMX178M与ADP-MV1的连接
二者使用0.5mm间距*30P的FFC异面线连接，注意接触面向外。
2.2 使用ADP-MV1的连接方式（以Xavier NX为例）
2.2.1 供电
ADP-MV1需要独立的5V供电，可以使用杜邦线直接从Jetson主板取电。
2.2.2 使用ADP-MV1连接（以Xavier NX为例）
Nano系列和NX系列采用这种连接方式。
2.3 使用ADP-N4的连接方式（以AGX Xavier为例）
TODO
3 更新Jetson系统
本章节描述怎样更新Jetson的L4T系统以支持MV摄像头模组。操作系统更新方法，请参考更新Jetson操作系统。
特别的，对于MV系列相机，除了在linux系统中增加了摄像头的驱动，我们还增加了一个内核补丁——veye_mv_l4t_32.7.1.patch。
这个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。
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 v4l2-ctl 应用范例
5.1 安装v4l2-utils
sudo apt-get install v4l-utils
5.2 yavta安装
git clone git://git.ideasonboard.org/yavta.git
cd yavta;make
5.3 使用v4l2-ctl配置参数
5.3.1 列出相机支持的数据格式
v4l2-ctl --list-formats-ext
下面是在XAVIER系统的例子：
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。
5.3.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实现。
需要指出的是，以上参数在开始取图的状态均不可修改。下面进行逐个说明：
5.3.3 配置翻转
- 水平翻转
v4l2-ctl --set-ctrl horizontal_flip=1
- 垂直翻转
v4l2-ctl --set-ctrl vertical_flip=1
5.3.4 配置触发模式
v4l2-ctl --set-ctrl trigger_mode=[0-2]
0：流模式
1：普通触发模式
2：快速连续触发模式
5.3.5 配置触发源
v4l2-ctl --set-ctrl trigger_src=[0-1]
0: 软触发
1: 硬触发
5.3.6 软触发一次
v4l2-ctl --set-ctrl soft_trgone=1
5.3.7 设置帧率
v4l2-ctl --set-ctrl frame_rate=[1-max]
随分辨率的调整，最大帧率会自动更新。
5.3.8 设置ROI和数据格式
举例，对于MV-MIPI-IMX178M:
v4l2-ctl --set-ctrl roi_x=0
v4l2-ctl --set-ctrl roi_y=0
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY
设置roi后，最大帧率会自动调整。请注意，摄像机roi参数需要符合摄像机手册中的要求。
5.3.9 preferred_stride
preferred_stride指一行图像数据需要的内存大小。
- 普通情况下，buffer需要64字节对齐。
preferred_stride= ALIGN_UP（width*bit_depth/8,64）
比如GREY模式下3088宽度，preferred_stride=3104。
- 如果使用VIC buffer，则需要256字节对齐。
preferred_stride= ALIGN_UP（width*bit_depth/8,256）
5.4 流模式
5.4.1 设置图像格式
以MV-MIPI-IMX178M，3088*2064举例：
v4l2-ctl --set-ctrl roi_x=0
v4l2-ctl --set-ctrl roi_y=0
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY
5.4.2 帧率统计
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=/dev/null
5.4.3 保存图片到文件
- raw8格式
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=1 --stream-to=y8-3104x2064.raw
或者
./yavta -c1 -Fy8-3104x2064.raw --skip 0 -f Y8 -s 3088x2064 /dev/video0
- raw10格式
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=XY10 --stream-mmap --stream-count=1 --stream-to=y10-3088x2064.raw
- raw12格式
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=XY12 --stream-mmap --stream-count=1 --stream-to=y12-3088x2064.raw
图片格式请参考下面：raw data图片格式说明 章节。
5.4.4 实时预览
UYVY模式支持的最大宽度为2880，使用如下命令可以进行实时预览。
v4l2-ctl --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" ! nvoverlaysink sync=false
5.5 触发模式(v4l2-ctl为例)
5.5.1 准备工作
以MV-MIPI-IMX178M，3088*2064举例：
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=3088,height=2064,pixelformat=GREY
v4l2-ctl -d /dev/video0 --set-ctrl preferred_stride=3136
5.5.2 软触发
5.5.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
5.5.2.2 开始取图
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=y8-3104x2064.raw
5.5.2.3 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
v4l2-ctl --set-ctrl soft_trgone=1
5.5.2.4 停止触发和采集
由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。
v4l2-ctl --set-ctrl vi_time_out_disable=0
在取图命令的终端中，按Ctrl+C退出采集操作。
5.5.3 硬触发
使用jetson-gpio进行触发操作，首先请安装并配置好jetson-gpio。
下面以使用jetson GPIO40（Board num）为模拟触发源，上升沿触发为例。
可以使用mv_mipi_i2c.sh脚本进行丰富的触发参数设置。
5.5.3.1 硬件连接
5.5.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
5.5.3.3 开始取图
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=y8-3104x2064.raw
5.5.3.4 进行硬触发操作
python gpio_trigger_jetson.py
Note:触发脚本链接。
5.5.3.5 停止触发和采集
由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。
v4l2-ctl --set-ctrl vi_time_out_disable=0
在取图命令的终端中，按Ctrl+C退出采集操作。
5.6 触发模式(C语言demo)