Is this page helpful?

SIPL Query JSON Guide#

This guide describes how to author SIPL Query JSON databases for GMSL and Camera over Ethernet (CoE) camera systems on NVIDIA Jetson platforms. CoE and GMSL use the same SIPL Query APIs (see sipl/include/query/include/NvSIPLCameraQuery.hpp); the JSON layout and file layout differ by transport.

Warning

JetPack 7.2 JSON config change: Case-sensitive “name” fields. As of JetPack 7.2, module, transport, sensor, serializer, and deserializer "name" fields are compared case-sensitively against the corresponding driver-exported name. Values such as "vb1940" and "VB1940" are no longer equivalent. JetPack 7.1 JSON configurations that worked with lowercase or mixed-case names must be updated to match the exact casing exported by the driver (for example, "VB1940").

Use the CoE section for Ethernet/HSB camera configuration. Use the GMSL section for serializer/deserializer topology, sensor system config, component database files, and name-matching rules for GMSL drivers.

What Is SIPL Query?#

SIPL Query is a component of the Safe Image Processing Library (SIPL) framework that provides a database-driven approach to camera configuration and discovery. It provides APIs to load, validate, and provide camera and transport configuration to SIPL Core at runtime, enabling flexible and scalable camera integration.

If you are new to SIPL, read Introduction to SIPL first (including SIPL Architecture Overview); this JSON guide assumes that background.

Key Functions of SIPL Query

  • Loads camera, transport, and module configuration from JSON files.

  • Validates configuration against schema and hardware requirements.

  • Provides APIs for querying available cameras, transports, and their properties.

  • Enables runtime discovery and selection of camera modules.

SIPL Query is designed to decouple camera configuration from application code, making it easy to add, remove, or modify camera setups without recompiling your application and driver libraries.

SIPL Query API Overview#

The SIPL Query interface INvSIPLCameraQuery is defined in the public header sipl/include/query/include/NvSIPLCameraQuery.hpp.

Key API Calls

SIPL Query Interface API Calls#

API Function

Description

ParseDatabase()

Loads the built-in sensor/module/transport database from /usr/lib/nvsipl_drv/libnvsipl_qry_*.so.

ParseJsonFile(std::string fileName)

Loads a user-specified JSON file and overlays custom configuration on the database loaded by ParseDatabase().

GetDeviceInfoList()

Returns a list of available camera devices and transports.

GetCameraConfigNames()

Returns a list of available camera configuration names.

GetSensorSystemConfig()

Gets a full SensorSystemConfig by camera configuration name.

GetModuleConfig()

Gets one ModuleConfig by module name.

GetTransportSettings()

Gets one transport settings object by transport name.

GetVersion()

Returns the query interface version.

ApplyMask()

Enables or disables links in a SensorSystemConfig.

For a detailed API list, refer to NvSIPLCameraQuery.hpp and the sample code in the SIPL framework.

Note

Migration from JetPack 7.1: INvSIPLCameraQuery::ParseDatabase() must be called before ParseJsonFile(). In JetPack 7.1 these two calls were mutually exclusive. In JetPack 7.2, ParseDatabase() populates the built-in sensor/module/transport database from /usr/lib/nvsipl_drv/libnvsipl_qry_*.so, and ParseJsonFile() overlays custom IP, MAC, or other configuration on top of that database. Applications that previously called only ParseJsonFile() will fail on JetPack 7.2—update your initialization sequence to call ParseDatabase() first.

GMSL Camera Development#

JSON File Categories#

GMSL configuration is split across four independent JSON file categories. Each file category is loaded from a different search path at runtime. Keeping them separate lets you update platform topology files independently from sensor or module vendor files.

File Category

Example Path

Purpose

Platform transport settings

camera_system_config/transport_settings_<platform>.json

Describes the deserializer, power drivers, CSI port, PHY mode, and I2C bus for each camera port on a specific board.

Sensor system config

camera_system_config/<module>/...

Pairs platform configs with camera module names. Contains cameraConfigs entries that map link indices and sensor IDs to module names.

Camera module config

<sensor_family>/<module>_module.json

Describes one camera module: its serializer name, sensors, and optional EEPROMs with their I2C addresses and image parameters.

Component database

<sensor_family>/<sensor>.json, <module>_serializer.json, etc.

