GX series camera appnotes 4 jetson

中文

1 overview

The GX series cameras are designed for embedded AI applications, featuring outstanding ISP performance, multiple working modes, a wealth of functional options, and reliable stability design. They use the MIPI CSI-2 interface and are particularly suitable for embedded computing platforms.

This article introduces how to use GX series cameras on the NVIDIA Jetson platform.

1.1 Supported camera modules

series	model	status
GX Series	GX-MIPI-IMX662	complete

1.2 Supported Jetson Board

Jetson model	status
XAVIER NX	complete
Orin NX	complete
Orin Nano	complete

1.3 Supported L4T versions

• Jetpack5.1.4,L4T version r35.6
• Jetpack6.2.1,L4T version r36.4.4

1.3.1 How to check the current L4T version

On the Jetson board, check the current L4T version and try to replace it with the same version.

cat /etc/nv_tegra_release

As shown:

# R32 (release), REVISION: 7.1......

This indicates that the current L4T version is 32.7.1, and the corresponding Jetpack version is Jetpack 32.6.1.

2 Hardware preparation and installation

The GX series cameras require a adapter board to be connected to the Jetson platform. The supported conditions are as shown in the table below:

Camera model	Jetson model	FFC line	Number of cameras	Additional power supply
GX Series	XAVIER NX	15-pin to 22-pin face-to-face FFC conversion connector	2	5V DC (must be provided)
	Orin Nano Orin NX	22-pin oblique FFC	2	5V DC (must be provided)

2.1 GX camera connected to Xavier NX

TBD

2.2 The GX camera is connected to Orin Nano or Orin NX.

TBD

3 Update the Jetson system

This section describes how to update the L4T system of Jetson to support the GX camera module. For the method of operating system update, please refer to the update instructions for Jetson operating system.

In particular, if you need the external trigger function, you need to apply a patch to the original kernel of Jetson - veye_mv_l4t_<version>.patch.

This patch has two functions:

1. Added support for two data formats, Y10 and Y12, for black-and-white cameras.
2. Added support for the trigger mode.

4 Support for the Trigger mode

The default driver of the Jetson system only supports video streaming mode. In its VI driver, the data reception function has a timeout mechanism. We have added a configurable option named "vi_time_out_disable" which allows for dynamically enabling or disabling this timeout mechanism.

For specific applications, please refer to the following application examples.

5 System status monitoring

After completing the system update, restart the Jetson motherboard.

During the startup process of the Jetson system, it will check whether there are any cameras on all i2c buses. If there are, it will create a /dev/videoX device node.

Execute the following commands on the Jetson board to check if the camera is properly connected.

dmesg | grep gxcam

It can be seen that during the Linux startup process, the camera model and version number that were probed are as follows:

For example, the following prompt indicates that a GX-MIPI-IMX662 camera has been detected on the i2c-9 bus.

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脚本使用

后文中使用的媒体设备节点、视频设备节点、子设备节点、I²C 总线及设备名称，均可参考此探测脚本得到的json文件中的信息进行替换。

摄像头模组在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.2 gx_probe.sh

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

如此，则方便后续使用media-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 保存图片到文件

9.3.1 通常情况下

此处的通常情况，指的是WIDTH是256的整数倍。

• UYVY格式

以XAVIER平台为例

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

9.3.2 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

下面是在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

                   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预览GREY格式图像

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 开始取图

• 通常情况下

此处的通常情况，指的是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.3 设置模式

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.4 开始取图

• 通常情况下

此处的通常情况，指的是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.5 进行硬触发操作

python gpio_trigger_jetson.py

Note:触发脚本链接。

11.4.3.6 停止触发和采集

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

v4l2-ctl --set-ctrl vi_time_out_disable=0

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

11.5 同步模式

11.5.1 设置同步模式

$ v4l2-ctl --set-ctrl work_mode=4

11.5.2 设置主从相机

主相机：

$ v4l2-ctl --set-ctrl sync_role=0

从相机：

$ v4l2-ctl --set-ctrl sync_role=1

11.5.3 开始取图

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

12 i2c脚本使用说明

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

gx_mipi_i2c.sh user guide

14 本文修改记录

• 2025-12-11

第一个发布版本