Difference between revisions of "GX Camera Application Development Guide"

From wiki_veye
Jump to navigation Jump to search
(Created page with "==== veye_viewe工具 ==== It can be downloaded from [https://github.com/veyeimaging/veye_viewer veye_viewe] We can use this tool to configure some parameters of the camera (...")
 
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
==== veye_viewe工具 ====
+
[[GX Camera Application Development Guide on Rochchip/zh|查看中文]]
−
It can be downloaded from [https://github.com/veyeimaging/veye_viewer veye_viewe]
 
  
−
We can use this tool to configure some parameters of the camera (directly operate and change the parameters of the register), switch the mode (stream mode, trigger mode, synchronization mode), and view some basic information of the camera (resolution, frame rate, etc.)
+
===Overview===
 +
This document applies to scenarios where the camera hardware is correctly connected, the driver is properly installed, and the GX series camera has been successfully recognized.
  
−
=== Application examples ===
+
The main objectives of this guide are to:
−
==== Configure parameters using v4l2-ctl ====
+
 
 +
*Query the device information of the connected GX series camera
 +
*Configure and prepare the camera operating modes
 +
*Introduce several methods for previewing and capturing images
 +
*Explain camera parameter configuration
 +
*Provide guidance for customer-specific development
 +
 
 +
On the Rockchip platform, regardless of the method used to access the camera, it is necessary to complete '''device detection''' and '''media-ctl configuration''' before performing any further operations. Therefore, the following sections first cover device detection and media-ctl setup.
 +
 
 +
===Device Detection and Environment Configuration===
 +
[https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/gx_i2c_tools Here], we provide two scripts that can automatically retrieve key information about the connected camera.
 +
 
 +
====probe_camera_info-rk.sh====
 +
This script is used to probe connected and successfully registered camera devices, retrieving underlying information such as the corresponding media device node, video device node, sub-device node, I²C bus, and device name.
 +
 
 +
After execution, an <code>auto_camera_index.json</code> file will be generated in the current directory, containing the retrieved information.
 +
 
 +
Example usage:
 +
 
 +
<code>$ ./probe_camera_info-rk.sh</code>
 +
 
 +
<code>cat auto_camera_index.json</code>
 +
 
 +
<code>[</code>
 +
 
 +
<code>  {</code>
 +
 
 +
<code>    "media_node": "/dev/media0",</code>
 +
 
 +
<code>    "video_node": "/dev/video0",</code>
 +
 
 +
<code>    "video_subnode": "/dev/v4l-subdev2",</code>
 +
 
 +
<code>    "media_entity_name": "m00_b_gxcam 7-003b",</code>
 +
 
 +
<code>    "i2c_bus": "7"</code>
 +
 
 +
<code>  }</code>
 +
 
 +
<code>]</code>
 +
 
 +
Each <code>{}</code> block represents a single camera. If the board supports multiple camera modules, multiple <code>{}</code> blocks will be present in the file.
 +
 
 +
Explanation of Camera Information：
 +
{| class="wikitable"
 +
|+Camera Information
 +
!Field
 +
!Name
 +
!Purpose
 +
!Usage
 +
|-
 +
|media_node
 +
|Media device node
 +
|Used to access the device within the media-controller framework
 +
|Used when configuring resolution and format via the <code>media-ctl</code> command
 +
|-
 +
|video_node
 +
|Video capture device node
 +
|Standard V4L2 video device
 +
|Used with <code>v4l2-ctl</code> or customer applications to capture images
 +
|-
 +
|video_subnode
 +
|V4L2 sub-device node
 +
|Used for configuring certain camera parameters
 +
|Accessed via <code>v4l2-ctl</code> commands
 +
|-
 +
|media_entity_name
 +
|Media entity name
 +
|Describes the device, e.g., <code>"m00_b_gxcam 7-003b"</code>
 +
|Used when setting resolution and format with <code>media-ctl</code>
 +
|-
 +
|i2c_bus
 +
|I²C bus
 +
|Indicates the I²C bus to which the device is connected
 +
|Used as the underlying communication channel for camera parameter configuration, e.g., by the <code>gx_mipi_i2c.sh</code> script
 +
|}
 +
The media device node, video device node, sub-device node, I²C bus, and device name used in the following sections can all be replaced with the corresponding information obtained from the JSON file generated by this probe script.
 +
 
 +
====gx_probe.sh====
 +
The <code>gx_probe.sh</code> script can configure environment variables with key information for a specific camera, including the I²C bus number, camera model, resolution (width and height), and frame rate. This simplifies subsequent use of <code>media-ctl</code> for format configuration.
 +
 
 +
The usage method is:
 +
 
 +
<code>$ source ./gx_probe.sh <i2c_bus></code>
 +
 
 +
Example:
 +
 
 +
<code>$ source ./gx_probe.sh 7</code>
 +
 
 +
<code>Found veye_gxcam camera on i2c-7.</code>
 +
 
 +
<code>Setenv CAMERAMODEL = GX-MIPI-IMX662</code>
 +
 
 +
<code>Setenv FPS = 60</code>
 +
 
 +
<code>Setenv WIDTH = 1920</code>
 +
 
 +
<code>Setenv HEIGHT = 1080</code>
 +
 
 +
You can verify the environment variable output using, for example:
 +
 
 +
<code>echo $CAMERAMODEL</code>
 +
 
 +
'''Note:''' These environment variables are valid only for the current shell session.
 +
 
 +
===Configuring Formats with media-ctl===
 +
 
 +
====Viewing the Topology with media-ctl====
 +
By using the <code>media-ctl</code> command, the current topology structure can be clearly displayed.
 +
 
 +
<code>media-ctl -p -d /dev/media0</code>
 +
 
 +
=====Link relationship=====
 +
<code>gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)</code>
 +
 
 +
