Device Discovery

Table of Contents

• • Introduction
  • Discovery in CVB
  • Driver Stack
  • Transport Layers
  • Device Lifetime
  • Connecting to a Device
  • Examples
  • Further Reading

<< What is GenICam? Configuration>>

Introduction

The first step in any image acquisition flow is to discover available devices and then connect to them, opening a data and control channel to allow for acquisition and streaming of data.

Whilst the CVB interface is designed primarily for image streaming from a camera, there are no restrictions on the type of data sent and it is perfectly capable of receiving any binary data (e.g. text or metadata). For the purpose of this documentation, the term Device will be used for the sender side (camera, sensor, etc.), and the term Image used for the data payload (image, point cloud, binary data, etc.).

Discovery in CVB

In CVB, discovery is done using the Cvb::DeviceFactory::Discover method. This will search the system and network for all compatible items according to the provided parameters and return a list of Cvb::DiscoveryInformation objects corresponding to those items.

CVB discovers devices in a hierarchical tree structure: System -> Vin -> Transport Layer -> Interface -> Device -> Stream. In the case that a branch has no items, it will not be filtered out during discovery unless the Cvb::DiscoverFlags::IncludeEmpty is used. In the case that a device can use multiple interfaces (e.g. a GEV device using either the GevFD or GevSD drivers), or a device is supported by multiple Transport Layers/Vins, the device will be present multiple times in the returned Cvb::DiscoveryInformation results list, once per configuration. It is up the calling code to select the correct device in these scenarios.

It is not always clear when all devices have been found, especially for GEV devices on complicated networks. To account for this, CVB discovery uses a timeout (default of 300ms) and will search for devices until this has been reached.

C++C#Python

C++

#include <cvb/device_factory.hpp>
 
auto devices = Cvb::DeviceFactory::Discover(Cvb::DiscoveryFlags::IgnoreVins);

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
 
var devices = DeviceFactory.Discover(DiscoverFlags.IgnoreVins);

Python

import cvb
 
devices = cvb.DeviceFactory.discover_from_root(cvb.DiscoverFlags.IgnoreVins)

Discovery Flags

The discovery procedure can be configured to show or hide specific entries in the discovery results using Cvb::DiscoverFlags. The possible flags are listed below:

Flag	Description	Note
FindAll	Discover all GenICam devices and legacy VIN drivers.	Default
IncludeEmpty	Do not filter out interfaces without attached devices.
IncludeInaccessible	Do not filter out inaccessible devices (e.g. different subnet, in use, etc).
UpToLevelSystem	Only discover up the system level (will only return the Device Factory).	Deprecated
UpToLevelVin	Only discover up the legacy VIN level.	Deprecated
UpToLevelTL	Only discover up the Transport Layer level. This will list all available transport layers, with or without connected devices.
UpToLevelInterface	Only discover up the Interface level. This will list all available interface, transport layer combinations, with or without connected devices. If an transport layer support multiple drivers (see GEVTL), these will be listed as separate interfaces.
UpToLevelDevice	Only discover up the Device level. If a device can be connected via multiple interfaces, they will be visible as distinct entries.
UpToLevelStream	Discover up the Stream level. This level is required to be able to open a stream for acquisition.	Default
IgnoreVins	Remove legacy VIN drivers from the discover result (see Third Party Drivers).	Recommended
IgnoreTLs	Remove any GenTL producers from the discover result (see Transport Layers).
IgnoreGevSD	Remove interfaces using Gig-E Vision Socket Driver from the discover result. (see GevSD).
IgnoreGevFD	Remove interfaces using Gig-E Vision Filter Driver from the discover result. (see GevFD).
IncludeMockTL	Show the CVB Mock GenTL producer (MockTL) in the discover results. This may be useful for development but not recommended for production.

Accessing Discovery Information

Once discovery has been completed, a list of Cvb::DiscoveryInformation objects will be returned. These are represented as a key-value data structure, providing all available information on the device as well as any items higher in the hierarchy. Data can be accessed using the Cvb::DiscoveryProperties flags. Only keys up-to the level specified during discovery (see Discovery Flags) will be available.

In addition, each Cvb::DiscoveryInformation object provides an Access Token that uniquely identifies the object. This can be passed to Cvb::DeviceFactory::Open to connect to the device (see Connecting to a Device).

C++C#Python

C++

#include <cvb/driver/driver.hpp>
 
auto transportLayerType = discoveryInformation[Cvb::DiscoveryProperties::DeviceTransportLayerType];

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
 
var transportLayerType = discoveryInformation[DiscoveryProperties.DeviceTransportLayerType];

Python

import cvb
 
transport_layer_type = discoveryInformation[cvb.DiscoveryProperties.DeviceTransportLayerType]

Driver Stack

CVB supports any GenICam standard compliant device using either the CVB internal Gig-E Vision (GEV) or USB3 Vision (U3V) drivers or external data producers that conform to the GenICam GenTL producer standard.

For certain manufacturers Stemmer Imaging also produces CVB compliant VIN drivers that do not support the full GenICam standard. These devices can be used with CVB but not provide the full feature set of a GenICam device. They can be discovered in the same manner as GenICam devices but have a different approach to Acquisition and Streaming.

Transport Layers

Internally, CVB supports anything that conforms to the standard of a GenTL producer, regardless of the technology and manufacturer used. CVB comes bundled with producer for the Gig-E Vision (GEV) protocol and the USB3 Vision (U3V) protocol.

GEVTL

The Gig-E Vision (GEV) to GenTL producer (GevTL) provides support for any standard-compliant GEV device and will be automatically selected for any compatible device. It supports both normal and GenDC payloads.

During discovery, the underlying driver can be selected between the CVB GEV Socket Driver (GevSD) and the CVB GEV Filter Driver (GevFD) by checking the Cvb::DiscoveryProperties::InterfaceDriverType property of the device and opening the device with the correct driver.

