Setting Up The Framework For Third Party GenTL Producer Usage

Introduction

Since Impact Acquire 2.32.0 the Impact Acquire SDK is a full-featured GenICam™ GenTL Consumer that is capable of connecting with third party driver stacks that are GenTL compliant.

Note

Everything described here is currently experimental and might change in a future version!

Right now third party GenTL producers will be located and loaded when they comply with the GenTL standard. This in particular requires any GenTL producer to be located in a path defined by the environment variables GENICAM_GENTL32_PATH (for 32-bit producers) or GENICAM_GENTL64_PATH (for 64-bit producers) They will be fully operational for a certain evaluation period (a defined number of images per session). If you are interested in certain combination of drivers and devices currently not supported please get in contact with suppo.nosp@m.rt.d.nosp@m.e@bal.nosp@m.luff.nosp@m..de

By default all technologies not supported a Balluff GenTL producer will be setup for device enumeration, all others will not but can be enabled if wanted.

ImpactControlCenter - GenTL producer enumeration default behaviour

Which drivers and even which interfaces reported by a certain driver shall be used for device enumeration however can be changed at any time either by

• using the tool ImpactControlCenter and there by navigating into the Info dialog
• The classes mvIMPACT::acquire::GenICam::GenTLDriverConfigurator and mvIMPACT::acquire::GenICam::GenTLProducerConfiguration can be used to set up the driver stacks behaviour regarding third party GenTL driver packages.

There are 2 ways to set up the driver stack for using or ignoring certain third party GenTL producers and interfaces: ImpactControlCenter or by using the API.

Using ImpactControlCenter

The method requires a producer to

• export a GenICam™ XML file from its SystemModule and InterfaceModule
• support the following feature within the system module's XML file:
  • TLFileName or TLPath
  • InterfaceSelector
  • InterfaceType
• support the following feature within the interface module's XML file:
  • InterfaceType
• support the following feature within either the system or the interface module's XML file:
  • InterfaceID

For all GenTL producers this is the case The Info dialog of ImpactControlCenter will display a convenient interface to configure all the interfaces of the GenTL producers detected in the system:

ImpactControlCenter - Info Dialog

