Using the GenTL Interface

This topic explains how to use the GenTL Producers of the Basler Framegrabber SDK.

A GenTL Producer is a library that implements the GenICam GenTL transport layer interface. A GenTL consumer is any application or library that loads one or more producers through that interface, for example pylon, HALCON, or your own software. The implemented producers provide GenICam GenTL Standard 1.5.

With the GenTL Producers, you can do the following:

• Configure GenICam-compatible Camera Link and CoaXPress cameras through the same interface (GenApi).
• View the hierarchical structure of an image acquisition system.
• Develop generic applications (GenTL consumers) without considering the camera standard that is used.

Opening the GenTL Producer

The directory <Framegrabber SDK installation directory>/bin contains two GenTL Producer files:

Producer	Transport Technology
ProducerCL.cti	Camera Link
ProducerCXP.cti	CoaXPress

A .cti file identifies a GenTL Producer. The extension stands for Common Transport Interface.

Don't open a GenTL Producer directly. Open a GenTL consumer, for example pylon. The consumer loads the GenTL Producer when the GENICAM_GENTL64_PATH or GENICAM_GENTL32_PATH environment variable is set correctly. Each variable contains one or more producer directories. The Framegrabber SDK adds <Framegrabber SDK installation directory>/bin to GENICAM_GENTL64_PATH or GENICAM_GENTL32_PATH. After you install or remove a package, verify that the GENICAM_GENTL64_PATH or GENICAM_GENTL32_PATH environment variable contains only one Basler producer path. For more information about how to set GENICAM_GENTL64_PATH when pylon and the Framegrabber SDK are installed in parallel, see Installing pylon and the Framegrabber SDK in Parallel.

GenTL Configuration File

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

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

The .config file stores the producer settings of that frame grabber, for example the selected applet, the discovery method, and the camera protocol configuration. If you delete the file, the producer resets the configuration of that frame grabber to the default values. Close the consumer before you delete the file, and open the consumer again afterward.

This configuration is persistent, and it belongs to the frame grabber. A setting that you make in one application session is still active in the next session and in a different GenTL consumer. Treat the stored settings as the active profile of the frame grabber. The settings aren't temporary choices of the application that set them. For more information about when changed settings take effect, see Applying and Persisting Changes.

GenTL Module Hierarchy

GenTL presents the acquisition system to the consumer as a hierarchy of modules:

Module	Representation in the Framegrabber SDK
System	The producer itself. This module is the entry point of the hierarchy.
Interface	One frame grabber board.
Device	One camera, or a pseudo device that stands in for an acquisition channel.
Data Stream	One acquisition stream of a device.
Buffer	Memory that is announced for image acquisition.

Consumers can display this hierarchy differently. The GenApi feature names in this topic are the same in every consumer. Most of the configuration in the following sections belongs to the Interface module. It belongs to a frame grabber, not to a camera.

Interface Applets

The Interface module lists the available applets in the InterfaceApplets category. In InterfaceApplets > InterfaceApplet, you can select an applet or .hap file other than the currently loaded one.

The producer saves an applet change in the persistent GenTL configuration file. The change takes effect only after you close all devices and update the device list, or after you close and reopen the Interface. After you select an applet and update the devices, wait a few seconds. Then check InterfaceAppletStatus to see whether the applet was loaded.

The frame grabber type determines which applets are available:

Frame Grabber	An Applet Is Available When…
imaWorx, imaFlex	The applet is present in the file system, in the DLL or Hardware Applets subdirectory of the Framegrabber SDK installation. Run the applet installer that contains the applet, or copy a VisualApplets .hap file into the Hardware Applets folder (for example …\Basler\FramegrabberSDK5.x.x\Hardware Applets).
marathon	The applet is flashed onto the frame grabber. If it isn't flashed yet, flash it first. For more information, see Flashing Applets onto marathon Frame Grabbers.

For more information about managing applets in microDiagnostics, see Managing Applets (microDiagnostics).

Applet Configuration via User Sets

An MCF file stores the applet configuration. MCF stands for microEnable Configuration File. The file extension is .mcf. For more information, see MCF Files.

