Pylon::IGigETransportLayer#

Module: Transport Layer

Extends the ITransportLayer interface by GigE Vision specific functionality.

#include <pylon/gige/GigETransportLayer.h>

Inherits from Pylon::ITransportLayer, Pylon::IDeviceFactory

Public Functions#

Public Functions Documentation#

function EnumerateAllDevices#

virtual int EnumerateAllDevices(
    DeviceInfoList_t & ,
    bool addToList =false
) =0

Enumerates all available Basler GigE Vision devices.

In contrast to the ITransportLayer::EnumerateDevices method, devices having a subnet configured that is different from the subnet of the application will be listed.

All Basler GigE Vision devices will be listed, including the Basler blaze, which is usually not considered by the GigE transport layer.

function ForceIp#

virtual void ForceIp(
    const String_t & MacAddress,
    const String_t & IpAddress,
    const String_t & SubnetMask,
    const String_t & DefaultGateway
) =0

"Force" a static IP address configuration in a device identified by its MAC Address

Parameters:

• MacAddress MAC address as a string, no delimiters are used. e.g., 003053061a58
• IpAddress Temporary IP address, "dot notation", e.g., 192.168.1.2
• SubnetMask Temporary SubnetMask, "dot notation", e.g. 255.255.255.0
• DefaultGateway Temporary DefaultGateway, "dot notation", e.g., 192.168.1.1

Note When calling this function, there must be no opened camera object for the device to be reconfigured!

This applies to all Basler GigE Vision devices, including the Basler blaze, which isn't usually considered by the GigE transport layer.

function RestartIpConfiguration#

virtual void RestartIpConfiguration(
    const String_t & MacAddress
) =0

Let a device restart the IP configuration cycle.

Parameters:

• MacAddress MAC address as a string, no delimiters are used, e.g., 003053061a58

Note This function fails when the device is open, i.e., a control channel is established

function AnnounceRemoteDevice#

virtual bool AnnounceRemoteDevice(
    const String_t & IpAddress,
    CDeviceInfo * pInfo =NULL
) =0

Announce that a remote device is going to be used.

Parameters:

• IpAddress address of device in "dot notation"
• pInfo This optional parameter holds the full device info if found

Note This device must be reachable, a route is configured.

This applies to all Basler GigE Vision devices, including the Basler blaze, which isn't usually considered by the GigE transport layer.

function RenounceRemoteDevice#

virtual bool RenounceRemoteDevice(
    const String_t & IpAddress
) =0

Stop using remote device.

Parameters:

• IpAddress address of device in "dot notation"

function BroadcastIpConfiguration#

virtual bool BroadcastIpConfiguration(
    const String_t & MacAddress,
    bool EnablePersistentIp,
    bool EnableDhcp,
    const String_t & IpAddress,
    const String_t & SubnetMask,
    const String_t & DefaultGateway,
    const String_t & UserdefinedName
) =0

Broadcast a new IP configuration.

Parameters:

• MacAddress MAC address as a string, no delimiters are used. e.g., 003053061a58
• EnablePersistentIp If true, a persistent Ip address will be set
• EnableDhcp If true, DHCP is enabled
• IpAddress Device's new IP address, "dot notation", e.g., 192.168.1.2
• SubnetMask Device's new SubnetMask, "dot notation", e.g. 255.255.255.0
• DefaultGateway Device's new DefaultGateway, "dot notation", e.g., 192.168.1.1
• UserdefinedName Device's new UserdefinedName, maximal 16 character

Return: true if configuration was successfully written

All Basler GigE Vision devices can be configured, including the Basler blaze, which isn't usually considered by the GigE transport layer. When configuring a blaze camera, some options may not be supported. Please check the camera documentation for more information.

function IssueActionCommand#