Simply checking and unchecking the corresponding check-boxes and leaving the dialog with OK will result in the required entries being created and the next time an Impact Acquire process will be started after leaving ImpactControlCenter will then use these new settings. Unfortunately the quality of GenTL producers out there varies quite a lot and not all producers fully comply with the standard (https://www.emva.org/standards-technology/genicam/). So sometimes it will be a little more complicated even though ImpactControlCenter can still be used.

To configure a certain GenTL producer using the API the exact name (without the path) and the exact ID of the interface (as reported by the interface selector of the producer) must be passed to the mvIMPACT::acquire::GenICam::GenTLDriverConfigurator::createProducerConfiguration

function as seen below:

ImpactControlCenter - Manual creation of a GenTL producer interface configuration entry

So doing this for a real world scenario might look like this:

ImpactControlCenter - Manual creation of a GenTL producer interface configuration entry

Now this particular interface can be configured for enumeration, which then after the next update of the device list results in devices connected to that interface being listed and becoming usable as well:

ImpactControlCenter - Manual creation of a GenTL producer interface configuration entry after updating the device list

Using The API

The classes needed for setting up the behaviour are

• mvIMPACT::acquire::GenICam::GenTLDriverConfigurator
• mvIMPACT::acquire::GenICam::GenTLProducerConfiguration

How The Configuration Data Is Stored

The current configuration will remain on the system upon process exit by storing a file called GenTLProducerConfigurationData.xml in $(MVIMPACT_ACQUIRE_DATA_DIR) from within the mvGenTLConsumer library when the driver shuts down/the process terminates and an application made changes to the current configuration either by using ImpactControlCenter or the SDK directly.

When starting a new Impact Acquire process the mvGenTLConsumer library will look for this file again to retrieve the current driver setup. The file (if found) then will be used to create the lists and properties defining the behaviour of the GenTL driver stack. Using the API mentioned above an application effectively modifies the content of this file so manually editing this file is also possible even so not recommended. The file content is similar to a standard Impact Acquire setting file in XML format. It will roughly look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PropList name="ConfigurationData" default="0" position="1" flags="3" size="1" parent="none" versionMajor="2" versionMinor="34" versionRelease="0">
  <DocString value="For all GenTL third party producers detected on this system this list contains features to configure things like enumeration behaviour(e.g. shall a producer be enumerated or not) to e.g. allow to exclude a faulty producer from enumeration. Features configured here will be stored automatically on the system so will be applied automatically during the next session."></DocString>
  <PropList name="ACME.cti" default="0" position="0" flags="3" size="2" parent="none"> <!-- The 'name' of the producer to configure! The 'position' attribute defines the relative position within the parent list. Use unique values only!, always keep all other attributes as defined here! -->
    <Property name="EnumerationEnable" default="0" position="0" flags="263" size="1" formatString="%d" valType="1"> <!-- The 'position' attribute defines the relative position within the parent list! Use unique values only! The 'default' attribute states if this property should be treated as being set to it's default value always keep all other attributes as defined here! -->
      <!-- Keep all 'TranslationDictEntry' tags as stated here! -->
      <TranslationDictEntry key="Off" value="0"></TranslationDictEntry>
      <TranslationDictEntry key="On" value="1"></TranslationDictEntry>
      <ConstantsDictEntry key="-4" value="0"></ConstantsDictEntry> <!-- The 'value' attribute defines the default value for this property(here: 'Off'), can be changed if needed. If this default value and the following 'Value' node' don't match adjust 'default' attribute of the 'Property' node -->
      <Value index="0" val="On"></Value>
      <DocString value="When switched off all interfaces reported by this producer (except the ones set to 'ForceEnumerate') will be ignored"></DocString>
    </Property>
    <PropList name="Interfaces" default="0" position="1" flags="3" size="1" parent="none">
      <DocString value="Contains an entry per interface to define the enumeration behavior of this particular interface"></DocString>
      <Property name="ACME.interface0.ID" default="1" position="0" flags="263" size="1" formatString="%d" valType="1"> <!-- The ID of the interface to configure. The 'position' attribute defines the relative position within the parent list! Use unique values only! The 'default' attribute states if this property should be treated as being set to it's default value always keep all other attributes as defined here! -->
        <!-- Keep all 'TranslationDictEntry' tags as stated here! -->
        <TranslationDictEntry key="NotConfigured" value="0"></TranslationDictEntry>
        <TranslationDictEntry key="ForceIgnore" value="1"></TranslationDictEntry>
        <TranslationDictEntry key="ForceEnumerate" value="2"></TranslationDictEntry>
        <ConstantsDictEntry key="-4" value="1"></ConstantsDictEntry> <!-- The 'value' attribute defines the default value for this property(here: 'ForceIgnore'), can be changed if needed. If this default value and the following 'Value' node' don't match adjust 'default' attribute of the 'Property' node -->
        <Value index="0" val="ForceIgnore"></Value>
        <!-- You could add a custom documentation using the next line -->
        <DocString value="When set to 'ForceIgnore' this interface will not enumerate device, when set to 'NotConfigured' this interface will enumerate devices when the producers 'EnumerationEnable' property is set to 'True' and when set to 'ForceEnumerate' this interface will enumerate devices even when the producers 'EnumerationEnable' property is set to 'False'"></DocString>
      </Property>
      <!-- Add more interface configurations for this producer here -->
    </PropList>
  </PropList>
  <!-- Add more producer configurations here -->
</PropList>

As already mentioned earlier: Manually editing this file should be a last straw! Use the API whenever possible! The only reason to manually access and modify this file is when the presence of a third party producer on the system results in an immediate crash of the complete Impact Acquire driver stack just because it is being enumerated.

Troubleshooting

• The Presence Of A 3rd Party GenTL Producer Results In Impact Acquire To Crash