SIPL Query JSON Guide for 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.

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.

For more details on the SIPL framework, refer to Introduction to SIPL.

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/query/include/NvSIPLCameraQuery.hpp.

Key API Calls

SIPL Query Interface API Calls#
API Function	Description
`ParseDatabase()`	Loads and parses the default query database (JSON files).
`ParseJsonFile(std::string fileName)`	Loads and parses a user-specified JSON file.
`GetDeviceInfoList()`	Returns a list of available camera devices and transports.
`GetCameraConfigNames()`	Retrieves the configuration for a named camera.

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

How to Develop Your Own Query Database JSON File#

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

Start from an Example
- Use the provided example files in sipl/query/database/coe/ (such as vb1940_config.json) as templates.
- Alternatively, refer to the examples later in this topic.

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"
            },
            "CoECamera": {
                "isStereo": false,
                "hsbSensorIndex": 0,
                "hsb_id": 0,
                "sensor": {
                  "mac_address": "8c:1f:64:6d:70:03",
                  "ip_address": "192.168.1.2"
                }
            },
            "sensorInfo": {
                "name": "VB1940",
                "id" : 0,
                "description": "VB1940 Eagle Sensor for CoE (Sensor 2)",
                "i2cAddress": "0x10",
                "virtualChannels": [
                    {
                        "cfa": "gbrg",
                        "embeddedTopLines": 1,
                        "embeddedBottomLines": 2,
                        "inputFormat": "raw10packed",
                        "width": 2560,
                        "height": 1984,
                        "fps": 30.0,
                        "isEmbeddedDataTypeEnabled": false
                    }
                ]
            },
            "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.

hsbSensorIndex must be either 0 or 1.

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
        }
    ]
}

Validate Your JSON
- Ensure all required fields are present and correctly formatted.
- Use SIPL Query’s validation output and logs to catch errors.
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 nvsipl-coe camera app 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, …}

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.
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.
Use the provided example JSON files in sipl/query/database/coe/ or the preceding examples as templates.
For validation, testing, and querying, refer to the SIPL Query APIs in sipl/query/include/NvSIPLCameraQuery.hpp.