virtual bool IssueActionCommand(
    uint32_t deviceKey,
    uint32_t groupKey,
    uint32_t groupMask,
    const String_t & broadcastAddress ="255.255.255.255",
    uint32_t timeoutMs =0,
    uint32_t * pNumResults =0,
    GigEActionCommandResult results[] =NULL
) =0

Issue a broadcast action command.

Parameters:

• deviceKey The device key addresses devices managed by an application. The device key is only known to the application controlling its camera devices and it ensures that only this application can trigger the camera devices. Therefore the device key cannot be read from a device. An exact match of the send deviceKey and the device key stored in a device is required for executing an action.
• groupKey The group key is used to create groups of devices or actions. An exact match of the send groupKey and the group key stored in a device for an action is required for executing an action.
• groupMask The groupMask is a bit mask that allows to send an action to a subgroup of the devices addressed by the deviceKey``groupKey pair. The result of a bitwise AND operation of groupMask and the group mask stored in a device for an action must be non-zero for executing an action.
• broadcastAddress BroadcastAddress in dot notation where the command will be broadcast to, e.g. 255.255.255.255 (all adapters, default), 192.168.1.255 (all devices in a single subnet 192.168.1.xxx), 192.168.1.38 (single device). See the note below.
• timeoutMs Optional: Time in milliseconds the call is waiting for acknowledges of the addressed devices. Waiting for acknowledges is stopped if pNumResults have been received. This parameter can be 0 if a check of action command results is not required.
• pNumResults Optional: The number of results in the results array. The value passed should be equal to the expected number of devices that acknowledge the command. Returns the number of received results. This parameter is ignored if timeoutMs is 0. Thus this parameter can be NULL if timeoutMs is 0.
• results Optional: An Array with *pNumResults elements to hold the action command result status. The buffer is filled beginning from the start. Remaining results are not changed if less results are received than result items available. This parameter is ignored if timeoutMs is 0. Thus this parameter can be NULL if timeoutMs is 0.

Return: Returns true if *pNumResults have been received and the Status of all results is GigEActionCommandStatus_Ok. Returns true if no results have been requested.

Note The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time. Directed broadcasts (192.168.1.255) or unicasts (192.168.1.38) are only sent if the request subnet matches the subnet of the IP address, i.e., if no gateway or routing are required.

Precondition:

• IP4 addresses must be used.
• groupMask must not be 0.
• pNumResult, *pNumResult and results must not be 0 if a timeoutMs value other than 0 is passed.

Error Safety:

Throws an exception if the preconditions are not met. Throws C++ exceptions.

Thread Safety:

The method is thread-safe.

The action command feature lets you trigger actions in multiple devices (e.g. cameras) at roughly the same time or at a defined point in time (scheduled action command) by using a single broadcast protocol message (without extra cabling). Action commands are used in cameras in the same way as for example the digital input lines.

See [Grab_UsingActionCommand] and Pylon::CActionTriggerConfiguration for more information.

function IssueScheduledActionCommand#

virtual bool IssueScheduledActionCommand(
    uint32_t deviceKey,
    uint32_t groupKey,
    uint32_t groupMask,
    uint64_t actionTimeNs,
    const String_t & broadcastAddress ="255.255.255.255",
    uint32_t timeoutMs =0,
    uint32_t * pNumResults =0,
    GigEActionCommandResult results[] =NULL
) =0

Issue a scheduled action command via broadcast.

Parameters:

