Skip to content

Building Applications with pylon C#

Note

Throughout the following paragraphs, the folder where the pylon SDK was installed is denoted as < SDK ROOT >, which may proxy for, e.g., 'C:\ProgramFiles\Basler\pylon7.1'. The pylon installation procedure sets the environment variable < PYLON_DEV_DIR > to '< SDK ROOT >\Development'.

The pylon SDK setup installs all header and library files required for building pylon applications, including the pylon C API libraries and headers.

As part of the pylon SDK installation, sample programs are also installed in < SDK ROOT >/Development/Samples/C. These samples include a Microsoft Visual Studio 2010 solution and associated project files demonstrating how to set up the build environment for pylon based applications. Building with Borland C V5.5 is also supported through a hierarchy of make files and a top level build script named 'buildall.cmd'.

Build Environment#

In order for the compiler to be able to locate the pylon C header files, the '< PYLON_DEV_DIR >\include' directory must be added to the compiler's include path.

Applications using the pylon C API must be linked to the pylon C import library, which is located in '< PYLON_DEV_DIR >\lib\Win32' or in '< PYLON_DEV_DIR >\lib\x64' for 64-Bit builds. The correct library directory must be added to the linker's search path in order for the library to be found. The following libraries are available:

  • PylonC.lib for using Microsoft Visual C
  • PylonC_BCC55.lib for using Borland C V5.5

Debugging pylon Applications Using GigE Cameras#

Heartbeat#

By default, pylon sends a heartbeat signal to all GigE cameras and the cameras then respond with a heartbeat signal of their own going back to pylon. If the cameras don't receive a heartbeat signal from pylon in the defined interval, the camera doesn't respond to commands from pylon anymore and is disconnected.

Heartbeat During Debugging#

When you work in debugging mode in pylon and hit a breakpoint in your pylon application, the debugger suspends all threads including the one sending the heartbeats. Thus, when you debug your pylon application and single-step through your code, no heartbeats are sent to the camera and the camera closes the connection.

To work around this, pylon detects when you debug your pylon application and extends the heartbeat timeout to one hour. This allows you to single-step through your pylon application without the camera closing the connection.

Extending the heartbeat timeout has the following side effect: When you terminate your pylon application using the debugger while the camera is opened and you restart your pylon application right after terminating it, you may get an error stating that the camera is currently in use. This is so, because due to the forced termination of the pylon application, pylon couldn't inform the camera of the termination and did not close the connection. As a result, the camera doesn't accept any new connections until the heartbeat timeout has elapsed or is restarted.

PylonGigEConnectionGuard#

To assist debugging pylon applications while using GigE cameras, you can use the PylonGigEConnectionGuard. The PylonGigEConnectionGuard is a small application that starts automatically when you debug your pylon application and open a connection to a GigE camera. If you close the connection between pylon and the camera, pylon stops the PylonGigEConnectionGuard. In case your pylon application terminates unexpectedly, i.e. by using the debugger, pylon's PylonGigEConnectionGuard automatically detects the unexpected termination and closes the connection to the camera.

If pylon detects the debugging mode, pylon does the following:

  • pylon enables the PylonGigEConnectionGuard. You can override this default behavior by setting the ConnectionGuardEnable node of the camera transport layer in your code.
  • pylon sets the heartbeat timeout to 60 minutes. You can override this value by setting the heartbeat timeout value HeartbeatTimeout in the camera transport layer in your code or by setting the PYLON_GIGE_HEARTBEAT environment variable.

If needed, you can modify these default values in your code before opening the camera by setting the values ConnectionGuardEnable and /or the HeartbeatTimeout nodes of the transport layer:

GENAPIC_RESULT              res;
PYLON_DEVICE_HANDLE         hDev;
NODEMAP_HANDLE              hTlNodemap;
NODE_HANDLE                 hNodeGuard;
NODE_HANDLE                 hNodeHeartbeat;

// Create the first camera device found.
res = PylonCreateDeviceByIndex( 0, &hDev );
CHECK(res);

// Retrieve the transport layer node map.
res = PylonDeviceGetTLNodeMap( hDev, &hTlNodemap );
CHECK(res);

// Find the PylonGigEConnectionGuard enable node.
res = GenApiNodeMapGetNode( hTlNodemap, "ConnectionGuardEnable", &hNodeGuard );
CHECK(res);

// Enable the guard.
res = GenApiBooleanSetValue( hNodeGuard, 1 );
CHECK( res );

// Find the hearbeat timeout node.
res = GenApiNodeMapGetNode( hTlNodemap, "HeartbeatTimeout", &hNodeHeartbeat );
CHECK(res);

// Set hearbeat timeout in ms.
res = GenApiIntegerSetValue( hNodeHeartbeat, 3000 );
CHECK( res );

If you want to configure the heartbeat timeout using an environment variable, set an environment variable named PYLON_GIGE_HEARTBEAT and set its value to the desired timeout in milliseconds. If you are working in Visual Studio, you can set the environment variable in the project settings for your debugging session: In the project properties, select Configuration Properties->Debugging->Environment.