GX series camera appnotes 4 jetson/zh
1 概述
GX系列相机是为工业领域的AI应用推出的相机。其使用MIPI CSI-2接口，尤其适合嵌入式运算平台使用。它具备丰富的数据格式和触发特性，极高的带宽和可靠的稳定性。
本文介绍了如何在英伟达Jetson平台使用GX系列相机。
1.1 支持的摄像机模组
| 系列 | 型号 | 状态 |
|---|---|---|
| GX系列 | GX-MIPI-IMX662 | 完成 |
1.2 支持的Jetson Board
| Jetson型号 | 状态 |
|---|---|
| Nano A02 | 完成 |
| Nano B01 | 完成 |
| Nano 2GB | 完成 |
| TX2 NX | 完成 |
| XAVIER NX | 完成 |
| TX2 Devkit | 完成 |
| AGX Xavier | 完成 |
| AGX Orin | 完成 |
| Orin NX | 完成 |
| Orin Nano | 完成 |
1.3 支持的L4T版本
- Jetpack4.6.1,L4T版本r32.7.1
- Jetpack4.6.3,L4T版本r32.7.3
- Jetpack4.6.4,L4T版本r32.7.4
- Jetpack5.0.2,L4T版本r35.1
- Jetpack5.1,L4T版本r35.2.1
- Jetpack5.1.1,L4T版本r35.3.1
- Jetpack5.1.2,L4T版本r35.4.1
- Jetpack5.1.3,L4T版本r35.5
- Jetpack5.1.4,L4T版本r35.6
- Jetpack6.0,L4T版本r36.3
- Jetpack6.1,L4T版本r36.4
- Jetpack6.2,L4T版本r36.4.3
- Jetpack6.2.1,L4T版本r36.4.4
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平台。支持情况如下表：
| Camera型号 | Jetson型号 | 转接板 | FFC线(to 转接板) | FFC线(to Jetson主板) | 摄像机数量 | 额外供电 |
|---|---|---|---|---|---|---|
| GX系列 | Nano A02 | ADP-MV1 | 30pin异面FFC | 15pin异面FFC | 1 | 5V DC（必须） |
| Nano B01 | ADP-MV1 | 30pin异面FFC | 15pin异面FFC | 2 | 5V DC（必须） | |
| Nano 2GB | ADP-MV1 | 30pin异面FFC | 15pin异面FFC | 1 | 5V DC（必须） | |
| TX2 NX | ADP-MV1 | 30pin异面FFC | 15pin异面FFC | 2 | 5V DC（必须） | |
| XAVIER NX | ADP-MV1 | 30pin异面FFC | 15pin异面FFC | 2 | 5V DC（必须） | |
| Orin Nano
Orin NX |
ADP-MV1 | 30pin异面FFC | 15to22 pin 同面FFC | 2 | 5V DC（必须） | |
| Orin Nano
Orin NX |
ADP-MV1-V2
支持4-lane |
30pin异面FFC | 22pin 异面FFC | 2 | 5V DC（必须） | |
| TX2 Devkit | ADP-N4 | 30pin异面FFC | B2B连接器 | 6 | 5V或12V DC (必须) | |
| AGX Xavier | ADP-N4 | 30pin异面FFC | B2B连接器 | 6 | 5V或12V DC (必须) | |
| AGX Orin | ADP-N4 | 30pin异面FFC | B2B连接器 | 6 | 5V或12V DC (必须) |
2.1 MV系列摄像头使用ADP-MV1的连接方式
2.1.1 MV系列摄像头与ADP-MV1的连接
二者使用0.5mm间距*30P的FFC异面线连接，注意接触面向外。
| TOP | BOTTOM |
|---|---|
2.1.2 供电
ADP-MV1需要独立的5V供电，可以使用杜邦线直接从Jetson主板取电。
2.1.3 使用ADP-MV1连接到Nano和Xavier NX
Nano系列和NX系列采用这种连接方式。
2.1.4 使用ADP-MV1连接到Orin Nano和 Orin NX
二者使用15P转22Pin的FFC同面线连接，注意接触面方向。
2.2 MV系列摄像头使用ADP-N4的连接方式
2.2.1 MV系列摄像头与ADP-N4的连接
二者使用0.5mm间距*30P的FFC同面线连接，注意接触面向外。
2.2.2 供电
ADP-N4需要独立的供电。它支持两种供电方式，二选其一即可。
- 5V DC 接到 J19-9。可以使用杜邦线直接从Jetson主板取电。
- 12V DC 接到J11。需使用外置适配器供电。
2.2.3 使用ADP-N4的连接到TX2和AGX
注意，使用中请务必用螺丝将ADP转接板固定到底板上面,以保证转接板安装平正。
2.3 RAW系列摄像头直接连接到Jetson主板
2.3.1 RAW系列摄像头连接到Nano和Xavier NX
RAW-MIPI-SC132M使用15pin异面FFC线，其他RAW系列相机使用15to22pin同面FFC线。注意相机端，FPC排线银色接触面向外。
2.3.2 RAW系列摄像头连接到Orin Nano和 Orin NX
RAW-MIPI-SC132M使用15to22pin同面FFC线，其他RAW系列相机使用22pin异面FFC线。注意相机端，FPC排线银色接触面向外。
2.4 RAW系列摄像头使用ADP-N5的连接方式
2.4.1 RAW系列摄像头与ADP-N5的连接
RAW-MIPI-SC132M使用15pin异面FFC线，其他RAW系列相机使用15to22pin同面FFC线。
2.4.2 使用ADP-N5连接到TX2和AGX
2.5 V-by-One-HS-KIT摄像机连接示意图
3 更新Jetson系统
本章节描述怎样更新Jetson的L4T系统以支持MV摄像头模组。操作系统更新方法，请参考更新Jetson操作系统。
特别的，对于MV系列相机，除了在linux系统中增加了摄像头的驱动，我们还增加了一个内核补丁——veye_mv_l4t_<verion>.patch，并提供编译好的Image文件。
这个patch具备两个功能：
- 增加了黑白相机的Y10和Y12两种数据格式的支持。
- 增加了trigger模式的支持。
4 Trigger模式的支持
Jetson系统的默认驱动只支持视频流模式。在其VI驱动中，数据接收功能具有超时机制。我们增加了一个可设的vi_time_out_disable选项，可以动态打开和关闭这个超时机制。
具体应用参考下面的应用范例。
5 系统状态检测
完成系统更新后，重启Jetson主板。
Jetson系统启动过程中，会检测所有i2c bus上摄像头是否存在，如果存在则生成/dev/videoX设备节点。
在Jetson板端执行以下命令来检测是否正确连接摄像头。
dmesg | grep gxcam
可以看到linux启动阶段probe到的相机型号和以及相机的版本号：
比如下面这个提示，表示在i2c-10总线上检测到了GX-MIPI-IMX662摄像机。
gxcam 10-003b: camera is: GX-MIPI-IMX662
5.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来访问不同的摄像头。
6 veye_viewer
veye_viewer是一个开源的，基于QT5的客户端软件。
代码以及使用请参考：https://github.com/veyeimaging/veye_viewer。
国内用户可访问gitee仓库。
7 状态检测并配置环境变量
在这里，我们提供了两个脚本，可以自动检索相机的一些信息。
7.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 10-003b",
"i2c_bus": "10"
}
]
{}内是一个摄像头的信息，如果主板支持多个摄像头模组，则会出现多组{}包含的内容。
摄像头信息解释如下：
| 代称 | 名称 | 作用 | 何处使用 |
|---|---|---|---|
| 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文件中的信息进行替换。
7.2 gx_probe.sh
使用gx_probe.sh脚本，可以将某一个相机对应的I²C总线编号、相机型号、宽、高、帧率等信息配置到环境变量中。
如此，则方便后续使用media-ctl配置格式使用起来更方便。
使用方法是：
$ source ./gx_probe.sh i2c_bus
一个典型的输出如下：
$ source ./gx_probe.sh 10
Found veye_gxcam camera on i2c-10.
Setenv I2C_BUS = 10
Setenv CAMERAMODEL = GX-MIPI-IMX662
Setenv FPS = 60
Setenv WIDTH = 1920
Setenv HEIGHT = 1080
可以通过 echo $CAMERAMODEL来验证环境变量的输出结果。注意，此环境变量只对当前会话有效。
8 实时预览
8.1 使用veye_viewer播放图像
veye_viewer是一个开源的，基于QT5的客户端软件。
代码以及使用请参考：https://github.com/veyeimaging/veye_viewer。
国内用户可访问gitee仓库。
8.2 使用qv4l2预览画面
首先安装qv4l2
sudo apt install qv4l2
1. 在命令行中输入qv4l2以启动 V4L2 播放器。
2. 点击 ▶（播放）按钮以调出打开的媒体窗口。
8.3 使用VLC预览画面
Install vlc，
sudo apt-get install vlc
1. Open VLC with command line vlc , or click the icon to launch.
2. Hit the ▶(Play) button to call the open media window.
3. In Capture Device >> Device Selection >> Video device name, select the camera video node.
4. Hit Advanced Options... button
5. Type in the width and height, for example, 1280 and 1024.
6. Hit OK to save the settings and see the video feed.
9 Gstreamer Usage
要安装最新的加速版 gstreamer 插件和应用程序，请运行以下命令：
sudo apt-get update
sudo apt-get install nvidia-l4t-gstreamer
sudo ldconfig
rm -rf .cache/gstreamer-1.0/
export DISPLAY=:0
- 视频预览1080p HD
gst-launch-1.0 nvv4l2camerasrc device=/dev/video0 ! "video/x-raw(memory:NVMM),format=(string)UYVY, width=(int)1920, height=(int)1080" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nv3dsink sync=false
gst-launch-1.0 nvv4l2camerasrc device=/dev/video0 ! "video/x-raw(memory:NVMM),format=(string)UYVY, width=(int)1920, height=(int)1080" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)NV12" ! nv3dsink sync=false
- 视频预览1080p HD(using xvimagesink sink if supported)
export DISPLAY=:0
gst-launch-1.0 -e v4l2src io-mode=4 device=/dev/video0 do-timestamp=true ! 'video/x-raw, width=1920, height=1080, framerate=30/1, format=UYVY' ! xvimagesink sync=false
- 视频预览720p@60 HD(模组支持此分辨率时)
gst-launch-1.0 nvv4l2camerasrc ! "video/x-raw(memory:NVMM),format=(string)UYVY, width=(int)1280, height=(int)720, framerate=(fraction)60/1" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nv3dsink sync=false
- 视频预览1280*1080@45fpsHD
gst-launch-1.0 nvv4l2camerasrc ! "video/x-raw(memory:NVMM),format=(string)UYVY, width=(int)1280, height=(int)1080, framerate=(fraction)45/1" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nv3dsink sync=false
- 视频预览640*480@130fps(模组支持此分辨率时)
gst-launch-1.0 nvv4l2camerasrc ! "video/x-raw(memory:NVMM),format=(string)UYVY, width=(int)640, height=(int)480, framerate=(fraction)130/1" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nv3dsink sync=false
- 并列预览两路视频 1080p HD
WIDTH=960
HEIGHT=540
CAPS="video/x-raw(memory:NVMM),format=(string)UYVY, width=1920, height=1080"
gst-launch-1.0 nvcompositor name=comp sink_0::xpos=0 sink_0::ypos=0 sink_0::width=$WIDTH sink_0::height=$HEIGHT sink_1::xpos=$WIDTH sink_1::ypos=0 sink_1::width=$WIDTH sink_1::height=$HEIGHT ! nv3dsink nvv4l2camerasrc device=/dev/video0 ! $CAPS ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420"! comp. nvv4l2camerasrc device=/dev/video1 ! $CAPS ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420"! comp.
- Gstreamer 嵌入到 OpenCV
I think maybe OpenCV do not support I420 data format input，so you should convert it to BGR format.
gst-launch-1.0 nvv4l2camerasrc ! video/x-raw(memory:NVMM), format=(string)UYVY, width=(int)1920, height=(int)1080 ! nvvidconv ! video/x-raw(memory:NVMM), format=(string)I420 ! nvvidconv ! video/x-raw, format=(string)BGRx ! videoconvert ! video/x-raw, format=(string)BGR ! appsink
- 视频录像1080p HD
gst-launch-1.0 nvv4l2camerasrc num-buffers=300 ! "video/x-raw(memory:NVMM),format=(string)UYVY, width=(int)1920, height=(int)1080" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)NV12" ! nvv4l2h264enc control-rate=1 bitrate=10000000 ! h264parse ! qtmux ! filesink location=filename.mp4 -e
- 录像回放
gst-launch-1.0 filesrc location=filename.mp4 ! qtdemux ! queue ! h264parse ! nvv4l2decoder ! nv3dsink -e
- 抓拍图片
gst-launch-1.0 v4l2src num-buffers=1 ! "video/x-raw,format=(string)UYVY, width=(int)1920, height=(int)1080" ! nvvidconv ! "video/x-raw(memory:NVMM),format=(string)I420" ! nvjpegenc ! filesink location=jpgname.jpg
10 Jetson multimedia-api samples
Jetson平台上提供了Jetson Linux API 供开发者使用。具体jetson_multimedia_api包的安装请参考nVidia官方文档。
对于GX系列相机，已经在相机内集成了ISP功能，因此不能使用libargus获取数据，而可以直接使用使用标准V4L2接口从/dev/videoX设备文件获取数据。
下面两个sample可以直接运行：
10.1 12_camera_v4l2_cuda
./camera_v4l2_cuda -d /dev/video0 -s 1920x1080 -f UYVY
10.2 v4l2cuda
./capture-cuda -d /dev/video0 -f UYVY -m -o out.ppm -s 1920x1080 -c 1
11 v4l2-ctl 应用范例
11.1 安装v4l2-utils
sudo apt-get install v4l-utils
11.2 使用v4l2-ctl配置参数
11.2.1 列出相机支持的数据格式
v4l2-ctl --list-formats-ext
下面是在XAVIER系统下，GX-MIPI-IMX662的例子：
ioctl: VIDIOC_ENUM_FMT
Type: Video Capture
[0]: 'UYVY' (UYVY 4:2:2)
Size: Discrete 1920x1080
Interval: Discrete 0.017s (60.000 fps)
[1]: 'YUYV' (YUYV 4:2:2)
[2]: 'NV16' (Y/CbCr 4:2:2)
Size: Discrete 1920x1080
Interval: Discrete 0.017s (60.000 fps)
- 帧率统计
v4l2-ctl --set-fmt-video=width=1920,height=1080,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null
- 保存图片到文件
v4l2-ctl --set-fmt-video=width=1920,height=1080,pixelformat=UYVY --stream-mmap --stream-count=1 --stream-to=uyvy-1920x1080.yuv
11.2.2 列出驱动中实现的相机的可配置参数
v4l2-ctl -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) : 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 --set-ctrl [ctrl_type]=[val]
v4l2-ctl --get-ctrl [ctrl_type]
以上所有功能，均可使用gx_mipi_i2c.sh实现。
需要指出的是，以上参数在开始取图的状态均不可修改。下面进行逐个说明：
11.2.3 配置触发模式
v4l2-ctl --set-ctrl trigger_mode=[0-2]
0：流模式
1：普通触发模式
2：多相机同步模式
11.2.4 配置触发源
v4l2-ctl --set-ctrl trigger_src=[0-1]
0: 软触发
1: 硬触发
11.2.5 软触发一次
v4l2-ctl --set-ctrl soft_trgone=1
11.2.6 设置帧率
v4l2-ctl --set-ctrl frame_rate=[1-max]
随分辨率的调整，最大帧率会自动更新。
11.3 流模式
11.3.1 设置图像格式
以最大画面为例：
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY
v4l2-ctl --set-ctrl frame_rate=$FPS
11.3.2 帧率统计
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null
11.3.3 保存图片到文件
11.3.3.1 通常情况下
此处的通常情况，指的是WIDTH是256的整数倍。
- 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"
11.3.3.2 使用opencv预览GREY格式图像
sudo apt install python3-opencv
- 我们提供了一个简单的sample实现此功能：
python3 ./v4l2dev_2_opencv_show_grey.py --roix 0 --roiy 0 --width 640 --height 480 --fps 30
11.4 触发模式
11.4.1 准备工作
v4l2-ctl --set-ctrl low_latency_mode=1
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY
v4l2-ctl --set-ctrl frame_rate=$FPS
11.4.2 软触发
11.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
11.4.2.2 开始取图
- 通常情况下
此处的通常情况，指的是WIDTH是256的整数倍。
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to="uyvy-${WIDTH}x${HEIGHT}.yuv"
- GX-MIPI-IMX662
v4l2-ctl --set-fmt-video=width=1920,height=1080,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=uyvy-1920x1080.yuv
11.4.2.3 进行软触发操作
在其他的shell终端，可以多次执行下面命令进行多次触发。
v4l2-ctl --set-ctrl soft_trgone=1
11.4.2.4 停止触发和采集
由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。
v4l2-ctl --set-ctrl vi_time_out_disable=0
在取图命令的终端中，按Ctrl+C退出采集操作。
11.4.3 硬触发
使用jetson-gpio进行触发操作，首先请安装并配置好jetson-gpio。
下面以使用jetson GPIO40（Board num）为模拟触发源，上升沿触发为例。
可以使用gx_mipi_i2c.sh脚本进行丰富的触发参数设置。
11.4.3.1 硬件连接
- 使用ADP-MV1时
- 使用ADP-N4时
如采用公共触发源连接，则首先将J7成对短接，然后将jetson GPIO40接到J19-1。
如采用独立触发源连接，则直接将 GPIO40接到J7-1---J7-11。
11.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
11.4.3.3 开始取图
- 通常情况下
此处的通常情况，指的是WIDTH是256的整数倍。
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to="uyvy-${WIDTH}x${HEIGHT}.yuv"
11.4.3.4 进行硬触发操作
python gpio_trigger_jetson.py
Note:触发脚本链接。
11.4.3.5 停止触发和采集
由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。
v4l2-ctl --set-ctrl vi_time_out_disable=0
在取图命令的终端中，按Ctrl+C退出采集操作。
12 Application demo
12.1 v4l2grab_mvcam_jetson
v4l2grab_mvcam是一个C语言开发的sample，支持流模式和触发模式。
国内用户可访问gitee仓库。
12.2 yavta(仅支持流模式)
12.2.1 yavta安装
git clone https://github.com/veyeimaging/yavta.git
cd yavta;make
国内用户可访问gitee仓库。
12.2.2 设置图像格式
v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY
12.2.3 保存图片到文件
12.2.3.1 通常情况下
此处的通常情况，指的是WIDTH是256的整数倍。
- UYVY格式
以XAVIER平台为例
./yavta -c1 -F"uyvy-${WIDTH}x${HEIGHT}.yuv" --skip 0 -f UYVY -s "${WIDTH}x${HEIGHT}" /dev/video0
12.2.3.2 GX-MIPI-IMX662
./yavta -c1 -FUYVY-1920x1080.yuv --skip 0 -f UYVY -s 1920x1080 /dev/video0
13 i2c脚本使用说明
我们提供了shell脚本来配置参数。
14 参考资料
15 本文修改记录
- 2025-12-11
第一个发布版本