• deviceKey The device key addresses devices managed by an application. The device key is only known to the application controlling its camera devices and it ensures that only this application can trigger the camera devices. Therefore the device key cannot be read from a device. An exact match of the send deviceKey and the device key stored in a device is required for executing an action.
• groupKey The group key is used to create groups of devices or actions. An exact match of the send groupKey and the group key stored in a device for an action is required for executing an action.
• groupMask The groupMask is a bit mask that allows to send an action to a subgroup of the devices addressed by the deviceKey``groupKey pair. The result of a bitwise AND operation of groupMask and the group mask stored in a device for an action must be non-zero for executing an action.
• broadcastAddress BroadcastAddress in dot notation where the command will be broadcast to, e.g. 255.255.255.255 (all adapters, default), 192.168.1.255 (all devices in a single subnet 192.168.1.xxx), 192.168.1.38 (single device). See the note below.
• timeoutMs Optional: Time in milliseconds the call is waiting for acknowledges of the addressed devices. Waiting for acknowledges is stopped if pNumResults have been received. This parameter can be 0 if a check of action command results is not required.
• pNumResults Optional: The number of results in the results array. The value passed should be equal to the expected number of devices that acknowledge the command. Returns the number of received results. This parameter is ignored if timeoutMs is 0. Thus this parameter can be NULL if timeoutMs is 0.
• results Optional: An Array with *pNumResults elements to hold the action command result status. The buffer is filled beginning from the start. Remaining results are not changed if less results are received than result items available. This parameter is ignored if timeoutMs is 0. Thus this parameter can be NULL if timeoutMs is 0.
• actionTimeNs Time in nanoseconds when the action is to be executed. The actual value depends on the used master clock. A master clock value can be obtained for instance for a set of synchronized camera devices by reading the timestamp value (GevTimestampValue) after latching the timestamp value (GevTimestampControlLatch) from one camera device of the set

Return: Returns true if *pNumResults have been received and the Status of all results is GigEActionCommandStatus_Ok. Returns true if no results have been requested.

Note The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time. Directed broadcasts (192.168.1.255) or unicasts (192.168.1.38) are only sent if the request subnet matches the subnet of the IP address, i.e., if no gateway or routing are required.

Precondition:

*

• IP4 addresses must be used.
• groupMask must not be 0.
• pNumResult, *pNumResult and results must not be 0 if a timeoutMs value other than 0 is passed.
• actionTimeNs must be smaller than or equal INT64_MAX.

Error Safety:

Throws an exception if the preconditions are not met. Throws C++ exceptions.

Thread Safety:

The method is thread-safe.

The action command feature lets you trigger actions in multiple devices (e.g. cameras) at roughly the same time or at a defined point in time (scheduled action command) by using a single broadcast protocol message (without extra cabling). Action commands are used in cameras in the same way as for example the digital input lines.

See [Grab_UsingActionCommand] and Pylon::CActionTriggerConfiguration for more information.

function GetTlInfo#

virtual CTlInfo GetTlInfo() const =0

Returns a CTlInfo object holding information about the transport layer.

Return: Returns a CTlInfo object holding information about the transport layer.

function CreateDeviceInfo#

virtual CDeviceInfo CreateDeviceInfo() =0

Creates and returns an 'empty' Device Info object appropriate for the transport layer.

Device Info objects returned by the CreateDeviceInfo() method are used to create devices from device info objects that are not the result of a device enumeration process but are provided by the user. The user is responsible for filling in the fields of the Device Info object that are needed to identify and create a device.

Example: To open a GigE device for which the IP address is known, the user lets the Transport Layer object create a Device Info object, specifies the IP address and passes the device info object to the CreateDevice() method.

function GetNodeMap#

virtual GenApi::INodeMap * GetNodeMap() =0

Returns the GenApi node map used for accessing parameters provided by the transport layer.

Return: NULL, if the transport layer doesn't provide parameters, a pointer to the parameter node map otherwise.

function EnumerateInterfaces#

virtual int EnumerateInterfaces(
    InterfaceInfoList_t & list,
    bool addToList =false
) =0

Retrieves a list of available interfaces.

Parameters:

• list The list to be filled with interface info objects. The list contains Pylon::CInterfaceInfo objects used for the interface creation. It is ordered by device class and interface ID using the operator Pylon::CInterfaceInfo::operator<().
• addToList If true, devices found will be added to the list instead of clearing the list. By default, the list passed in will be cleared.

