GX series camera appnotes 4 jetson/zh

English

1 概述

GX系列相机是为嵌入式的AI应用推出的相机，具备卓越的ISP性能，多种工作模式，丰富的功能选项，可靠的稳定性设计。其使用MIPI CSI-2接口，尤其适合嵌入式运算平台使用。

本文介绍了如何在英伟达Jetson平台使用GX系列相机。

1.1 支持的摄像机模组

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

1.2 支持的Jetson Board

Jetson型号	状态
Xavier NX	完成
Orin NX	完成
Orin Nano	完成

1.3 支持的L4T版本

• Jetpack5.1.4,L4T版本r35.6
• 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 硬件准备以及安装

GX系列相机需要转接板才可以接入Jetson平台。支持情况如下表：

Camera型号	Jetson型号	FFC线	摄像机数量	供电
GX系列	Xavier NX	15pin转22pin同面FFC	2	5V DC（必须）
	Orin Nano Orin NX	22pin异面FFC	2	5V DC（必须）

2.1 GX相机接到Xavier NX

GX Camera to Xavier NX

2.2 GX相机接到Orin Nano或者Orin NX

GX camera to Orin NX/Nano

3 更新Jetson系统

本章节描述怎样更新Jetson的L4T系统以支持GX摄像头模组。操作系统更新方法，请参考更新Jetson操作系统。

特别的，如果需要触发功能，需要对Jetson原本的内核打一个补丁——veye_mv_l4t_<verion>.patch。

这个patch具备两个功能：

1. 增加了黑白相机的Y10和Y12两种数据格式的支持。
2. 增加了trigger模式的支持。

4 Trigger模式的支持

Jetson系统的默认驱动只支持视频流模式。在其VI驱动中，数据接收功能具有超时机制。我们增加了一个可设的vi_time_out_disable选项，可以动态打开和关闭这个超时机制。

具体应用参考下面的应用范例。

5 系统状态检测

完成系统更新后，重启Jetson主板。

Jetson系统启动过程中，会检测所有i2c bus上摄像头是否存在，如果存在则生成/dev/videoX设备节点。

在Jetson板端执行以下命令来检测是否正确连接摄像头。

dmesg | grep gxcam

可以看到linux启动阶段probe到的相机型号和以及相机的版本号：

比如下面这个提示，表示在i2c-9总线上检测到了GX-MIPI-IMX662摄像机。

gxcam 9-003b: camera is: GX-MIPI-IMX662

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

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

6.1 probe_camera_info-jetson.sh

该脚本用于探测已连接并成功注册的摄像头设备，检索设备对应的视频设备节点、I²C 总线等信息。

执行后，将在当前目录生成 auto_camera_index.json 文件并在文件中记录检索到的信息。

下面是一个例子：

$ ./probe_camera_info-jetson.sh

cat auto_camera_index.json

[

{"i2c_bus": "9", "video_node": "/dev/video0"}

]

{}内是一个摄像头的信息，如果主板支持多个摄像头模组，则会出现多组{}包含的内容。

摄像头信息解释如下：

摄像头信息

代称	名称	作用	何处使用
video_node	视频设备节点(Video capture device node)	典型 V4L2 视频设备	v4l2-ctl或者客户开发的程序，获取图像时使用。也用于配置部分相机参数。
i2c_bus	I²C 总线号	表示设备连接的 I²C 总线编号	对摄像头进行参数配置的底层通信信道，gx_mipi_i2c.sh脚本使用

• 后文中使用的视频设备节点（video node）和 I²C 总线号，可以参考 probe_camera_info-jetson.sh 脚本生成的 JSON 文件中的信息进行替换。
• 在 Jetson 系统中，每个摄像头模组会被映射为 /dev/videoX 设备节点。
• 操作系统启动时，会按 I²C 总线号从小到大依次探测摄像头。设备节点中的 X 值按照探测顺序从 0 开始递增。
  • 例如，如果只接入一个摄像头，无论硬件连接到哪个 I²C 位置，X 都为 0。
  • 如果接入 5 个摄像头，则 X 值按照 I²C 总线号从小到大依次为 [0-4]。
• 在 v4l2-ctl 命令中，可通过 -d /dev/videoX 指定不同摄像头进行操作。