In the UserSetControl category of the Interface module, you can save and load the configuration of the currently selected applet. To save or load that configuration, enter the path of an existing or new *.mcf file in the UserSetFile parameter. Then execute UserSetSave or UserSetLoad. If the path is empty, or if the file extension isn't .mcf, the two commands aren't available.

Two different configuration files are involved. They have different scopes and lifetimes:

File	Contains	Lifetime
*.mcf	The parameter values of one applet.	The producer loads these values on demand with UserSetLoad. Not persistent: The producer doesn't keep the values after an applet change or after a system shutdown.
*.config	The GenTL Producer configuration of one frame grabber.	Persistent: The producer reloads this file automatically every time it initializes the Interface.

If the currently loaded applet doesn't match the applet that a loaded .mcf file references, the producer first tries to set InterfaceApplet to the applet from the configuration file. Close the devices and update the device list. Don't close the System. The configuration then takes effect.

Device Discovery and Pseudo Devices

The DiscoveryMethod feature (Interface.DiscoveryMethod in Interface > TransportLayerControl) defines which devices the producer creates when the device list is updated.

Discovery Modes Overview

DiscoveryMethod	Devices Exposed	Default for
EmulationDiscovery	One pseudo device for each acquisition channel of the applet. Real cameras aren't searched.	Camera Link
MixedDiscovery	Real cameras are searched. On Camera Link, the search uses GenCP or CLP. Acquisition channels without a discovered camera are filled with pseudo devices.	—
CameraDiscovery	Only real cameras are searched and exposed. No pseudo devices are created.	CoaXPress

Pseudo devices (emulation devices) make the applet and its acquisition channels usable when no camera can be discovered. For each pseudo device, the producer generates a basic remote-device XML file. If the applet contains an image generator, the producer activates the image generator by default. To receive images from a connected Camera Link camera, disable the image generator in the remote device nodes.

Choose the discovery mode according to the intended use:

• EmulationDiscovery: Use this mode when you develop or inspect an applet, when no camera is connected, or when applet parameters and acquisition-channel parameters must remain accessible without camera control. Real-camera discovery is disabled, and the camera protocol configuration isn't used.
• MixedDiscovery: Use this mode when real cameras must be found and empty acquisition channels must remain accessible as pseudo devices. On Camera Link, real cameras are searched through GenCP or CLP. Also use this mode for VisualApplets .hap files, including on CXP frame grabbers. For more information, see Using VisualApplets Applets with GenTL.
• CameraDiscovery: Use this mode when the application must list only real cameras.

For Camera Link, real-camera discovery also requires a camera protocol. For more information, see Accessing Camera Link Cameras.

Compatibility Status

The CompatibilityStatus category reports whether the current combination of frame grabber, applet, and camera works together.

Interface Modules (Frame Grabbers)

Feature	Reported Values
InterfaceDriverVersion	Version number of the driver for this Interface.
InterfaceProducerVersion	Version number of the GenTL Producer.
InterfacePCIeStatus	If the PCIe speed matches or exceeds the required speed, the feature shows the detected PCIe speed (for example Gen3x8). Otherwise, the feature shows a warning such as Warning: Gen2x1 detected, but Gen3x8 possible. A downgraded link limits the available bandwidth.
InterfacePowerSupplyStatus	The feature shows Connected if the power connector of the frame grabber is connected. The feature shows Warning: PCI-Power connector missing if the power connector isn't connected.

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

Device Modules (Cameras)

Feature	Reported Values
DevicePixelformatStatus	The feature shows Supported if the camera supports the configured pixel format. Otherwise, the feature shows Warning: Not supported.
DeviceAutomaticROIControlStatus	The feature shows Activated by default, or Deactivated if Automatic ROI is disabled. In the pylon Viewer, disable Automatic ROI under Device Transport Layer > Image Format Control. The feature shows Warning: ROI truncated according to stepping when the step size of the camera differs from the step size of the applet and the ROI was adjusted to the next lower matching value.
DeviceTapGeometryStatus	The feature shows Supported if a tap geometry match was found. Otherwise, the feature shows Warning: Driver does not support tap geometry setting or Warning: Requested geometry not supported in applet.