Sensor, serializer, deserializer, and EEPROM component records with I2C addresses, virtual channel parameters, and capability flags.

All four categories contribute to a single logical database. SIPL Query merges them at runtime by name-matching (for example, the "deserializer" field in a platform config must match a "name" in the component database).

Platform Transport Settings#

The platform transport settings file describes the physical camera ports on a specific board. It is loaded from camera_system_config/transport_settings_<platform>.json.

Top-level structure:

{
    "platformTransportSettings": [
        {
            "name": "jetson-thor",
            "description": "Thor - Jetson AGX Devkit (Thor)",
            "boardIdPrefix": "p3960",
            "enableMasks": ["0x1111", "0x1111", "0x1111", "0x1111", "0x1111"],
            "transportSettings": [ ... ]
        }
    ]
}

Each entry in transportSettings describes one deserializer:

{
    "name": "transportSettings_jetson-thor_AB",
    "type": "GMSL",
    "description": "GMSL transport settings for CSI-AB (Thor)",
    "csiPort": "csi-ab",
    "phyMode": "dphy",
    "deserInfo": {
        "name": "Max96724GmslDeserializer",
        "i2cAddress": "0x27"
    },
    "powerControlInfo": {
        "deserializerInfo": {
            "name": "TegraDeserPowerDriver",
            "gpioPinIndex": 7
        },
        "moduleInfo": {
            "name": "MAX20087",
            "i2cAddress": "0x29"
        }
    },
    "i2cDevice": 7,
    "desI2CPort": 0,
    "groupInitProg": true
}

Transport settings fields:

Field

Required

Description

name

Yes

Unique name for this transport entry. Referenced by sensor system config cameraConfigs entries.

type

Yes

Must be "GMSL" for GMSL transports.

csiPort

Yes

CSI port on the SoC. Valid values: "csi-a", "csi-b", "csi-ab", "csi-c", "csi-d", "csi-cd", "csi-e", "csi-f", "csi-ef", "csi-g", "csi-h", "csi-gh".

phyMode

Yes

PHY mode: "dphy" or "cphy".

deserInfo.name

Yes

Must match the DriverInfo.name exported by the deserializer UDDF driver library.

deserInfo.i2cAddress

Yes

I2C address of the deserializer chip (hexadecimal string).

powerControlInfo.deserializerInfo.name

No

Must match the DriverInfo.name of the deserializer power driver.

powerControlInfo.deserializerInfo.gpioPinIndex

No

GPIO pin index for direct GPIO power control. Omit to use I/O expander mode.

powerControlInfo.moduleInfo.name

No

Must match the DriverInfo.name of the module power driver.

powerControlInfo.moduleInfo.i2cAddress

No

I2C address of the module power control device.

i2cDevice

Yes

SoC I2C bus number used to communicate with the deserializer.

desI2CPort

Yes

Deserializer-side I2C port number.

groupInitProg

No

true enables group (broadcast) initialization programming. Defaults to false.

Platform-level fields:

Field

Description

name

Unique platform name. Used to select the correct transport settings at runtime.

boardIdPrefix

Board ID prefix string that SIPL uses to auto-detect the platform.

enableMasks

Array of hex strings, one per transport settings entry, controlling which links are enabled by default (bit 0 = link 0).

Sensor System Config#

Sensor system config files pair a platform topology with a set of camera modules. They are loaded from camera_system_config/<module>/.

A sensor system config file may contain a cameraConfigs array (module-level, used by SIPL directly) or a cameraConfigs array (platform-level, used when multiple deserializers are configured together).

cameraConfigs (module-level)#

Each entry in cameraConfigs describes a single camera module connected to a single deserializer link.

{
    "cameraConfigs": [
        {
            "name": "C2SIM728S3RU3030ND1",
            "type": "GMSL",
            "description": "Conti IMX728 RGGB - 30 FOV Non-heater module",
            "serInfo": {
                "name": "MAX96717F",
                "i2cAddress": "0x40"
            },
            "linkMode": "LINK_MODE_GMSL2_6GBPS",
            "fsyncMode": "external",
            "mipiSettings": {
                "dphyRate": 1300000,
                "phyMode": "dphy"
            },
            "sensorInfo": [{
                "name": "IMX728",
                "description": "Sony IMX728 RGGB Sensor",
                "i2cAddress": "0x1A",
                "numContext": 1,
                "virtualChannels": [
                    {
                        "cfa": "rggb",
                        "embeddedTopLines": 1,
                        "embeddedBottomLines": 20,
                        "inputFormat": "raw12",
                        "width": 3840,
                        "height": 2160,
                        "fps": 30.0,
                        "isEmbeddedDataTypeEnabled": false
                    }
                ]
            }]
        }
    ]
}

