The Extra Configuration File

This section details how to use an extra configuration file to customize your installation packages, processes, and hardware with NVIDIA SDK Manager. This can be used to support the installation of a third-party carrier board, customized packages, and so on.

Introduction

The extra configuration file enables you to add and/or modify some behavior of SDK releases with NVIDIA SDK Manager in a way that will overwrite the original release manifest.

There are two pillars that can be handled with this manifest file:

  • Software - modify install steps and binaries.

  • Hardware - overwrite with the new hardware information.

Background

SDK Manager uses data (hardware and software information) that is dynamically obtained for each SDK release, such as JetPack 5.x.

The data is stored in JSON manifest files that are loaded as needed during the install session. When supplying an extra config file, it will overwrite the original values (stored in the JSON manifest files) per selected object, or add new objects to the install session.

To modify objects to create your own extra config file, you will need to allocate the objects that need modifications from the original release manifest. The easiest way to do it is by inquiring about the original release manifest file(s) along with the provided example file.

Usage of the Extra Configuration File

The end-user/developer will configure their development environment with the extra configuration file provided by you. They will then use NVIDIA SDK Manager with the following command:

sdkmanager --extraconfig [local path to the extra config file]

This can be used along with other command line arguments as needed. See the Command Line Install section for a full list of supported arguments.

Create the Extra Configuration File

Obtain Reference Data

To begin, get the software and hardware JSON manifest files that includes the hardware and software components for the SDK release you want to customize:

  1. Download the Software JSON manifest file using one of the below methods:

    • Using the SDK Manager GUI: run the NVIDIA SDK Manager GUI, select the SDK you would like to customize, then go to STEP 2 to review the list of components. When finished, exit SDK Manager.

    • Using the SDK Manager command-line interface: run the NVIDIA SDK Manager CLI with the specific parameters needed. For example:

      # sdkmanager --cli install  --logintype devzone --product Jetson --host --targetos Linux --version 5.1.1 --target JETSON_AGX_ORIN_TARGETS --flash all
      

      Review the list of components in the main window. When finished, exit SDK Manager.

  2. Obtain the software reference file (sdkml3_<release>.json) from the ~/.nvsdkm/dist/ directory.

  3. Obtain the hardware reference file from the ~/.nvsdkm/hwdata/ directory.

Note

The hardware you choose to overwrite must be a single device. Do NOT use “family” files that end with TARGETS.json or DEVKITS.json.

This single device is referenced in its devices “family” file. The “family” ID is referred to in the software components section (usually sharing the same prefix name).

For example: JETSON_AGX_ORIN_TARGETS.json “family” file refers to JETSON_AGX_ORIN_32GB. The device’s “family” ID is referenced in the targetIdsarray in the software reference file (sdkml3_<release>.json).

Use the ~/.nvsdkm/hwdata/HWDevices/Jetson/JETSON_AGX_ORIN_32GB.json (and NOT JETSON_AGX_ORIN_TARGETS.json).

It is recommended that you choose the nearest module of the device hardware you are customizing.

Setup the Extra Configuration File

Get the Example Configuration File

Download the example configuration file (extraconfig file) from:

Create Your Own Configuration File

Use the example file to create your own configuration file by following, changing, or adding objects as described below.

information Section

This section is used to set up the required SDK release version that you want to customize.

  • From the Software reference file, copy the below keys (and values) to your extra configuration file.

    information.release.releaseVersion
    
    information.release.releaseEdition
    
    information.release.releaseRevision
    

Note

Empty values can be used and are not limited to a specific SDK release.

sw Section

This section is used to overwrite specific component installation with your customized software and installation steps.

  • From the Software reference file, copy a complete sw component object to your extra configuration file.

    The components are located in the components object in the software reference file and should be copied into the sw object at the extra configuration file. For example:

    • components.NV_L4T_FILE_SYSTEM_AND_OS_COMP (used for BSP)

    • components.NV_L4T_FLASH_JETSON_LINUX_COMP (used for the flash command)

  • Modify the copied objects to meet your needs.

    Note that scripts and commands that are executed must follow the below rules:

  • To automatically be ended and exited back to the terminal.

  • Errors need to be output into stderr.

  • Blocking errors must exit with a none 0 exit value.

  • Not contain any user input (run completely in an unattended mode).

hw Section