Tap geometry describes how the sensor data is transferred. With 1X_1Y, which is the default for most cameras, the whole image is transferred as one data stream. Large, fast sensors may require 1X_2YE. In that mode, the sensor is read out in two subframes at the same time. Set 1X_2YE only if the camera requires it and the applet supports it.

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

Automatic ROI and Format

In the ImageFormatControl category of the Device module, you find the AutomaticFormatControl, AutomaticROIControl, AutomaticTapGeometryControl, and OutputPacketFormats nodes. While AutomaticFormatControl, AutomaticROIControl, and AutomaticTapGeometryControl are active, the GenTL Producer configures the format, ROI, and tap geometry of the applet so that they match the camera settings. and you have to configure the camera and the applet only once. This behavior applies to applets of the microEnable 6 frame grabbers.

Disable these features when the applet must keep its own configuration. This applies in particular to applets that were designed with VisualApplets. For more information, see Using VisualApplets Applets with GenTL.

Accessing Camera Link Cameras

ProducerCL.cti can discover Camera Link cameras and can provide full GenApi access to them, including the camera's XML description file. This access is useful for third-party Camera Link cameras, because most GenTL producers don't provide XML access for these cameras. The following sections describe the two supported camera protocols and how to configure them.

Why Camera Link Needs a Configured Protocol

On Camera Link, you configure the camera protocol. The protocol isn't detected automatically. Camera Link standardizes the image transport and a serial connection. It doesn't standardize how a camera is controlled over that serial line. Each vendor implemented its own command protocol. Automatic detection isn't possible, because there is no standard protocol to try first. Probing with arbitrary protocol variants takes too long, and it can put some camera models into an undefined state.

GenApi needs register-oriented access: read this address, write that address. The camera's XML file describes that access. Two standardized routes connect the serial line with this register model:

Route	How the Gap Is Bridged	Where the Camera-Specific Part Resides
GenCP	The camera itself implements a standardized, packet-based register-access protocol on the serial line.	The camera firmware. No vendor software is required on the host.
CLP (CLProtocol)	A protocol library from the camera vendor translates GenApi register access to the vendor's proprietary serial protocol.	A CLProtocol library (.dll file) that is installed on the host.

The two routes aren't interchangeable. A camera with a vendor CLP library doesn't understand GenCP. A GenCP camera doesn't need a CLP library.

Info

Basler Camera Link cameras aren't GenCP-compatible, but they support CLP. With the Basler CLProtocol library installed, ProducerCL provides direct access to the camera's XML file and to the full camera configuration.

GenCP (Generic Control Protocol) is a GenICam standard for register-based devices. The camera answers standardized read and write commands on the serial line. The commands start at the Camera Link wake-up rate of 9600 baud. The camera exposes its identity through a bootstrap register map, and it provides its GenICam XML file through a manifest in that register space. Everything that is specific to the camera is in the firmware, so a GenCP camera works without vendor-specific software on the host.

CLP (CLProtocol) is the GenICam standard for all other Camera Link cameras. The vendor's CLProtocol library provides a register interface for GenApi and translates that interface to the camera's own serial protocol. For ASCII-based cameras, the library provides a pseudo register space and the matching XML description. CLProtocol libraries are installed for each vendor and registered through the GENICAM_CLPROTOCOL environment variable. Below each registered directory, the library for a 64-bit Windows application is in the Win64_x64 subdirectory. For the Basler library, the file is \Win64_x64\BaslerClProtocol.dll.

Automatic Configuration for Basler CLP

The ConfigurationForBaslerCLP feature provides automatic configuration for Basler Camera Link cameras. The feature is enabled by default. During Interface initialization, the producer checks whether BaslerClProtocol.dll can be found through GENICAM_CLPROTOCOL. If the producer finds the library, it makes the following changes:

1. Sets DiscoveryMethod to MixedDiscovery.
2. Sets ClpSharedLibraryPath to the detected BaslerClProtocol.dll.

The read-only feature BaslerCLPAutoConfigActive indicates that the automatic configuration is in effect. After you update the device list, confirm the loaded library in LoadedClpSharedLibraryPath.