The application can obtain images through the /dev/video0 node.
 +
 
 +
=====gx camera entity information=====
 +
Take GX-MIPI-IMX662 as an example:
 +
 
 +
<code>- entity 63: m00_b_gxcam 7-003b (1 pad, 1 link)</code>
 +
 
 +
<code>             type V4L2 subdev subtype Sensor flags 0</code>
 +
 
 +
<code>             device node name /dev/v4l-subdev2</code>
 +
 
 +
<code>        pad0: Source</code>
 +
 
 +
<code>                [fmt:UYVY8_2X8/1920x1080@10000/600000 field:none colorspace:rec709</code>
 +
 
 +
<code>                 crop:(0,0)/1920x1080]</code>
 +
 
 +
<code>                -> "rockchip-csi2-dphy0":0 [ENABLED]</code>
 +
 
 +
It can be seen that:
 +
 
 +
*The complete name of this Entity is: m00_b_gxcam 7-003b. (On the ROC-RK3566-PC, the name of this Entity is m00_b_gxcam 4-003b).
 +
*It is a V4L2 subdev (Sub-Device) sensor.
 +
*The corresponding node is /dev/v4l-subdev2. The application (such as v4l2-ctl) can open it and make configurations.
 +
*Its output format is [UYVY8_2X8/1920x1080@10000/600000 field:none], where UYVY8_2X8 is a shortened form of an mbus-code. The supported mbus-codes will be listed in the next section.
 +
*The current resolution is 1920x1080.
 +
*The current frame interval is 10000/600000, which means the frame rate is 60.
 +
 
 +
The data format output by the camera can be modified through the "media-ctl" command.
 +
====Camera-supported MBUS code====
 +
The GX series cameras utilize the UYVY data format capability. For details, please refer to the data manuals of each model of the cameras.
 +
{| class="wikitable"
 +
|+Format correspondence relationship
 +
!Format on datasheet
 +
!mbus-code for media-ctl
 +
!FourCC pixelformat for v4l2-ctl
 +
|-
 +
|UYVY
 +
|UYVY8_2X8
 +
|UYVY
 +
|}
 +
 
 +
====Configuring Image Formats with <code>media-ctl</code>====
 +
