Skip to content

Using the GenTL Interface#

This topic tells you how to use the GenTL Producer.

With the GenTL Producer, you can do the following:

  • Configure GenICam compatible cameras of various standards via the same interface (GenApi). Supported standards are Camera Link and CoaXPress.
  • View the hierarchical structure of an image acquisition system.
  • Develop generic applications (GenTL consumers) without considering the camera standard used.

The implemented GenTL producer provides GenTL 1.5.

GenTL Producers#

The Basler Framegrabber SDK contains two GenTL Producers ProducerCXP.cti (for CXP frame grabbers) and ProducerCL.cti (for Camera Link frame grabbers).

GenTL Configuration#

The GenTL Producer saves configuration files for each discovered frame grabber in the following directory:

  • Under Windows: %Appdata%\basler
  • Under Linux: ~/.config/basler

If you delete the *.config files, the GenTL Producer is reset to a default configuration.

Interface Applets#

The interface module XML contains information about the applets in the InterfaceApplets category node. In the InterfaceApplets> InterfaceApplet node, you can select a different applet or .hap file than the currently loaded applet. An applet change is saved in the persistent GenTL configuration file. However, it will only be effective after closing all devices and updating the device list or after closing and reopening the interface. After you have selected an applet and updated the devices, wait some seconds, then check the InterfaceAppletStatus parameter to see whether the applet was loaded.

When Is an Applet Available?

  • On imaWorx and imaFlex frame grabbers, an applet is available as soon as it is available in the file system of your computer (Framegrabber SDK installation directory, sub-directories DLL or Hardware Applets). If the applet isn't there, run the applet installer that contains the applet you want to use, or, if you need an applet created with VisualApplets, copy the applet file (*.hap) into the Hardware Applets folder of your Framegrabber SDK installation (e.g., ...\Basler\FramegrabberSDK5.x.x\Hardware Applets\*.hap).
  • On marathon frame grabbers, an applet is available as soon as it is flashed onto the frame grabber. If the applet you want to use isn't flashed on the frame grabber yet, flash it according to the instructions in the Flashing Applets onto marathon Frame Grabbers topic.

For details on how to manage applets in microDiagnostics, see Managing Applets (microDiagnostics).

Applet Configuration#

In the UserSetControl category in the interface module, you can load and save the configuration file for the currently selected applet. To do this, provide a path to an existing or non-existing *.mcf file in the UserSetFile parameter and execute the UserSetLoad or UserSetSave command. If you leave the path empty or use a different file extension than *.mcf, the commands UserSetLoad and UserSetSave aren't available.

The *.mcf configuration files save the configuration of the applet, while the *.config files save the configure of the GenTL Producer. The configuration loaded from an *.mcf file isn't persisted after an applet change or a system shutdown. If the currently loaded applet doesn't match the applet in the loaded *.mcf file, the GenTL Producer first tries to set the InterfaceApplet to the one in the configuration file. In this case, you must close the devices and update the device list (without closing the system) for the configuration to be effective.

Pseudo Devices#

In the TransportLayerControl category in the interface module, you find the DiscoveryMethod enumeration node. This node contains the CameraDiscovery, EmulationDiscovery, and MixedDiscovery values, where CameraDiscovery is the default value for CXP frame grabbers, and EmulationDiscovery is the default value for Camera Link frame grabbers. The emulated devices are specifically important for Camera Link frame grabbers and for working with **.hap files.

If you select EmulationDiscovery, emulation devices are detected automatically and a basic remote device XML file is generated. If the applet contains an image generator, the image generator is activated by default. You can disable the image generator inside the remote device nodes to receive images from a Camera Link camera. For each acquisition channel, there's an emulation device.

The MixedDiscovery discovers real cameras, but fills the empty acquisition channels with emulated devices. Use this value for .hap files of CXP frame grabbers.

Compatibility Status#

The Compatibility Status category informs about the status of interfaces and devices.

Compatibility Status of Interfaces (e.g., Frame Grabbers)#

  • Interface Driver Version: Displays the version number of the interface's driver.
  • Interface Producer Version: Displays the version number of the current GenTL Producer.
  • Interface PCIe Status:
    • If the actual speed matches or exceeds the required speed, this feature displays the detected PCIe speed, e.g., Gen3x8
    • If the actual speed doesn't match or falls below the required speed, this feature displays the Warning: Gen2x1 detected, but Gen3x8 possible
  • Interface Power Supply Status:
    • Connected: The power connector of the grabber is connected.
    • Warning: PCI-Power connector missing: The power connector of the grabber isn't connected.

In the pylon Viewer, the Compatibility Status for interfaces looks as follows:

pylon Viewer Compatibility Status Interfaces