This section is used to overwrite specific hardware device parameters with your customized hardware device.

  • From the Hardware reference file, copy a complete hw component object to your extra configuration file.

    The hardware device is located in the hw object in the hardware reference file and should be copied into the hw object at the extra configuration file.

    For example:

    • hw.JETSON_AGX_ORIN_32GB (used for Jetson AGX Orin 32GB device)

  • Modify the copied objects to meet your needs.

Carefully review the note section in the Hardware reference file instructions above, and verify that the “family” device is referred to in the software component object you are modifying.

For example: sw.NV_L4T_FILE_SYSTEM_AND_OS_COMP.platforms.targetIds includes "JETSON_AGX_ORIN_TARGETS".

Schema Objects

The information, hw and sw objects support multiple key-value paired objects in it. These values are managed by SDK Manager Schema versions. Each SDK release schema is defined in the information.schemaVersionobject in the Software reference file(sdkml3_<release>.json). It is recommended that you use the latest SDK Manager version.

Review information related to:

Descriptions and Samples for JSON Elements: Schema Version 17

  • information - (object) contains information needed to support a specific SDK.

    • release - (object) contains release information needed to support a specific SDK.

  • releaseVersion - (string) the release version supported for this SDK.

  • releaseEdition - (string) the release edition supported for this SDK.

  • releaseRevision - (number) the release revision supported for this SDK.

  • sw - (object) contains needed components’ information to change the components’ installation, and support multiple components.

key - (string) special key used in the client to identify the component. This key must already exist in sdkml3_<release>.json.

This will override the original native component in SDK Manager’s l3 json with that key.

  • id - unique ID for the component. In general, this is the same as the key.

    • name - (string) the official name of the component, which will be shown in the SDK Manager GUI.

    • isVisible - (boolean) expose the component in the SDK Manager GUI.

    • estimateInstallDurationSeconds - (number) the estimated install duration in seconds.

    • platforms- (array of objects) components can have different platforms to support different install files per targetIds and operatingSystems.

      • operatingSystems - (array of strings) the operating systems supported for this version.

      • targetIds - (array of strings) target series IDs of the target devices; available target series IDs can be found in ~/.nvsdkm/hwdata/HWDevices/ (see the Hardware reference file) ending with TARGETS.json or DEVKITS.json. For example:

        JETSON_AGX_ORIN_TARGETS
        
    • prerequisites - (array of strings) The prerequisites string checks for the components, if needed. Available prerequisites in SDK Manager include:

      PREREQUISITE_APT_HOST, PREREQUISITE_DISK_SPACE_TARGET,
      
      PREREQUISITE_NETWORK_TARGET, PREREQUISITE_APT_TARGET
      
    • installSizeMB - (number) the size in MB of the component after installed.

    • downloadFiles - (array of objects) This element contains information of the download files and installation methods.

      • url - (string) the URL of the download file.

      • fileName - (string) the file name of the download file.

      • size - (string) size of the download file in bytes.

      • checksum - (string) checksum of the download file.

      • checksumType - (string) the download file checksum type, Set to md5.

      • verifyChecksum - (string) yes / no to identify whether SDK Manager should verify the checksum.

      • packageInstallParameters - (object) the install parameters for the download file.

      • additionalParameters - (object) additional parameters for the download file.

      • installDir - (string) path where the installation will be executed.

      • installCommands - (array of objects) commands to run for the download file installation process. Some of the installation types can be automatically handled by SDK Manager, while others cannot.

      • installEngineQueue - (string) defines how the engine will queue the file in installation order. Available options are:

        default, parallel, sequential
        
    • installType - (string) installation type of the download file. Available options are:

      skip, archive, zip, tgz, deb, deb_repo, run, run_root, cmd, target_deb_repo, target_deb, rpm
      
    • componentInstallParameters- (object) the install parameters for the component.

      • installDir - (string) path of where the installation will be executed.

      • installCommands - (array of objects) commands to run for the download file installation process. Some of the install types can be automatically handled by SDK Manager, while others cannot.

      • installEngineQueue - (string) defines how the engine will queue the file in installation order. Available options are:

        default, parallel, sequential
        
      • preInstallCommands - (array of objects) commands to run before the component installation process.

      • postInstallCommands - (array of objects) commands to run after the component installation process.

      • installCommands - (array of objects) commands to run for the component installation process.

      • dependencies - (array of objects) the components or groups this component should be dependent on for the installation queue.

      • type - (string) type of the dependency. Available options are:

        optional, required
        
      • id - (string) ID of the dependency component or group.

      • version - (string) the component exact version.

      • licenseId - (string) the ID of the license for this component in SDK Manager.

      • isDetectableInstall - (boolean) Set whether the component installation status is detectable or not. Typically, the installation type with deb, deb_repo, target_deb_repo, target_deb, and rpm should be set to true. Others should be set to false.

      • isPartiallyDetectableInstall - (boolean) Set whether the component installation status is detectable. Should be set to true when a component has both detectable methods and undetectable methods in it.

      • hw - (object) contains needed board information in order to identify a target device, and can only support a single target device.

    • key - (string) special key used on the client to identify the target board. See the notes in the Hardware reference file on how to identify the hardware device ID.

    • name - (string) the official name of the target board, which is shown in the SDK Manager GUI.

    • moduleNames - (array of strings) module/modules name supported on this target device. This is displayed in the SDK Manager GUI.

    • hwDevices - (array of strings) used when there are multiple target devices in the devices group, not related to the extra configuration, should be kept empty as [].

    • products - (array of strings) product names of the target devices. Supported products are: Jetson, Holoscan, DRIVE, DOCA, Switch.

    • targetIds - (array of strings) target IDs of the target devices, usually uses the P + module ids for it.

    • moduleIds - (array of strings) module IDs of the target devices. This is used in SDK Manager for board detection and flash identification.

    • carrierIds - (array of strings) carrier IDs of the target devices. This is used in SDK Manager for board detection and flash identification.

    • moduleDescription - (string) Description for the module of the target board.

    • carrierDescription - (string) Description for the carrier of the target board.

    • recoveryModeCodes - (array of strings) recovery mode code of the device in lsusb. This is used in SDK Manager for board detection and flash identification.

    • aurixPort - (string) ttyUSB port used for DRIVE devices.

    • deviceInstructions - (object) instructions to flash a board.

      • linux - (array of strings) used on DRIVE devices. Contains the DRIVE OS Linux flashing instructions.

      • qnx - (array of strings) used on DRIVE devices. Contains the DRIVE OS QNX flashing instructions.

      • flash - (array of strings) contains the general flashing instructions.

      • recoveryAuto - (array of strings) used on Jetson, Holoscan and Switch devices. Contains the auto flashing instructions.

      • recoveryManual - (array of strings) used on Jetson, Holoscan and Switch devices. Contains the manual flashing instructions.

    • hwImagePath - (string) the path of hardware images, can be a URL starting with http://, https://, file:// or a local directory absolute path that starts with /.

    • storages - (array of objects) used to define what kind of storages for device to flash on if there are multiple options.

      • id - (string) id of the storage type.

      • displayName - (string) display name of the storage type to show on the client.

      • flashOptions - (string) the additional options command to used for the storage.

