Establishing a Camera Bridge with GenICam CLProtocol using a CLProtocol DLL

Important: This article pertains to eBUS SDK 5.0 (and later), which provides a simplified user interface for configuring, controlling, and monitoring Camera Link cameras.

Some camera manufacturers provide you with a CLProtocol DLL to configure and monitor the camera using GenICam.
Pleora’s eBUS SDK allows you to establish a camera bridge between the Pleora video interface and the camera, using a network or USB 3.0 connection. When the bridge is established, the CLProtocol DLL is used to interface between the camera’s GenICam node map and the eBUS Player (the sample viewing and configuration application that is included with the eBUS SDK).
Note: While the camera bridge is only available for the Windows operating system, the eBUS SDK provides classes for all supported operating systems, which allows the functionality to be replicated in any non-Windows operating system.
 
This article describes the two ways in which you can configure the camera bridge for each of the video interface’s serial ports:

• Using eBUS Player (the sample viewing and configuration application that is included with the eBUS SDK)
• Using an application created using the eBUS SDK

Using the GenICam CLProtocol to Establish a Camera Bridge

The GenICam CLProtocol allows you to control camera parameters through a GenICam interface, such as eBUS Player or your own eBUS SDK application. The CLProtocol DLL (provided by the camera manufacturer) allows communication between the GenICam interface (register-based) and the camera (serial protocol).

Note: CLProtocol DLLs are not provided with the eBUS SDK. CLProtocol DLLs are often camera-specific, family-specific, or vendor-specific. Because CLProtocol DLLs are not mandatory (according to the Camera Link standard), some camera manufacturers may not provide them.

Figure 1: GenICam CLProtocol

 

Ensuring the Pleora Camera Link DLL Files are Installed and Registered

The GenICam CL Protocol relies on the eBUS SDK Camera Link DLLs and CameraLink registry key, which are added to your computer during the installation of the eBUS SDK. In most cases, the provided Camera Link DLLs are sufficient and you do not need to take any additional steps to set up the DLL files.
 

Defining the Environment Variable

If this is the first time you are establishing a camera bridge using the GenICam CLProtocol DLL, you must define the GENICAM_CLPROTOCOL environment variable on your computer. You can use one of the following methods:

• Use the Pleora eBUS Camera Link Setup Assistant
• Use the camera manufacturer’s software installer, if available

Using the Pleora eBUS Camera Link Setup Assistant to Define the Environment Variable

The Pleora eBUS Camera Link Setup Assistant allows you to specify the location of your CL Protocol DLL files and automatically generates (or updates) the GENICAM_CLPROTOCOL environment variable.

To use the Pleora eBUS Camera Link Setup Assistant to define the environment variable

1. If you have not yet done so, copy the CL Protocol DLL files (provided by the camera manufacturer) to your computer.

• The CLProtocol DLLs must be stored in platform-specific folders:

• 32-bit applications (Windows 32 or 64-bit) require a 32-bit CLProtocol DLL.
• 64-bit applications (Windows 64-bit only) require a 64-bit CLProtocol DLL.
• You should place CLProtocol DLLs from different camera manufacturers in different folders on your computer.

Example:

 

2. Click Start > All Programs > Pleora Technologies Inc > Tools > eBUS Camera Link Setup Assistant.
3. In the CL Protocol DLL section, click Add.
4. Navigate to the folder in which the DLL is stored and then click Select Folder. In the example above, you would click the CLProtocol folder.
5. When you close the eBUS SDK Camera Link Setup Assistant, you are asked if you want to update the Windows registry. Click Yes to complete the process of adding the DLL and generating the registry key.

Using a Software Installer to Automatically Define the Environment Variable

Some camera manufacturers may provide a software installer that deploys tools, documentation, and a CLProtocol library for the camera. If this has been provided, the software installer typically defines or extends the GENICAM_CLPROTOCOL environment variable during installation.

Note: You should verify that the CLProtocol DLL installation completed properly. In the installation folder, locate the CLProtocol path (for example, C:\Program Files\CameraManufacturerName or C:\Program Files (x86)\ CameraManufacturerName). Verify that the GENICAM_CLPROTOCOL environment variable is defined with the correct path.
 

Option 1: Establishing a GenICam CLProtocol Bridge Using eBUS Player

When you establish a GenICam CLProtocol bridge with the eBUS Player, the camera’s GenICam interface appears, which lets you adjust camera settings.
 