Fields:

Field

Required

Description

name

Yes

Unique camera config name. Referenced from application code.

type

Yes

Must be "GMSL" for GMSL cameras.

serInfo.name

Yes

Must match a serializer name in the component database.

serInfo.i2cAddress

Yes

Serializer physical I2C address (hexadecimal string).

linkMode

Yes

GMSL link mode. One of: "LINK_MODE_NONE", "LINK_MODE_GMSL1", "LINK_MODE_GMSL2_6GBPS", "LINK_MODE_GMSL2_3GBPS", "LINK_MODE_GMSL3", "LINK_MODE_GMSL3_GMSL2".

fsyncMode

No

"external" (default) or "osc_manual". On the HAWK AR0234 module "external" is the only supported value as of JP 7.2; JP 7.1 configurations that set "osc_manual" for HAWK AR0234 must be updated to "external". Other GMSL modules (for example, IMX623, IMX728) continue to accept either value.

mipiSettings.dphyRate

Conditional

DPHY rate in kHz. Required when phyMode is "dphy".

mipiSettings.phyMode

No

"dphy" or "cphy". Overrides the transport settings PHY mode for this specific module.

sensorInfo

Yes

Array of sensor info objects (one per sensor on the module). Must match sensor records in the component database by name.

Sensor info fields (within sensorInfo):

Field

Description

name

Sensor name. Must match the "name" in the sensor component database file.

i2cAddress

Physical I2C address of the sensor.

numContext

Number of sensor contexts (exposure groups).

virtualChannels

Array of virtual channel descriptors (see Virtual Channel Fields below).

Virtual Channel Fields#

Field

Description

cfa

Color filter array pattern: "rggb", "rccb", "gbrg", "bggr", "rccc", etc.

inputFormat

Pixel format: "raw8", "raw10", "raw10tp", "raw12", "raw12rj", "raw12tp", "raw16".

width / height

Active pixel resolution.

fps

Frame rate.

embeddedTopLines

Number of embedded data lines at the top of the frame.

embeddedBottomLines

Number of embedded data lines at the bottom of the frame.

isEmbeddedDataTypeEnabled

true if embedded data uses a dedicated CSI data type (DT).

cameraConfigs (platform-level)#

A cameraConfigs array describes an entire multi-deserializer camera topology. Each entry assigns camera modules to deserializer links across one or more deviceBlocks.