Descriptions and Samples for JSON Elements: Schema Version 13

  • information - (object) contains information needed to support a specific SDK.

    • release - (object) contains release information needed to support a specific SDK.

      • releaseVersion - (string) the release version supported for this SDK.

      • releaseEdition - (string) the release edition supported for this SDK.

      • releaseRevision - (number) the release revision supported for this SDK.

        • sw - (object) contains needed components’ information to change the components’ installation, and support multiple components.

          key - (string) special key used in the client to identify the component. This key must already exist in sdkml3_<release>.json.

          This will override the original native component in SDK Manager’s l3 json with that key.

  • id - unique ID for the component. In general, this is the same as the key.

  • name - (string) the official name of the component, which will be shown in the SDK Manager GUI.

  • isVisible - (boolean) expose the component in the SDK Manager GUI.

  • estimateInstallDurationSeconds - (number) the estimated install duration in seconds.

  • versions - (array of objects)components can have different versions to upport different install files per targetIds and operatingSystems.

    • operatingSystems - (array of strings) the operating systems supported for this version.

    • installSizeMB - (number) the size in MB of the component after installation is complete.

    • targetIds - (array of strings) target series IDs of the target devices; available target series IDs can be found in ~/.nvsdkm/hwdata/HWDevices/ (see the Hardware reference file) ending with TARGETS.json or DEVKITS.json. For example:

      JETSON_AGX_XAVIER_TARGETS
      
  • prerequisites - (array of strings) The prerequisites string checks for the components, if needed. Available prerequisites in SDK Manager include:

    PREREQUISITE_APT_HOST, PREREQUISITE_DISK_SPACE_TARGET,
    
    PREREQUISITE_NETWORK_TARGET, PREREQUISITE_APT_TARGET
    
  • downloadFiles - (array of objects) This element contains information of the download files and installation methods.

    • url - (string) the URL of the download file.

    • fileName - (string) the file name of the download file.

    • size - (string) size of the download file in bytes.

    • checksum - (string) checksum of the download file.

    • checksumType - (string) the download file checksum type, Set to md5.

    • verifyChecksum - (string) yes / no to identify whether SDK Manager should verify the checksum.

    • installParameters - (object) the install parameters for the download file.

      • additionalParameters - (object) additional parameters for the download file.

      • installDir - (string) path where the installation will be executed.

      • installCommands - (array of objects) commands to run for the download file installation process. Some of the installation types can be automatically handled by SDK Manager, while others cannot.

      • installEngineQueue - (string) defines how the engine will queue the file in installation order. Available options are:

        default, parallel, sequential
        
  • installType - (string) installation type of the download file. Available options are:

    skip, archive, zip, tgz, deb, deb_repo, run, run_root, cmd, target_deb_repo, target_deb, rpm
    
  • installParameters - (object) the install parameters for the component.

    • installDir - (string) path of where the installation will be executed.

    • installCommands - (array of objects) commands to run for the download file installation process. Some of the install types can be automatically handled by SDK Manager, while others cannot.

    • installEngineQueue - (string) defines how the engine will queue the file in installation order. Available options are:

      default, parallel, sequential
      
  • preInstallCommands - (array of objects) commands to run before the component installation process.

  • postInstallCommands - (array of objects) commands to run after the component installation process.

  • installCommands - (array of objects) commands to run for the component installation process.

  • version - (string) the component exact version.

  • dependencies - (array of objects) the components or groups this component should be dependent on for the installation queue.

  • type - (string) type of the dependency. Available options are:

    optional, required
    
  • id - (string) ID of the dependency component or group.

  • ver - (string) version of the dependency component or group.

  • operator - (string) == or > or < or <= or >= for upper version.

    • licenseId - (string) the ID of the license for this component in SDK Manager.

    • isDetectableInstall - (boolean) Set whether the component installation status is detectable or not. Typically, the installation type with deb, deb_repo, target_deb_repo, target_deb, and rpm should be set to true. Others should be set to false.

    • isPartiallyDetectableInstall - (boolean) Set whether the component installation status is detectable. Should be set to true when a component has both detectable methods and undetectable methods in it.

    • hw - (object) contains needed board information in order to identify a target device, and can only support a single target device.

  • key - (string) special key used on the client to identify the target board. See the notes in the Hardware reference file on how to identify the hardware device ID.

  • name - (string) the official name of the target board, which is shown in the SDK Manager GUI.

  • moduleNames - (array of strings) module/modules name supported on this target device. This is displayed in the SDK Manager GUI.

  • hwDevices - (array of strings) used when there are multiple target devices in the devices group, not related to the extra configuration, should be kept empty as [].

  • products - (array of strings) product names of the target devices. Supported products are: Jetson, Holoscan, DRIVE, DOCA, Switch.

  • targetIds - (array of strings) target IDs of the target devices, usually uses the P + module ids for it.

  • moduleIds - (array of strings) module IDs of the target devices. This is used in SDK Manager for board detection and flash identification.

  • carrierIds - (array of strings) carrier IDs of the target devices. This is used in SDK Manager for board detection and flash identification.

  • moduleDescription - (string) Description for the module of the target board.

  • carrierDescription - (string) Description for the carrier of the target board.

  • recoveryModeCodes - (array of strings) recovery mode code of the device in lsusb. This is used in SDK Manager for board detection and flash identification.

  • aurixPort - (string) ttyUSB port used for DRIVE devices.

  • deviceInstructions - (object) instructions to flash a board.

    • linux - (array of strings) used on DRIVE devices. Contains the DRIVE OS Linux flashing instructions.

    • qnx - (array of strings) used on DRIVE devices. Contains the DRIVE OS QNX flashing instructions.

    • recoveryManual - (array of strings) used on Jetson, Holoscan and Switch devices. Contains the manual flashing instructions.

  • hwImagePath - (string) the path of hardware images, can be a URL starting with http://, https://, file:// or a local directory absolute path that starts with /.