C++C#Python

C++

#include <cvb/device_factory.hpp>
 
auto devices = Cvb::DeviceFactory::Discover(Cvb::DiscoveryFlags::IgnoreVins);
for (auto device : devices) {
  auto driverType = device[Cvb::DiscoveryProperties::InterfaceDriverType];
  if (driverType == "FILTER")
    // Using GevFD driver
  else if (driverType == "SOCKET")
    // Using GevSD driver
}

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
 
var devices = DeviceFactory.Discover(DiscoverFlags.IgnoreVins);
for (var device in devices) {
  var driverType = device[DiscoveryProperties.InterfaceDriverType];
  if (driverType == "FILTER")
    // Using GevFD driver
  else if (driverType == "SOCKET")
    // Using GevSD driver
}

Python

import cvb
 
devices = cvb.DeviceFactory.discover_from_root(cvb.DiscoverFlags.IgnoreVins)
 
for device in devices:
  driverType = device[DiscoveryProperties.InterfaceDriverType]
  if driverType == "FILTER":
    # Using GevFD driver
  elif driverType == "SOCKET":
    # Using GevSD driver

GevSD

Note

Default driver on UNIX systems.

The GEV Socket Driver (GevSD) is the standard driver provided by CVB. It supports Windows, UNIX, and Embedded ARM systems as well as standard and GenDC data payloads.

GevFD

Note

Default driver on Windows systems.

Warning

GevFD is only supported on Windows operating systems. Use the GevSD driver for other platforms.

GevFD only supports plain data payloads. Use the GevSD driver for GenDC streaming.

The GEV Filter Driver (GevFD) is a high performance user-space driver allowing for high bandwidth image streaming for demanding applications.

USBTL

The USB3 Vision (U3V) GenTL producer (USBTL) provides support for any standard-compliant U3V device and will be automatically selected for any compatible device. It supports both standard and GenDC data payloads.

It automatically uses the libusbK system driver provided with the CVB installation.

Third-Party GenTL Producers

Warning

Stemmer Imaging is not responsible for any third-party GenTL producers loaded into CVB and can only offer limited support for any encountered issues.

In the case that a device uses a proprietary communication protocol, the CVB bundled GEVTL and USBTL producers will not be compatible. In this case, many manufacturers provide a custom GenTL producer to allow interoperability between CVB and their devices using the full GenICam feature set.

Check with the device manufacturer for a GenTL producer driver and install the .cti file into the path specified by the environment variable GENICAM_GENTL64_PATH. After this, the CVB discovery will automatically find and load the third-party GenTL producer.

Legacy VIN Drivers

Warning

Stemmer Imaging is not responsible for any third-party legacy VIN drivers loaded into CVB and can only offer limited support for any encountered issues.

Some legacy devices do not provide GenICam compliant data and cannot provide a GenTL Producer. CVB supports these devices using custom Video INterface (VIN) drivers, allowing basic acquisition and control at a lower performance when compared to GenTL Producers. These interfaces are provided by the device manufacturer for integration with the CVB SDK and should be installed to %CVB%\Drivers (Windows) or $CVB/drivers (Linux).

Opening these devices can be done either using the standard discovery interface as described in Discovery in CVB or by opening the VIN file directly using Cvb::DeviceFactory::Open.

Configuration of VIN devices can be done using the .ini files located in %CVBDATA%\Drivers (Windows) or $CVBDATA/drivers (Linux).

Device Lifetime

Opened devices are tracked using a reference counting system. As long as a reference to a device is kept alive, the connection to the device will be kept open.

When calling Cvb::DeviceFactory::Open on an already opened device, the existing device object is returned, increasing the reference count by one. No new connection will be opened.

There are a few things to consider when working with CVB to avoid unexpected problems:

• Keep the Cvb::DevicePtr in scope until it is no longer required. Otherwise, the acquisition engine will close the connection to the device. Whilst closing a connection and reopening is possible, it is not recommended for real-time applications.
  • In .NET, the device implements the IDisposable interface and should be used in combination with a using statement to ensure correct object cleanup.
  • In Python, the device implements a Context Manager and should be used in combination with a with statement to ensure correct object cleanup.

Connecting to a Device

Each discovered device will have an access token that encapsulates the connection information for that device and can be passed to Cvb::DeviceFactory::Open to establish the connection to the device. It can be accessed using the Cvb::DiscoveryInformation::AccessToken method. Once the connection to the device has been opened, the image stream can be selected and streaming started as described in Acquisition and Streaming.

When opening the device using Cvb::DeviceFactory::Open, the desired acquisition stack should be selected using the Cvb::AcquisitionStack flags listed below:

Flag	Description	Note
PreferGenTL	Prefer the GenTL acquisition stack. If the GenTL stack cannot be loaded, try opening the legacy Vin stack then try opening the non-streamable device interface before failing.	(recommended)
GenTL	Use the newest GenTL acquisition stack that provides all stream capabilities.
PreferVin	Prefer to load the legacy Vin acquisition stack. If the Vin stack cannot be loaded try opening the non-streamable device interface before failing.
Vin	Use legacy Vin acquisition stack.

For more details on the different acquisition stacks, see Cvb::AcquisitionStack.

Examples

Example	Description
Discover Gig-E Vision Devices	Discovery and connection of a Gig-E Vision Device
Discover USB3 Vision Devices	Discovery and connection of a USB3 Vision Device
Discovery using Third-Party GenTL Producer	Discovery and connection of a device using a third-party GenTL producer
Discovery using Legacy VIN Driver	Discovery and connection of a device using a legacy VIN driver

Further Reading

Getting started with C++
Getting started with .NET
Getting started with Python