The camera data format, resolution, and frame rate can be configured using the following command:
 +
 
 +
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 +
 
 +
*<code>"m00_b_gxcam 7-003b"</code> specifies the full entity name of the camera.
 +
*<code>UYVY8_2X8</code> is the mbus-code.
 +
*<code>"$WIDTH"x"$HEIGHT"</code> indicates the resolution.
 +
*<code>1/"$FPS"</code> specifies the frame rate.
 +
 
 +
For example, for the '''GX-MIPI-IMX662''', after substituting the variables, the command becomes:
 +
 
 +
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'</code>
 +
 
 +
This command allows you to configure the data format, resolution, and frame rate in a single step. Individual parameters can also be modified separately if needed.
 +
 
 +
'''Note:''' The node names in <code>media-ctl</code> can be adjusted according to the information in the JSON file generated by the probe script to configure different cameras.
 +
 
 +
===veye_viewer===
 +
The <code>veye_viewer</code> is an open-source, Qt-based client application that allows users to easily evaluate cameras and configure parameters.
 +
 
 +
Its operation logs, register listings, and open-source nature provide a convenient reference for users and support custom development.
 +
 
 +
The source code of <code>veye_viewer</code> can be downloaded [https://github.com/veyeimaging/veye_viewer here], or platform-specific executable programs are available directly in its [https://github.com/veyeimaging/veye_viewer/releases release packages].
 +
 
 +
===yavta===
 +
 
 +
====Installing Yavta====
 +
<code>git clone <nowiki>git://git.ideasonboard.org/yavta.git</nowiki></code>
 +
 
 +
<code>$ cd yavta;make</code>
 +
 
 +
====Saving Images to a File====
 +
After configuring the data format, resolution, and frame rate, execute the following command to capture and save images:
 +
 
 +
<code>./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
 +
 
 +
*<code>-c1</code> specifies capturing 1 frame.
 +
*<code>-F</code> sets the output filename.
 +
*<code>--skip 0</code> disables frame skipping.
 +
*<code>-f UYVY</code> specifies the pixel format.
 +
*<code>-s ${WIDTH}x${HEIGHT}</code> sets the capture resolution.
 +
 
 +
*<code>/dev/video0</code> is the video device node.
 +
 
 +
===Importing Camera Data into OpenCV===
 +
Install OpenCV for Python:
 +
 
 +
<code>$ sudo apt install python3-opencv</code>
 +
 
 +
Example scripts can be found in the [https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples/opencv/veye%20camera samples] directory of the GitHub repository.
 +
 
 +
Run the sample program with appropriate parameters:
 +
 
 +
<code>$ python3 ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7</code>
 +
 
 +
'''Note:''' Ensure that the program is executed with the correct parameters matching your camera setup.
 +
 
 +
===GStreamer Examples===
 +
Several GStreamer example pipelines are provided to implement camera preview functionality. Detailed examples are available in the [https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples samples] directory on GitHub.
 +
 
 +
===v4l2-ctl Examples===
 +
The following example demonstrates how to configure the camera and capture images directly from the command line using <code>/dev/v4l-subdev2</code>, <code>/dev/media0</code>, and <code>/dev/video0</code>.
 +
 
 +
====install v4l2-utils​====
 +
<code>sudo apt-get install v4l-utils</code>
 +
 
 +
====Configure parameters using v4l2-ctl====
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 -L</code>
 
<code>$ v4l2-ctl -d /dev/v4l-subdev2 -L</code>
  
Line 26: Line 250:
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]</code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]</code>
  