• 在 GStreamer 中，v4l2src 可以通过 device=/dev/videoX 指定不同摄像头。

6.2 gx_probe.sh

使用gx_probe.sh脚本，可以将某一个相机对应的I²C总线编号、相机型号、宽、高、帧率等信息配置到环境变量中。

如此，则后续使用v4l2-ctl操作起来更方便。

使用方法是：

$ source ./gx_probe.sh i2c_bus

一个典型的输出如下：

$ source ./gx_probe.sh 9

Found veye_gxcam camera on i2c-9.

Setenv I2C_BUS = 9

Setenv CAMERAMODEL = GX-MIPI-IMX662

Setenv FPS = 60

Setenv WIDTH = 1920

Setenv HEIGHT = 1080

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

7 实时预览

7.1 veye_viewer

veye_viewer是一个开源的，基于QT5的客户端软件。

代码以及使用请参考：https://github.com/veyeimaging/veye_viewer。

国内用户可访问gitee仓库。

7.2 使用qv4l2预览画面

首先安装qv4l2

sudo apt install qv4l2

1. 在命令行中输入qv4l2以启动 V4L2 播放器。

2. 点击 ▶（播放）按钮以调出打开的媒体窗口。

Play gx camera using qv4l2

8 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

• 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

9 yavta(仅支持流模式)

9.1 yavta安装

git clone https://github.com/veyeimaging/yavta.git

cd yavta;make

国内用户可访问gitee仓库。

9.2 设置图像格式

v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY

9.3 保存图片到文件

• UYVY格式

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

• GX-MIPI-IMX662

./yavta -c1 -Fuyvy-1920x1080.yuv --skip 0 -f UYVY -s 1920x1080 /dev/video0

10 Jetson multimedia-api samples

Jetson平台上提供了Jetson Linux API 供开发者使用。具体jetson_multimedia_api包的安装请参考nVidia官方文档。

对于GX系列相机，已经在相机内集成了ISP功能，因此不能使用libargus获取数据，而可以直接使用使用标准V4L2接口从/dev/videoX设备文件获取数据。

安装 Jetson 系统后，可进入多媒体 API 示例目录，自行编译并运行以下命令以预览摄像头视频:

cd /usr/src/jetson_multimedia_api/samples/12_v4l2_camera_cuda

make

./v4l2_camera_cuda -d /dev/video0 -s 1920x1080 -f UYVY

该命令将使用 /dev/video0 设备，以 1920×1080 分辨率和 UYVY 格式进行实时视频预览。

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

典型输出如下：

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

                   work_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 work_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 通常情况下

• 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预览图像

sudo apt install python3-opencv

• 我们提供了一个简单的sample实现此功能：

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

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 work_mode=1

v4l2-ctl --set-ctrl trigger_src=0

v4l2-ctl --set-ctrl vi_time_out_disable=1

11.4.2.2 开始取图

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 设置模式

v4l2-ctl --set-ctrl work_mode=1

v4l2-ctl --set-ctrl trigger_src=1

v4l2-ctl --set-ctrl vi_time_out_disable=1

11.4.3.2 开始取图

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.3 进行硬触发操作

python gpio_trigger_jetson.py

Note:触发脚本链接。

11.4.3.4 停止触发和采集

由于内核驱动中，死循环等待新图片，因此需要先取消vi_time_out_disable，然后再退出采集操作。

v4l2-ctl --set-ctrl vi_time_out_disable=0

在取图命令的终端中，按Ctrl+C退出采集操作。

11.5 同步模式

11.5.1 设置同步模式

$ v4l2-ctl -d /dev/video0 --set-ctrl work_mode=4

$ v4l2-ctl -d /dev/video1 --set-ctrl work_mode=4

11.5.2 设置主从相机

主相机：

$ v4l2-ctl -d /dev/video0 --set-ctrl sync_role=0

从相机：

$ v4l2-ctl -d /dev/video1 --set-ctrl sync_role=1

11.5.3 开始取图

同步模式下的取图方式与视频流模式下完全一致。

12 i2c脚本使用说明

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

gx_mipi_i2c.sh user guide

13 本文修改记录

• 2025-12-11

第一个发布版本