Compatibility Status of Other Devices (e.g., Cameras)#

  • Device Pixelformat Status:
    • Supported: Pixel format is supported by the camera.
    • Warning: Not supported: Pixel format isn't supported by the camera.
  • Device Automatic ROI Control Status:
    • Deactivated: Automatic ROI was disabled via Device Transport Layer -> Image Format Control.
    • Activated: Automatic ROI is enabled (default).
    • Warning: ROI truncated according to stepping: Feature is activated and the ROI size was adjusted. If the step size of the camera and the applet differ and the requested value can't be set, the ROI size is set to the next lower matching value.
  • Device Tap Geometry Status:
    • Supported: A tap geometry match was found.
    • Warning: Driver does not support tap geometry setting: The driver doesn't support tap geometry.
    • Warning: Requested geometry not supported in applet: The camera requires an unsupported tap geometry. Currently 1X1Y is the default value. Set 1X2YE only if required by the camera and supported by the applet. With 1X_1Y mode, you define that the whole image is transferred as one data stream. This mode is the default mode for most cameras. As sensors grow bigger, a faster readout is needed. To achieve this, use the 1X_2YE mode. In 1X_2YE mode, the sensor is read out in two subframes at once.

In the pylon Viewer, the Compatibility Status for devices looks as follows:

pylon Viewer Compatibility Status Devices

Automatic ROI and FORMAT#

In the ImageFormatControl category, you find the AutomaticFormatControl, AutomaticROIControl, and OutputPacketFormats nodes. If AutomaticFormatControl and AutomaticROIControl are active, the GenTL Producer tries to set the correct format and ROI in the applet to match the camera settings. This is relevant for applets of the microEnable 6 frame gabbers.

Basler's ProducerCL.cti GenTL Producer provides access to camera XML files via Camera Link (CL) connections, using GenCP or CLP (Camera Link Protocol). This is particularly valuable for third-party Camera Link devices connected to a frame grabber, as most GenTL producers don't offer XML access for these setups.

Info

Basler cameras aren't GenCP-compatible but support CLP, allowing direct access to the camera's XML and full configuration through the GenTL Producer. This provides enhanced control and flexibility for Camera Link setups.

Automatic Configuration for Basler CLP#

The ConfigurationForBaslerCLP feature enables automatic XML discovery and optimized configuration for Basler Camera Link cameras when compatible libraries are available. By default, this feature is enabled. When active, it verifies that the Basler-specific CLP library BaslerClProtocol.dll is available. If the GENICAM_CLPROTOCOL environment variable is accessible and the Basler CLP library is detected, the following configurations are applied automatically:

  1. DiscoveryMethod is set to Mixed during interface initialization.
  2. ClpSharedLibraryPath is set to the Basler-specific CLP library path at interface initialization.

This automatic setup simplifies XML access for Camera Link devices when the Basler CLP library is available.

Discovery Modes Overview#

The discovery modes define how cameras or pseudodevices are detected. You can configure the devices via the DiscoveryMethod node in the Interface section of the API:

Mode Description Node Path
Emulation Discovery (Default for CL) Creates pseudodevices (i.e. virtual devices) for each acquisition channel, emulating remote devices. Interface.DiscoveryMethod
Mixed Discovery Searches for real cameras using GenCP or CLP. Falls back to pseudodevices if no real camera is found. Interface.DiscoveryMethod
Camera Discovery (Default for CXP) Searches exclusively for real cameras, without using pseudodevices. Interface.DiscoveryMethod

Protocol Selection: GenCP vs. CLP#

In the following sections you find how to select between the GenCP and CLP discovery modes in hte frame grabber configuration. Whether you set GenCP or CLP depends on your camera.

Configuration for GenCP#

  • GenCP is the default protocol for camera discovery.
  • To enable GenCP, set DiscoveryMethod either to Mixed Discovery or to Camera Discovery in the Interface layer.

Configuration for CLP#

For CLP configuration, follow these steps:

Step Node Path Action
Set Discovery Method Interface.DiscoveryMethod Select Mixed Discovery or Camera Discovery.
Specify CLP Library Path Interface.ClpSharedLibraryPath Define the full path to the CLP shared library (DLL or SO), typically in a folder defined by GENICAM_CLPROTOCOL.
Confirm CLP Library Path Interface.LoadedClpSharedLibraryPath Verify the CLP library has loaded by checking this node.

When ConfigurationForBaslerCLP is enabled and BaslerCLAutoConfig is active, the Basler CLP library path and discovery mode are set automatically, provided that the GENICAM_CLPROTOCOL variable points to the correct location.

Applying and Persisting Changes#

Changes to DiscoveryMethod, GenCP, or CLP settings take effect only after updating the device list.

The configuration is saved in an internal file associated with the frame grabber, ensuring that settings persist across sessions, even after the producer is closed.

Interface Node Access in Some Consumers

In certain applications such as Halcon, the Interface node is available only when at least one device is detected. If DiscoveryMethod is set to Camera Discovery with an incorrect protocol (e.g., CLP instead of GenCP), this may prevent device detection, blocking discovery method changes.

If this occurs, locate the frame grabber configuration file associated with the frame grabber's serial number:

  • On Windows: %AppData%\basler
  • On Linux: ~/.config/basler

Modify the discovery method settings in this file or delete it to reset the configuration.