While the automatic configuration is active, it controls DiscoveryMethod and ClpSharedLibraryPath. To set either feature manually, first set ConfigurationForBaslerCLP to false.

Manual Protocol Selection

The protocol that you configure (GenCP or CLP) depends on the camera. Set ConfigurationForBaslerCLP to false before you configure the protocol.

For GenCP (the default protocol for real-camera discovery when no CLP library is configured):

Step	Feature	Value
1	ConfigurationForBaslerCLP	false
2	ClpSharedLibraryPath	Empty
3	DiscoveryMethod	MixedDiscovery or CameraDiscovery

For CLP with a vendor library:

Step	Feature	Value
1	ConfigurationForBaslerCLP	false
2	ClpSharedLibraryPath	Full path to the vendor's CLProtocol library (.dll or .so file), typically in a directory that is registered in GENICAM_CLPROTOCOL
3	DiscoveryMethod	MixedDiscovery or CameraDiscovery

After you update the device list, verify the result in LoadedClpSharedLibraryPath. ClpSharedLibraryPath stores only the requested path. LoadedClpSharedLibraryPath reports the library that was actually loaded.

Camera Link Feature Reference

All features are located in Interface > TransportLayerControl:

Feature	Purpose
ConfigurationForBaslerCLP	Enables the automatic Basler configuration. The feature is enabled by default. Disable it before you configure the protocol manually.
BaslerCLPAutoConfigActive	Read-only. Indicates that the automatic configuration is active and that the Basler CLProtocol library was found.
DiscoveryMethod	Selects real cameras, pseudo devices, or both. For more information, see Device Discovery and Pseudo Devices.
ClpSharedLibraryPath	Requested full path to a CLProtocol library. An empty path selects GenCP for real-camera discovery.
LoadedClpSharedLibraryPath	Read-only. The CLProtocol library that was actually loaded.

The following table shows the typical configurations:

Intended Use	ConfigurationForBaslerCLP	DiscoveryMethod	ClpSharedLibraryPath
Applet or acquisition channels only, no real cameras	false	EmulationDiscovery	Not used
Basler Camera Link camera	true	Controlled automatically (MixedDiscovery)	Controlled automatically (BaslerClProtocol.dll)
GenCP-compatible camera	false	MixedDiscovery or CameraDiscovery	Empty
Camera with a vendor CLP library	false	MixedDiscovery or CameraDiscovery	Full path to the vendor library

How the Serial Connection Is Made

The CLProtocol library doesn't communicate with the frame grabber directly. The library receives a serial interface (ISerial) from the software that loads the library. When the library runs inside ProducerCL, the producer supplies its own internal ISerial implementation. Access to the frame grabber stays inside the producer, and no additional serial components are involved.

Standalone CLProtocol clients, such as pylon, don't run inside GenTL. These clients obtain the serial interface through CLAllSerial. CLAllSerial discovers Camera Link Serial libraries (clser*.dll) in the directory that is registered under the registry value HKEY_LOCAL_MACHINE\SOFTWARE\CameraLink\CLSERIALPATH. Usually, that directory is C:\Program Files\CameraLink\Serial. In that directory, clsersis.dll implements Camera Link Serial for Basler frame grabbers.

Both paths end at the same hardware. A frame grabber can't be initialized through both paths at the same time. This limitation matters mainly when pylon is installed. This topic doesn't describe the use of ProducerCL.cti as a pylon transport layer. For more information, see Installing pylon and the Framegrabber SDK in Parallel.

Applying and Persisting Changes

Changes to DiscoveryMethod, the applet selection, and the GenCP or CLP settings take effect only after you update the device list. In some situations, the changes take effect only after you close and reopen the Interface or restart the consumer. Set the complete configuration before you apply it. After you apply the configuration, evaluate the result.

The configuration is saved for each frame grabber and remains in effect across sessions, even after the producer is closed. For more information, see GenTL Configuration. Remember the following points when the intended use changes:

• A persisted EmulationDiscovery setting prevents real-camera discovery. This is intentional.
• A persisted CameraDiscovery setting creates no pseudo device when the selected protocol can't identify the camera.
• A persisted CLP path continues to select that vendor library after the camera is replaced.
• When the Basler automatic configuration is enabled, it restores MixedDiscovery and the Basler CLP path every time the Interface is initialized.