−
All the above functions can be implemented using [https://wiki.veye.cc/index.php/Gx_mipi_i2c.sh_user_guide gx_mipi_i2c.sh].
+
All the above functions can be implemented using [[Gx mipi i2c.sh user guide|gx_mipi_i2c.sh]].
  
 
Note that the above parameters cannot be modified during the capture process.  
 
Note that the above parameters cannot be modified during the capture process.  
Line 52: Line 276:
 
The maximum frame rate is automatically updated as the resolution changed.
 
The maximum frame rate is automatically updated as the resolution changed.
  
−
==== Set image format using media-ctl ====
+
====Video Streaming mode====
−
use the following command to configure the camera's data format, resolution, and frame rate using <code>media-ctl</code>:
 
  
−
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
+
=====Set data format, resolution, frame rate=====
−
 
 
−
Among them: <code>"m00_b_gxcam '"$I2C_BUS"'-003b"</code> refers to the complete name of the camera entity, <code>UYVY8_2X8</code> is the mbus-code, <code>'"$WIDTH"'x'"$HEIGHT"'</code> indicates the resolution, <code>1/'"$FPS"'</code> indicates the resolution frame rate.
 
−
 
 
−
For example, for GX-MIPI-IMX662, the command after variable replacement would be:
 
−
 
 
−
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'</code>
 
−
 
 
−
You can not only configure the data format, resolution, and frame rate in one command, but also modify them separately as needed.
 
−
 
 
−
==== Video Streaming mode ====
 
−
 
 
−
===== Set data format, resolution, frame rate =====
 
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
=====Frame rate statistics=====
 
=====Frame rate statistics=====
Line 77: Line 288:
  
 
<code>./yavta -c1000 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
 
<code>./yavta -c1000 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
−
===== Save image to file =====
+
=====Save image to file=====
  
 
*UYVY
 
*UYVY
Line 85: Line 296:
 
Please refer to the description in the previous section for the image format.
 
Please refer to the description in the previous section for the image format.
  
−
===== Example of yavta =====
+
====Trigger mode====
−
 
 
−
====== Install yavta ======
 
−
<code>git clone <nowiki>git://git.ideasonboard.org/yavta.git</nowiki></code>
 
−
 
 
−
<code>cd yavta;make</code>
 
−
 
 
−
====== Save image to file ======
 
−
After setting data format, resolution, frame rate，run:
 
−
 
 
−
<code>./yavta -c1 -Fuyvy-${WIDTH}x${HEIGHT}.yuv --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0</code>
 
−
 
 
−
===== Example of import image to OpenCV =====
 
−
<code>sudo apt install python3-opencv</code>
 
−
 
 
−
See the [https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples samples] directory on github for details.
 
−
 
 
−
<code>python ./v4l2_opencv_show2.py --width 1920 --height 1080 --fps 60 --i2c 7</code>
 
  
−
===== Example of gstreamer application =====
+
=====Set data format, resolution, frame rate=====
−
We provide several gstreamer routines that implement the preview function. See the [https://github.com/veyeimaging/rk35xx_veye_bsp/tree/main/samples samples] directory on github for details.
 
−
 
 
−
==== Trigger mode ====
 
−
 
 
−
===== Set data format, resolution, frame rate =====
 
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
=====Software trigger mode=====
 
=====Software trigger mode=====
Line 117: Line 306:
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=0</small></code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=0</small></code>
  
−
====== Start acquisition ======
+
======Start acquisition======
 
<code>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</code>
 
<code>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</code>
  
Line 125: Line 314:
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>soft_trgone=1</small></code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>soft_trgone=1</small></code>
  
−
===== Hardware trigger mode =====
+
=====Hardware trigger mode=====
  
−
====== Set mode ======
+
======Set mode======
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=1</small></code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=1</small></code>
  
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=1</small></code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_src=1</small></code>
  
−
The [https://wiki.veye.cc/index.php/Gx_mipi_i2c.sh_user_guide gx_mipi_i2c.sh] script can be used to set rich trigger parameters.
+
The [[Gx mipi i2c.sh user guide|gx_mipi_i2c.sh]] script can be used to set rich trigger parameters.
  
−
====== Start acquisition ======
+
======Start acquisition======
 
<code>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</code>
 
<code>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</code>
  
−
====== Perform hardware trigger operation ======
+
======Perform hardware trigger operation======
 
Connect the appropriate trigger signal to the trigger pin of the camera and trigger it.
 
Connect the appropriate trigger signal to the trigger pin of the camera and trigger it.
  
−
==== synchronous mode ====
+
====Synchronous Mode====
 +
The following nodes and sub-devices should be selected according to the actual hardware configuration.
  
−
===== Set data format, resolution, frame rate =====
+
=====Set data format, resolution, frame rate=====
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
 
<code>media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'</code>
  
−
===== Switch to synchronous mode =====
+
=====Set synchronous mode=====
−
Note: The RK platform only supports one camera connection. Perform the following operations on both mainboard terminals to switch to synchronous mode.
 
−
 
 
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=</small>4</code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>trigger_mode=</small>4</code>
  
−
===== Set the camera as the master or slave. =====
+
=====Set the camera as the master or slave.=====
 
master camera：
 
master camera：
  
Line 159: Line 347:
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>sync_role=1</small></code>
 
<code>v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl <small>sync_role=1</small></code>
  
−
===== Start taking pictures =====
+
=====Start taking pictures=====
−
Several methods in the streaming mode can be used to take pictures.
+
The image capture method in synchronous mode is identical to that used in video streaming mode.
  
 
===i2c script for parameter configuration===
 
===i2c script for parameter configuration===
 
We provide shell scripts to configure the parameters.
 
We provide shell scripts to configure the parameters.
  
−
[https://wiki.veye.cc/index.php/Gx_mipi_i2c.sh_user_guide gx_mipi_i2c.sh user guide]
+
[[gx_mipi_i2c.sh user guide]]
  
−
=== Question Feedback ===
+
===Recommendations for Customer Integration and Development===
−
We are committed to providing richer possibilities for image applications on embedded platforms. Therefore, our software for embedded platforms is based on the principle of open source.
 
  
−
If you have any questions or suggestions about our existing software, please feel free to submit them to the [http://forum.veye.cc/ forum] or email our technical staff at xumm#csoneplus.com.
+
====Initialization Phase====
 +
During initialization, it is necessary to configure the resolution and frame rate. It is recommended that customers integrate calls to <code>media-ctl</code> and <code>v4l2-ctl</code> directly within their application’s initialization sequence to configure the resolution, frame rate, and data format.
  
 +
Do '''not''' use <code>gx_mipi_i2c.sh</code> to directly modify camera registers, as direct register changes will not be synchronized with the Rockchip Linux driver layers.
 +
 +
On Rockchip platforms, the nodes detected by <code>./probe_camera_info-rk.sh</code> are fixed for a given board. It is recommended that customers use the JSON output from this script as their application’s configuration file. Alternatively, the detected nodes can be hardcoded in the program based on this output.
 +
 +
====Operation Phase====
 +
Depending on the programming language used, customers can refer to the tools and examples provided earlier in this document.
 +
 +
Regarding timestamps, the <code>v4l2_buffer.timestamp</code> provides the precise time when the RK chip receives a complete frame, which can be used for camera synchronization or as a reference timestamp for other external sensors.
 +
 +
====Parameter Configuration====
 +
GX series cameras offer rich and flexible parameter options, which are mainly configured via the <code>gx_mipi_i2c.sh</code> script. For detailed instructions, refer to the register documentation and the <code>gx_mipi_i2c.sh</code> manual.
 +
 +
The <code>gx_mipi_i2c.sh</code> script includes a <code>paramsave</code> function that saves all configured parameters to the camera’s flash memory. However, frequent invocation of this function in programs is '''not recommended'''.
 +
<br />
 
===References===
 
===References===
  
Line 190: Line 392:
 
https://wiki.t-firefly.com/en/Firefly-Linux-Guide/index.html
 
https://wiki.t-firefly.com/en/Firefly-Linux-Guide/index.html
 
===Document History===
 
===Document History===
 +
2025-12-20
 +
 +
*Adjusted document structure and added several new sections.
  
−
*2025-11-28
+
2025-11-28
  
 
Release 1st version.<br />
 
Release 1st version.<br />

Latest revision as of 17:53, 26 January 2026

查看中文

1 Overview

This document applies to scenarios where the camera hardware is correctly connected, the driver is properly installed, and the GX series camera has been successfully recognized.

The main objectives of this guide are to:

  • Query the device information of the connected GX series camera
  • Configure and prepare the camera operating modes
  • Introduce several methods for previewing and capturing images
  • Explain camera parameter configuration
  • Provide guidance for customer-specific development

On the Rockchip platform, regardless of the method used to access the camera, it is necessary to complete device detection and media-ctl configuration before performing any further operations. Therefore, the following sections first cover device detection and media-ctl setup.

2 Device Detection and Environment Configuration

Here, we provide two scripts that can automatically retrieve key information about the connected camera.

2.1 probe_camera_info-rk.sh

This script is used to probe connected and successfully registered camera devices, retrieving underlying information such as the corresponding media device node, video device node, sub-device node, I²C bus, and device name.

After execution, an auto_camera_index.json file will be generated in the current directory, containing the retrieved information.

Example usage:

$ ./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 7-003b",

    "i2c_bus": "7"

  }

]

Each {} block represents a single camera. If the board supports multiple camera modules, multiple {} blocks will be present in the file.

Explanation of Camera Information：

Camera Information
Field Name Purpose Usage
media_node Media device node Used to access the device within the media-controller framework Used when configuring resolution and format via the media-ctl command
video_node Video capture device node Standard V4L2 video device Used with v4l2-ctl or customer applications to capture images
video_subnode V4L2 sub-device node Used for configuring certain camera parameters Accessed via v4l2-ctl commands
media_entity_name Media entity name Describes the device, e.g., "m00_b_gxcam 7-003b" Used when setting resolution and format with media-ctl
i2c_bus I²C bus Indicates the I²C bus to which the device is connected Used as the underlying communication channel for camera parameter configuration, e.g., by the gx_mipi_i2c.sh script

The media device node, video device node, sub-device node, I²C bus, and device name used in the following sections can all be replaced with the corresponding information obtained from the JSON file generated by this probe script.

2.2 gx_probe.sh

The gx_probe.sh script can configure environment variables with key information for a specific camera, including the I²C bus number, camera model, resolution (width and height), and frame rate. This simplifies subsequent use of media-ctl for format configuration.

The usage method is:

$ source ./gx_probe.sh <i2c_bus>

Example:

$ source ./gx_probe.sh 7

Found veye_gxcam camera on i2c-7.

Setenv CAMERAMODEL = GX-MIPI-IMX662

Setenv FPS = 60

Setenv WIDTH = 1920

Setenv HEIGHT = 1080

You can verify the environment variable output using, for example:

echo $CAMERAMODEL

Note: These environment variables are valid only for the current shell session.

3 Configuring Formats with media-ctl

3.1 Viewing the Topology with media-ctl

By using the media-ctl command, the current topology structure can be clearly displayed.

media-ctl -p -d /dev/media0

3.1.1 Link relationship

gx camera->rockchip-csi2-dphy0->rockchip-mipi-csi2->stream_cif_mipi_id0 - - ->DDR(/dev/video0)

The application can obtain images through the /dev/video0 node.

3.1.2 gx camera entity information

Take GX-MIPI-IMX662 as an example:

- entity 63: m00_b_gxcam 7-003b (1 pad, 1 link)

             type V4L2 subdev subtype Sensor flags 0

             device node name /dev/v4l-subdev2

        pad0: Source

                [fmt:UYVY8_2X8/1920x1080@10000/600000 field:none colorspace:rec709

                 crop:(0,0)/1920x1080]

                -> "rockchip-csi2-dphy0":0 [ENABLED]

It can be seen that:

  • The complete name of this Entity is: m00_b_gxcam 7-003b. (On the ROC-RK3566-PC, the name of this Entity is m00_b_gxcam 4-003b).
  • It is a V4L2 subdev (Sub-Device) sensor.
  • The corresponding node is /dev/v4l-subdev2. The application (such as v4l2-ctl) can open it and make configurations.
  • Its output format is [UYVY8_2X8/1920x1080@10000/600000 field:none], where UYVY8_2X8 is a shortened form of an mbus-code. The supported mbus-codes will be listed in the next section.
  • The current resolution is 1920x1080.
  • The current frame interval is 10000/600000, which means the frame rate is 60.

The data format output by the camera can be modified through the "media-ctl" command.

3.2 Camera-supported MBUS code

The GX series cameras utilize the UYVY data format capability. For details, please refer to the data manuals of each model of the cameras.

Format correspondence relationship
Format on datasheet mbus-code for media-ctl FourCC pixelformat for v4l2-ctl
UYVY UYVY8_2X8 UYVY

3.3 Configuring Image Formats with media-ctl

The camera data format, resolution, and frame rate can be configured using the following command:

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

  • "m00_b_gxcam 7-003b" specifies the full entity name of the camera.
  • UYVY8_2X8 is the mbus-code.
  • "$WIDTH"x"$HEIGHT" indicates the resolution.
  • 1/"$FPS" specifies the frame rate.

For example, for the GX-MIPI-IMX662, after substituting the variables, the command becomes:

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam 7-003b":0[fmt:UYVY8_2X8/1920x1080@1/60 field:none]'

This command allows you to configure the data format, resolution, and frame rate in a single step. Individual parameters can also be modified separately if needed.

Note: The node names in media-ctl can be adjusted according to the information in the JSON file generated by the probe script to configure different cameras.

4 veye_viewer

The veye_viewer is an open-source, Qt-based client application that allows users to easily evaluate cameras and configure parameters.

Its operation logs, register listings, and open-source nature provide a convenient reference for users and support custom development.

The source code of veye_viewer can be downloaded here, or platform-specific executable programs are available directly in its release packages.

5 yavta

5.1 Installing Yavta

git clone git://git.ideasonboard.org/yavta.git

$ cd yavta;make

5.2 Saving Images to a File

After configuring the data format, resolution, and frame rate, execute the following command to capture and save images:

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

  • -c1 specifies capturing 1 frame.
  • -F sets the output filename.
  • --skip 0 disables frame skipping.
  • -f UYVY specifies the pixel format.
  • -s ${WIDTH}x${HEIGHT} sets the capture resolution.
  • /dev/video0 is the video device node.

6 Importing Camera Data into OpenCV

Install OpenCV for Python:

$ sudo apt install python3-opencv

Example scripts can be found in the samples directory of the GitHub repository.

Run the sample program with appropriate parameters:

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

Note: Ensure that the program is executed with the correct parameters matching your camera setup.

7 GStreamer Examples

Several GStreamer example pipelines are provided to implement camera preview functionality. Detailed examples are available in the samples directory on GitHub.

8 v4l2-ctl Examples

The following example demonstrates how to configure the camera and capture images directly from the command line using /dev/v4l-subdev2, /dev/media0, and /dev/video0.

8.1 install v4l2-utils​

sudo apt-get install v4l-utils

8.2 Configure parameters using v4l2-ctl

$ v4l2-ctl -d /dev/v4l-subdev2 -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) : value=0 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

Parameters can be set and get using the following methods.

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl [ctrl_type]=[val]

v4l2-ctl -d /dev/v4l-subdev2 --get-ctrl [ctrl_type]

All the above functions can be implemented using gx_mipi_i2c.sh.

Note that the above parameters cannot be modified during the capture process.

The following is an explanation of each parameter:

8.2.1 Trigger Mode

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=[0-2]

0：Video streaming mode

1：Normal trigger mode.

4：Multi-camera synchronization mode.

8.2.2 Trigger Source

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=[0-1]

0: Software trigger mode.

1: Hardware trigger mode.

8.2.3 Software trigger command

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1

8.2.4 Set frame rate

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl frame_rate=[1-max]

The maximum frame rate is automatically updated as the resolution changed.

8.3 Video Streaming mode

8.3.1 Set data format, resolution, frame rate

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

8.3.2 Frame rate statistics

In streaming mode, the following commands can be used for frame rate statistics：

v4l2-ctl --set-fmt-video=width=$WIDTH,height=$HEIGHT,pixelformat=UYVY --stream-mmap --stream-count=-1 --stream-to=/dev/null

Or：

./yavta -c1000 --skip 0 -f UYVY -s ${WIDTH}x${HEIGHT} /dev/video0

8.3.3 Save image to file
  • 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

Please refer to the description in the previous section for the image format.

8.4 Trigger mode

8.4.1 Set data format, resolution, frame rate

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

8.4.2 Software trigger mode
8.4.2.1 Set mode

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=1

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=0

8.4.2.2 Start acquisition

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

8.4.2.3 Perform soft trigger operation

In other shell terminals, you can execute the following command multiple times for multiple triggers.

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl soft_trgone=1

8.4.3 Hardware trigger mode
8.4.3.1 Set mode

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=1

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_src=1

The gx_mipi_i2c.sh script can be used to set rich trigger parameters.

8.4.3.2 Start acquisition

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

8.4.3.3 Perform hardware trigger operation

Connect the appropriate trigger signal to the trigger pin of the camera and trigger it.

8.5 Synchronous Mode

The following nodes and sub-devices should be selected according to the actual hardware configuration.

8.5.1 Set data format, resolution, frame rate

media-ctl -d /dev/media0 --set-v4l2 '"m00_b_gxcam '"$I2C_BUS"'-003b":0[fmt:UYVY8_2X8/'"$WIDTH"'x'"$HEIGHT"'@1/'"$FPS"']'

8.5.2 Set synchronous mode

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl trigger_mode=4

8.5.3 Set the camera as the master or slave.

master camera：

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=0

slave camera：

v4l2-ctl -d /dev/v4l-subdev2 --set-ctrl sync_role=1

8.5.4 Start taking pictures

The image capture method in synchronous mode is identical to that used in video streaming mode.

9 i2c script for parameter configuration

We provide shell scripts to configure the parameters.

gx_mipi_i2c.sh user guide

10 Recommendations for Customer Integration and Development

10.1 Initialization Phase

During initialization, it is necessary to configure the resolution and frame rate. It is recommended that customers integrate calls to media-ctl and v4l2-ctl directly within their application’s initialization sequence to configure the resolution, frame rate, and data format.

Do not use gx_mipi_i2c.sh to directly modify camera registers, as direct register changes will not be synchronized with the Rockchip Linux driver layers.

On Rockchip platforms, the nodes detected by ./probe_camera_info-rk.sh are fixed for a given board. It is recommended that customers use the JSON output from this script as their application’s configuration file. Alternatively, the detected nodes can be hardcoded in the program based on this output.

10.2 Operation Phase

Depending on the programming language used, customers can refer to the tools and examples provided earlier in this document.

Regarding timestamps, the v4l2_buffer.timestamp provides the precise time when the RK chip receives a complete frame, which can be used for camera synchronization or as a reference timestamp for other external sensors.

10.3 Parameter Configuration

GX series cameras offer rich and flexible parameter options, which are mainly configured via the gx_mipi_i2c.sh script. For detailed instructions, refer to the register documentation and the gx_mipi_i2c.sh manual.

The gx_mipi_i2c.sh script includes a paramsave function that saves all configured parameters to the camera’s flash memory. However, frequent invocation of this function in programs is not recommended.

11 References

  • ROC-RK3566-PC Manual

https://wiki.t-firefly.com/en/ROC-RK3566-PC/

  • ROC-RK3588S-PC Manual

https://wiki.t-firefly.com/en/ROC-RK3588S-PC/

  • ROC-RK3576-PC Manual

https://wiki.t-firefly.com/en/ROC-RK3576-PC/

  • Firefly Linux User Guide

https://wiki.t-firefly.com/en/Firefly-Linux-Guide/index.html

12 Document History

2025-12-20

  • Adjusted document structure and added several new sections.

2025-11-28

Release 1st version.

Retrieved from "http://wiki.veye.cc/index.php?title=GX_Camera_Application_Development_Guide&oldid=9123"