Return: Number of interfaces provided by the transport layer.

Note Currently, this method is used mainly for the pylon GenTL Consumer transport layer, which is used for CoaXPress, for example. All other pylon transport layers return one default interface. The default interface will forward all IDeviceFactory methods to the transport layer that created the interface object. The default interface does not provide a node map.

Thread Safety:

This method is thread-safe.

Error Safety:

Can throw C++ exceptions.

An interface may represent a frame grabber board, a network card, etc.

function CreateInterface#

virtual IInterface * CreateInterface(
    const CInterfaceInfo & interfaceInfo
) =0

Creates an interface object from an interface info object.

Parameters:

• interfaceInfo The Interface info object. You can pass an interface info object returned by EnumerateInterfaces() or a user-provided interface info object. User-provided interface info objects can be preset with properties required for an interface, e.g. the interface ID. The implementation tries to find a matching interface.

Return: Returns the pointer to the interface created.

Postcondition: The interface created must be freed by calling DestroyInterface(). The transport layer is not destroyed as long as the interface is not destroyed. Never try to delete a pointer to an interface object by calling free or delete. Always use the DestroyInterface() method.

Error Safety:

Throws an exception if creating the interface fails.

Thread Safety:

This method is thread-safe.

function DestroyInterface#

virtual void DestroyInterface(
    IInterface * pInterface
) =0

Destroys an interface.

Parameters:

• pInterface The pointer to an interface created by this transport layer.

Precondition: The interface has been created by this transport layer using CreateInterface() and has not been destroyed using DestroyInterface() yet.

Postcondition: The interface is deleted and must not be used any longer.

Error Safety:

Throws a C++ exception if the preconditions are not met.

Thread Safety:

This method is thread-safe.

function EnumerateDevices#

virtual int EnumerateDevices(
    DeviceInfoList_t & list,
    bool addToList =false
) =0

Retrieves a list of available devices.

Parameters:

• list List to be filled with device info objects.
• addToList If true, the devices found will be appended to the list instead of deleting the list. Only newly discovered devices are sorted and not the entire list.

Return: Number of devices found.

Reimplemented by: Pylon::CTlFactory::EnumerateDevices, Pylon::CInstantInterface::EnumerateDevices

The list contains Pylon::CDeviceInfo objects used for the device creation and is ordered by device class and serial number using the operator Pylon::CDeviceInfo::operator<(). By default, the list will be cleared before the device discovery is started.

function EnumerateDevices#

virtual int EnumerateDevices(
    DeviceInfoList_t & list,
    const DeviceInfoList_t & filter,
    bool addToList =false
) =0

Retrieves a list of available devices filtered by given properties, usable for looking for specific devices.

Parameters:

• list List to be filled with device info objects.
• filter A list of device info objects with user-provided properties that a device can match.
• addToList If true, the devices found will be appended to the list instead of deleting the list. Only newly discovered devices are sorted and not the entire list.

Return: Number of devices found.

Reimplemented by: Pylon::CTlFactory::EnumerateDevices, Pylon::CInstantInterface::EnumerateDevices

The list contains Pylon::CDeviceInfo objects used for the device creation and is ordered by device class and serial number using the operator Pylon::CDeviceInfo::operator<(). By default, the list will be cleared before the device discovery is started. The filter list can contain a list of device info objects containing properties a device must have, e.g., the user-provided name or the serial number. A device is returned if it matches the properties of any of the device info objects on the filter list. If the device class property is set in the filter device info objects, the search is limited to the required transport layers.

function CreateDevice#

virtual IPylonDevice * CreateDevice(
    const CDeviceInfo & di
) =0

Creates a camera object from a device info object.

Parameters:

• di Device info object containing all information needed to identify exactly one device.

Reimplemented by: Pylon::CTlFactory::CreateDevice, Pylon::CInstantInterface::CreateDevice

