All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Building Applications with pylon C

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

Sample Programs are included in the installation archive in Samples/C/. The folder contains a top-level Makefile that can be used to build the different Sample Programs.

Build Environment

This section shows the most common Linux build settings for building an application using pylon and the GNU tool chain.

To collect all the required parameters to build a pylon-based application, we created the pylon-config utility. It works like pkg-config and you can call pylon-config --help to get a list of supported parameters.

In a typical GNU Make-based project you can add the following lines to your Makefile:

PYLON_ROOT ?= /opt/pylon5
CPPFLAGS += $(shell $(PYLON_ROOT)/bin/pylon-config --cflags pylonc)
LDFLAGS += $(shell $(PYLON_ROOT)/bin/pylon-config --libs-rpath pylonc)
LDLIBS += $(shell $(PYLON_ROOT)/bin/pylon-config --libs pylonc)

If needed, you can now overwrite the default installation path using the environment variable PYLON_ROOT. E.g.:

PYLON_ROOT=/path/to/your/pylon/install make

Locating dependencies using RPATH

At runtime, the dynamic linker must know where it can find the pylon libraries. We use the rpath feature of the GNU linker to specify the runtime location of pylon. You can find more details about rpath and runpath at https://en.wikipedia.org/wiki/Rpath.

There are two cases to distinguish when you want to build an application with rpath support:

Note
These snippets assume, that the environment variable PYLON_ROOT points to your pylon installation (e.g. /opt/pylon5).

Debugging pylon Applications When Using GigE Cameras

When debugging a pylon application using a GigE camera, heartbeat timeouts may be encountered. Any pylon application is required to send special network packets, called heartbeat packets, to the camera at regular intervals to hold the connection open. If the camera does not receive these heartbeat packets for some predefined time (the so-called 'heartbeat timeout'), it will assume that the connection is broken, and will cease to accept further commands from the application.

This is not a problem if the application is running normally, as pylon will take care of generating the heartbeat. During debugging, however, the debugger may stop the application, including all its threads, when a breakpoint is hit or single-stepping is done. This will also stop the heartbeat.

The problem can be worked around by extending the heartbeat timeout during debugging. The pylon GigE transport layer automatically sets the heartbeat timeout to 5 minutes when creating a device if the program runs under a debugger. This can be overridden by setting the PYLON_GIGE_HEARTBEAT environment variable. We recommend not to rely on the default mechanism but to explicitly specify the heartbeat timeout by setting the environment variable or by setting an appropriate heartbeat timeout in the application.

To set the heartbeat timeout programmatically, write a new value to the HeartbeatTimeout node:

/* If the device provides a heartbeat timeout, this function will set the heartbeat timeout.
When the device provides the parameter, the old value is returned, -1 otherwise.
The heartbeat timeout is a parameter provided by the transport layer.
The transport layer parameters are exposed as a GenApi node map that
can be retrieved from the device.
*/
int64_t setHeartbeatTimeout( PYLON_DEVICE_HANDLE hDev, int64_t timeout_ms )
{
NODEMAP_HANDLE hNodemap; /* Handle to the node map */
NODE_HANDLE hNode; /* Handle to a node, i.e., a feature */
GENAPIC_RESULT res; /* Return value */
int64_t oldTimeout; /* The current timeout value */
/* Get the node map for the transport layer parameters. */
res = PylonDeviceGetTLNodeMap( hDev, &hNodemap );
CHECK(res);
if ( GENAPIC_INVALID_HANDLE == hNodemap )
{
/* The device doesn't provide a transport layer node map. Nothing to do. */
return -1;
}
/* Get the node for the heartbeat timeout parameter. */
res = GenApiNodeMapGetNode( hNodemap, "HeartbeatTimeout", &hNode );
CHECK(res);
if ( GENAPIC_INVALID_HANDLE == hNode )
{
/* There is no heartbeat timeout parameter. Nothing to do. */
return -1;
}
/* Get the current value. */
res = GenApiIntegerGetValue( hNode, &oldTimeout );
CHECK(res);
/* Set the new value. */
res = GenApiIntegerSetValue( hNode, timeout_ms );
CHECK(res);
/* Return the old value. */
return oldTimeout;
}
Note
If the heartbeat timeout is set to a large value, and then the application is terminated without calling the PylonDeviceClose() function (either explicitly or implicitly through PylonTerminate()), it will be impossible to reconnect to the camera before the timeout has expired. This may happen if the application is stopped by the debugger, for example. One can recover from this state, by disconnecting and reconnecting the camera again.

pylon C 5.0.5
Copyright © 2006-2016 Basler AG (Thu Aug 11 2016 18:01:26)