To start the GenICam CLProtocol bridge using eBUS Player

1. Start eBUS Player.
2. In the Connection panel, click Select/Connect.
3. Click the video interface in the Available Devices list and then click OK.
4. If the video interface does not appear (possibly because eBUS Player and the video interface are not on the same subnet), you can locate the external frame grabber by clicking Show unreachable Network Devices.
5. The Camera Control dialog box appears, which asks how you will control the camera.

6. Under How is your camera powered, select whether your camera is powered by an external power supply or if power is provided by the external frame grabber using Power Over Camera Link (PoCL).
7. Click OK.

8. In the Frame Grabber Camera Bridge dialog box, under Bridge Setup, click GenICam CL Protocol (if it is not already selected).
9. If the template does not appear, click Probe.

10. Select the XML file that the eBUS SDK uses to build the GenICam interface.

11. Click Connect.

12. Use the GenICam interface that is populated in the right-hand side of the dialog box to configure the camera.
13. When the Frame Grabber Parameters Synchronization check box is selected, the changes you made to the camera configuration are automatically applied to the external frame grabber, where a corresponding feature exists. For example, if you change the Width value on the camera, the Width value is also changed on the external frame grabber.

Option 2: Starting the GenICam CLProtocol Bridge Using the eBUS SDK

The eBUS SDK builds the GenICam interface from a GenICam XML file that is provided by the CLProtocol DLL. How the XML file is provided varies, depending on the camera manufacturer: for example, the XML file can be retrieved from the camera, bundled in the CLProtocol DLL, or it can be deployed as a file next to the CLProtocol DLL.

The link between the CL Protocol library and the eBUS SDK’s camera bridge is the eBUS SDK’s Camera Link DLL, clserpte.dll.
 

To start the GenICam CLProtocol bridge using the eBUS SDK

1. This procedure assumes that you are using the Pleora Camera Link DLL which is installed with the eBUS SDK.
2. If you have not yet done so, create the GENICAM _CLPROTOCOL environment variable and add the path to the CLProtocol DLL. For more information, see Defining the Environment Variable.
3. Use the CreateAndConnect method to create a PvDevice and connect it to your video interface.
4. Create a PvCameraBridge with these parameters:

• A PvDevice object representing the device controller.
• A PvDeviceSerialPort object representing the serial port to use on the video interface.

5. If the camera attached to the video interface uses Power over Camera Link (PoCL), configure the bridge accordingly with the SetPoCLEnabled method from PvCameraBridge.
6. Get the list of all available templates:

• Use the GetCLProtocolTemplates static method from PvCameraBridge.
• A PvStringList containing all currently available templates is obtained.

7. Use the ProbeCLProtocol method of PvCameraBridge to resolve the template into a device ID:

• Provide one of the templates as a PvString.
• Provide a PvString to contain the camera ID.
• Provide a PvStringList to contain the XML IDs.

8. Use the ConnectCLProtocol method of PvCameraBridge to connect the bridge:

• Provide one of the templates as a PvString.
• Optionally, provide an XML ID as a PvString.

Code Sample – GenICam CLProtocol Bridge

#include <PvSampleUtils.h>
#include <PvCameraBridge.h>

// Find a device controller – PvSampleUtils is used here
PvString lConnectionID;
if ( PvSelectDevice( &lConnectionID )
{
    // Connect to the found device
    PvResult lControllerResult;
    PvDevice* lDevice = PvDevice::CreateAndConnect( lConnectionID, &lControllerResult);
    if ( lControllerResult.IsOK() )
    {
        // Retrieve the CLProtocol options
        PvStringList lOptions;
        PvCameraBridge::GetCLProtocolTemplates( lOptions );

        // Use a CLProtocol option to retrieve the camera ID and XML IDs
        PvString lCameraID;
        PvStringList lXMLIDs;
        PvResult lProbeResult = lBridge.ProbeCLProtocol( *lOptions[ 0 ], lCameraID, lXMLIDs );

        if ( lProbeResult.IsOK() )
        {
            // Use a CLProtocol option and an XML ID (optional) to
            // connect the camera bridge
            PvResult lResult = lBridge.ConnectCLProtocol( *lOptions[ 0 ] )
        }
    }
}

Related Knowledge Base Articles

For a description of the other serial communication options available, see Introduction: Establishing a Serial Bridge​.