This method accepts either a device info object from a device enumeration or a user-provided device info object. User-provided device info objects can be preset with properties required for a device, e.g. the user-provided name or the serial number. The implementation tries to find a matching camera by using device enumeration. When the device class property is set, the search is limited to the required transport layer.

If the device creation fails, a GenApi::GenericException will be thrown.

function CreateDevice#

virtual IPylonDevice * CreateDevice(
    const CDeviceInfo & di,
    const StringList_t & InjectedXmlStrings
) =0

Reimplemented by: Pylon::CTlFactory::CreateDevice, Pylon::CInstantInterface::CreateDevice

Creates a camera object from a device info object, injecting additional GenICam XML definition strings. Currently only one injected xml string is supported.

function CreateDevice#

virtual IPylonDevice * CreateDevice(
    const String_t &
) =0

Reimplemented by: Pylon::CTlFactory::CreateDevice, Pylon::CInstantInterface::CreateDevice

This method is deprecated. Use CreateDevice and pass a CDeviceInfo object containing the full name as a property. Example: IPylonDevice* device = TlFactory.CreateDevice( CDeviceInfo().SetFullName( fullname)); creates a device that matches its full name (i.e., as returned by CDeviceInfo::GetFullName).

function CreateFirstDevice#

virtual IPylonDevice * CreateFirstDevice(
    const CDeviceInfo & di =CDeviceInfo()
) =0

Reimplemented by: Pylon::CTlFactory::CreateFirstDevice, Pylon::CInstantInterface::CreateFirstDevice

If multiple devices match the provided properties, the first device found is created. The order in which the devices are found can vary from call to call.

function CreateFirstDevice#

virtual IPylonDevice * CreateFirstDevice(
    const CDeviceInfo & di,
    const StringList_t & InjectedXmlStrings
) =0

Reimplemented by: Pylon::CTlFactory::CreateFirstDevice, Pylon::CInstantInterface::CreateFirstDevice

Creates the first found camera device matching the provided properties, injecting additional GenICam XML definition strings. Currently only one injected xml string is supported.

function DestroyDevice#

virtual void DestroyDevice(
    IPylonDevice *
) =0

Destroys a device.

Note Never try to delete a pointer to a camera device by calling free or delete. Always use the DestroyDevice method.

Reimplemented by: Pylon::CTlFactory::DestroyDevice, Pylon::CInstantInterface::DestroyDevice

function IsDeviceAccessible#

virtual bool IsDeviceAccessible(
    const CDeviceInfo & deviceInfo,
    AccessModeSet mode =Control,
    EDeviceAccessiblityInfo * pAccessibilityInfo =NULL
) =0

This method can be used to check if a camera device can be created and opened.

Parameters:

• deviceInfo Properties to find/identify the camera device to check.

• mode Used for defining how a device is accessed. The use of the mode information is transport layer-specific.

• For CameraLink, and USB devices, the mode information is ignored.

• For GigE devices, the Exclusive and Control flags are used for defining how a device is accessed. Other mode information is ignored.
• For devices of any type that are accessed via the GenICam GenTL transport layer, the mode is ignored.
• pAccessibilityInfo Optional parameter that provides more information about whether a device is accessible or not.

Return: True if device can be opened with provided access mode.

Precondition: The deviceInfo object properties specify exactly one device. This is the case when the device info object has been obtained using device enumeration.

Error Safety:

Throws a C++ exception, if the preconditions are not met.

Reimplemented by: Pylon::CTlFactory::IsDeviceAccessible, Pylon::CInstantInterface::IsDeviceAccessible

This method accepts either a device info object from a device enumeration or a user-provided device info object. User-provided device info objects can be preset with properties required for a device, e.g. the user-provided name or the serial number. The implementation tries to find a matching camera by using device enumeration. When the device class property is set, see DeviceClass.h header file, the search is limited to the required transport layer. For more information, see [Applying a Filter when Enumerating Cameras].