{
    "cameraConfigs": [
        {
            "name": "C2SIM623S2RU1195NB20_CPHY_x4",
            "description": "IMX623 RGGB module in 4 lane CPHY mode",
            "enableMasks": ["0x1111", "0x1111", "0x1111", "0x1111"],
            "deviceBlocks": [
                {
                    "passiveMode": false,
                    "csiPort": "csi-ab",
                    "phyMode": "cphy",
                    "homogenousModules": true,
                    "groupInitProg": true,
                    "deserializer": "MAX96712_Fusa_nv",
                    "cameraModules": [
                        {
                            "linkIndex": 0,
                            "simulatorMode": false,
                            "name": "C2SIM623S2RU1195NB20",
                            "serializers": [
                                {
                                    "name": "MAX96717F",
                                    "gpioSerToDes": ["5", "3", "3", "3"]
                                }
                            ],
                            "sensors": [
                                {
                                    "name": "IMX623",
                                    "id": 0,
                                    "isAuthEnabled": false
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Device block fields:

Field

Required

Description

csiPort

Yes

CSI port for this device block (same values as transport settings).

phyMode

Yes

"dphy" or "cphy".

deserializer

Yes

Deserializer name. Must match a "name" in the component database.

homogenousModules

No

true if all camera modules on this deserializer are identical.

groupInitProg

No

true enables group initialization programming.

passiveMode

No

true for passive (pass-through) mode.

cameraModules

Yes

Array of camera module assignments.

Camera module assignment fields:

Field

Description

linkIndex

Zero-based GMSL link index on the deserializer (0–3).

name

Module name. Must match a "name" in the camera module config file.

simulatorMode

true for simulator (TPG) mode without a physical camera.

serializers

Optional array. Overrides the serializer specified in the module config. Each entry may include gpioSerToDes, an array of GPIO forwarding pin IDs.

sensors

Array of sensor assignments. id is the globally unique sensor index (must be unique across all device blocks). isAuthEnabled enables hardware authentication. isTPGEnabled enables the serializer TPG.

Note

Sensor id values must be unique and sequential within a platform config. Even when multiple deserializers are present, no two sensors may share the same id.

Component Database Files#

Component database records define reusable sensors, serializers, deserializers, and modules. In JetPack 7.2, the built-in records are loaded from query libraries in /usr/lib/nvsipl_drv/libnvsipl_qry_*.so. A JSON file passed to ParseJsonFile() overlays custom configuration on top of that database.

Sensor Component File#

{
    "imageSensors": [
        {
            "name": "IMX623",
            "description": "Sony IMX623 Sensor",
            "i2cAddress": "0x1A",
            "virtualChannels": [
                {
                    "cfa": "rggb",
                    "embeddedTopLines": 1,
                    "embeddedBottomLines": 22,
                    "inputFormat": "raw12rj",
                    "width": 1936,
                    "height": 1552,
                    "fps": 30.0,
                    "isEmbeddedDataTypeEnabled": false
                }
            ],
            "isTriggerModeEnabled": true,
            "isTPGEnabled": false,
            "useCDIv2API": true
        }
    ]
}

Sensor fields:

Field

Description

name

Sensor name. Must match the "name" field in camera module and camera system config files.

i2cAddress

Default I2C address. Can be overridden per module.

virtualChannels

Default virtual channel parameters. Can be overridden in platform configs.

isTriggerModeEnabled

true if the sensor supports external trigger mode.

sensorGroup

Sensors with the same non-zero value are grouped into one logical stereo camera.

deviceIndex

Index of the sensor within a multi-sensor module. Use 0 for the primary/left sensor and 1 for the secondary/right sensor in stereo pairs.

isTPGEnabled

true if the sensor supports TPG.

useCDIv2API

true if the sensor driver uses the CDI v2 API.

Serializer Component File#

{
    "serializers": [
        {
            "name": "MAX96717F",
            "description": "Maxim MAX96717F GMSL2 Serializer",
            "i2cAddress": "0x40"
        }
    ]
}

Deserializer Component File#

{
    "deserializers": [
        {
            "name": "MAX96712_Fusa_nv",
            "description": "Maxim MAX96712 GMSL2 Deserializer (NVIDIA FuSa driver)",
            "i2cAddress": "0x29"
        }
    ]
}

The "name" field in the deserializer component file is the identifier used in the "deserializer" field of platform configs. It is distinct from the UDDF driver name in deserInfo.name in the transport settings (which must match the DriverInfo.name exported by the UDDF shared library). The component database name identifies the hardware device; the transport settings name identifies the software driver.

Camera Module Config File#

{
    "cameraModules": [
        {
            "name": "C2SIM623S2RU1195NB20",
            "description": "Sony IMX623 RGGB module - MAX96717F serializer",
            "serializer": {
                "name": "MAX96717F"
            },
            "sensors": [
                {
                    "name": "IMX623",
                    "i2cAddress": "0x1A",
                    "virtualChannels": [
                        {
                            "cfa": "rggb",
                            "inputFormat": "raw12rj",
                            "width": 1920,
                            "height": 1536
                        }
                    ]
                }
            ],
            "eeproms": [
                {
                    "name": "M24C32",
                    "i2cAddress": "0x50"
                }
            ]
        }
    ]
}

Module config fields:

Field

Description

name

Module name. Must match the "name" field in platform configs.

serializer.name

Default serializer for this module. Can be overridden per platform config.

sensors

Array of sensor records. "name" must match a sensor component database entry. Fields here override the component database defaults.

eeproms

Optional array of EEPROM records. Each entry has a "name" (must match an EEPROM component record) and an "i2cAddress".

Name Matching Rules#

The SIPL query subsystem matches entries across files by string comparison. The following table summarizes all name relationships:

JSON field

Must match

transportSettings.deserInfo.name

DriverInfo.name exported by the deserializer UDDF driver library

powerControlInfo.deserializerInfo.name

DriverInfo.name exported by the deserializer power UDDF driver library

powerControlInfo.moduleInfo.name

DriverInfo.name exported by the module power UDDF driver library

cameraConfigs.serInfo.name

"name" in the serializer component database file

cameraConfigs.sensorInfo[].name

"name" in the sensor component database file

cameraConfigs.moduleDriverName

Optional alias to another module driver and NITO. Use this when a platform configuration should reuse an existing module driver without duplicating the driver-side definition.

All comparisons are case-sensitive.

Important

The deserInfo.name in transport settings is the UDDF driver name (which must match DriverInfo.name in the shared library). The deserializer field in deviceBlocks is the hardware component name (which must match the deserializer component database). These are two separate concepts and can differ even when referring to the same chip (for example, when the hardware is "MAX96712_Fusa_nv" and the driver is "Max96712GmslDeserializer").

Best Practices#

  • One responsibility per file: Keep transport settings, platform configs, module configs, and component databases in separate files. This makes it easy to share module configs across different platforms.

  • Sequential sensor IDs: Sensor id values must be unique across the entire platform config, even across different device blocks. Use non-overlapping ranges (for example, 0–3 for the first deserializer, 4–7 for the second).

  • Minimal overrides: Override virtual channel parameters in platform configs only when they differ from the component database defaults, such as for TPG mode.

  • Name consistency: Use a consistent naming convention such as <Vendor><PartNumber><FOV><Options> for module and camera config names to make the database self-documenting.

  • Validation: Use SIPL Query’s startup logs to diagnose name-matching failures. A driver that fails to load produces a log message containing the unresolved name.

Troubleshooting#

Symptom

Likely cause

SIPL fails to find a driver at startup

deserInfo.name or sensorInfo.name does not match the DriverInfo.name exported by the driver library. Check for case differences or typos.

Link does not achieve lock

Mismatch between linkMode in the JSON and the physical cable or serializer speed. Verify that the serializer supports the configured GMSL version and data rate.

Sensor not probed after serdes init

Verify that the sensor I2C address in the module config matches the physical address after virtual address translation. Check that SerInit() correctly programs the address translation table.

Embedded data lines missing

Set isEmbeddedDataTypeEnabled to true and verify embeddedTopLines / embeddedBottomLines match the sensor data sheet.

Wrong image format at ISP output

Verify inputFormat and cfa match the sensor output. raw12rj is right-justified 12-bit packing; raw12 is left-justified.

CoE Camera Development#

This guide explains how to write SIPL Query JSON files for Camera over Ethernet (CoE) camera development on NVIDIA platforms.

It covers the structure, key fields, annotated examples, and best practices for creating valid and effective configuration files.

How to Develop Your Own Query Database JSON File#

To create a custom query database JSON file for your CoE camera system:

  1. Define Camera Configurations

    • Each entry in the cameraConfigs array describes a camera module.

    • Set type to CoE for CoE cameras.

    • Specify a unique name, mac_address, ip_address, hsb_id, and sensorInfo (ID) for each camera.

    Example from vb1940_config.json:

    {
    "cameraConfigs": [
        {
            "name": "VB1940_Camera",
            "type": "CoE",
            "description": "VB1940 Camera 1 Configuration - 2560x1984 30FPS Mode",
            "platform": "Vb1940",
            "platformConfig": "Thor_VB1940",
            "mipiSettings": {
                "lanes": 4,
                "lpBypassMode": false,
                "tClkSettle": 0,
                "mipiClockRate": 570000,
                "tHsSettle": 0,
                "lanePolarity": [0, 0, 0, 0],
                "laneSwizzle": "LANE_SWIZZLE_A0A1B0B1",
                "dphyRate": 1140,
                "cphyRate": 1140,
                "phyMode": "dphy"
            },
            "sensorInfo": {
                "name": "VB1940",
                "id" : 0,
                "description": "VB1940 Eagle Sensor for CoE (Sensor 2)",
                "i2cAddress": "0x10",
                "virtualChannels": [
                    {
                        "cfa": "gbrg",
                        "embeddedTopLines": 1,
                        "embeddedBottomLines": 2,
                        "inputFormat": "raw10tp",
                        "width": 2560,
                        "height": 1984,
                        "fps": 30.0,
                        "isEmbeddedDataTypeEnabled": false
                    }
                ],
                "sensorGroup": 0,
                "deviceIndex": 0
            },
            "isEEPROMSupported": false,
            "sensor": {"name": "VB1940"},
            "cryptoConfigName": "JETSON_AGX_JEDHA_DEVKIT_VB1940",
            "mac_address": "8c:1f:64:6d:70:03",
            "ip_address": "192.168.1.2",
            "hsb_id": 0
        }
    ]
}

    Note

    "id": 0, under sensorInfo, is the sensor index, which should be unique and sequential for each sensor, even when multiple HSBs are connected to the Jetson platform.

    JetPack 7.2 no longer accepts cameraConfigs[].CoECamera.isStereo. Stereo CoE configs use sensorInfo.sensorGroup > 0 together with transportSettings[].sync_sensors. Use the shipped VB1940_Stereo config as the reference stereo layout.

  2. Define Transport Settings

    • Each entry in the transportSettings array describes a transport (network interface).

    • Set type to CoE and specify name, compatible_name, if_name, ip_address, vlan_enable, and hsb_id.

    Example from vb1940_config.json:

    {
    "transportSettings": [
        {
            "name": "VB1940_Camera",
            "compatible_name": "HsbTransport",
            "type": "CoE",
            "description": "Transport settings for VB1940 camera",
            "if_name": "mgbe0_0",
            "ip_address": "192.168.1.2",
            "vlan_enable": false,
            "hsb_id": 0,
            "sync_sensors": false
        }
    ]
}

  3. Validate Your JSON

    • Ensure all required fields are present and correctly formatted.

    • Use SIPL Query’s validation output and logs to catch errors.

  4. Iterate and Test

    • Modify and test your JSON files as you develop your camera solution.

    • Use the SIPL Query API to verify that your cameras and transports are discovered and configured as expected.

    • After testing the JSON file, you can use the unified nvsipl_camera application to test the camera streaming use cases.

Key Fields and Best Practices#

Important Fields for CoE Cameras#

Field

Description

Example

name

Unique identifier for the camera or transport.

“VB1940_Camera”

type

Must be “CoE” for CoE cameras.

“CoE”

mac_address

MAC address of the HSB device (format: XX:XX:XX:XX:XX:XX).

“8c:1f:64:6d:70:03”

ip_address

IP address of the HSB device (dotted decimal).

“192.168.1.2”

hsb_id

HSB identifier for multi-HSB systems.

0

if_name

Network interface name on the host.

“eth0”

vlan_enable

Enable VLAN tagging (true/false).

false

mipiSettings

MIPI interface configuration (such as lanes and clock rate).

{“lanes”: 4, …}

sync_sensors

Enable HSB VSYNC for stereo CoE configurations.

true

Best Practices and Tips#

  • IP Address: Assign a unique static IP address to each HSB device. Avoid conflicts with other devices on the network.

  • MAC Address: Use the correct MAC address for each HSB. This must match the hardware.

  • Device Addressing: If using multiple HSBs, ensure each camera and transport has a unique name and hsb_id.

  • Network Interface: Set if_name to the correct Ethernet interface on your L4T system (such as eth0).

  • VLAN: Enable vlan_enable only if your network requires VLAN tagging.

  • MIPI Settings: Match these settings to your camera hardware’s capabilities and requirements.

  • Stereo CoE: Use the shipped VB1940_Stereo configuration as a template. Assign both sensors the same non-zero sensorGroup, use distinct deviceIndex values, and set sync_sensors to true.

  • Validation: Use SIPL Query’s validation output to catch errors before deployment.

  • Comments: JSON does not support comments. Use descriptive description fields for clarity.

Validation and Troubleshooting#

  • SIPL Query reports errors for missing or invalid fields at runtime.

  • If your configuration fails to load, check logs for detailed error messages.

  • For validation, testing, and querying, refer to the SIPL Query APIs in sipl/include/query/include/NvSIPLCameraQuery.hpp.