Interface Node Access in Some Consumers

In some consumers, such as HALCON, the Interface node map is available only when at least one device is detected. If DiscoveryMethod is set to CameraDiscovery and the protocol doesn't match the camera, the producer creates no device. You then can't reach the discovery settings in that consumer. Locate the configuration file that is associated with the serial number of the frame grabber. On Windows, the file is under %AppData%\basler. On Linux, the file is under ~/.config/basler. Change the discovery settings in that file, or delete the file to reset the configuration. For an applet-only setup, use EmulationDiscovery to avoid this situation. That mode always creates pseudo devices.

Using VisualApplets Applets with GenTL

Design Considerations

Applet file name: The file name of the applet is used directly as the Name attribute of the corresponding entry in the InterfaceApplets enumeration. The file name must therefore conform to the GenICam naming requirements. GenICam standard version 2.1.1 specifies the following requirements:

Each node has a Name attribute. The Name must be unique within the camera description
file. Names can be composed of alphanumeric characters [A-Za-z0-9]. The schema also
allows the use of the underscore '_', but not as a leading character.

Operator and hierarchy names: The parameter names of the applet are formed from the operator hierarchy of the VisualApplets design. The producer changes these names so that they conform to the GenICam requirements. If you name operator instances and hierarchical elements according to the GenApi rules from the start, the resulting node names are easier to understand.

Runtime Configuration

When you use an applet that was designed with VisualApplets, the usual camera discovery isn't sufficient. The producer also doesn't synchronize camera parameters to the applet automatically. Make the following settings:

1. Set DiscoveryMethod to MixedDiscovery before you enumerate the devices. This setting enables all DmaToPc module.
2. After you open a device, set AutomaticFormatControl, AutomaticROIControl, and AutomaticTapGeometryControl in the device XML to false.

Troubleshooting

Observed Behavior	Interpretation and Action
DiscoveryMethod or ClpSharedLibraryPath can't be edited for a Camera Link Interface.	The automatic Basler configuration is active. Set ConfigurationForBaslerCLP to false first.
Only pseudo devices are listed for a Camera Link Interface.	EmulationDiscovery is active, or MixedDiscovery didn't find a real camera and filled the channel with a pseudo device. Check the protocol configuration.
A Basler Camera Link camera isn't discovered.	Keep ConfigurationForBaslerCLP enabled. Make sure that GENICAM_CLPROTOCOL points to the Basler CLProtocol installation. Update the device list, and confirm BaslerClProtocol.dll in LoadedClpSharedLibraryPath.
A GenCP-compatible camera isn't discovered after CLP was configured.	Set ConfigurationForBaslerCLP to false, clear ClpSharedLibraryPath, select MixedDiscovery or CameraDiscovery, and update the device list.
A camera with a vendor CLP library isn't discovered.	Set ConfigurationForBaslerCLP to false. Enter the full library path in ClpSharedLibraryPath, update the device list, and verify LoadedClpSharedLibraryPath.
A pseudo device delivers test images instead of camera images.	The image generator of the applet is active. Disable the image generator in the remote device nodes of the pseudo device.
Interface or frame grabber initialization reports that the resource is in use.	Another process already holds the frame grabber. Each frame grabber can be initialized by only one process at a time. For
Camera Link, this includes standalone CLProtocol clients such as pylon that use clsersis.dll. For more information, see Installing pylon and the Framegrabber SDK in Parallel.
The producer reports at initialization that another Framegrabber SDK version is already active.	The producer loaded protected Framegrabber SDK modules such as fglib5.dll from another installation. For more information, see Installing pylon and the Framegrabber SDK in Parallel.
You can't reach the Interface settings in the consumer after a discovery change.	No device was created, and the consumer shows the Interface node map only when at least one device exists. Reset or edit the .config file of the frame grabber. For more information, see Applying and Persisting Changes.

References

• Installing pylon and the Framegrabber SDK in Parallel
• clsersis
• GenICam GenTL Standard 1.5 - EMVA