|
Common Vision Blox 15.0
|
|
|
Common Vision Blox 15.0
|
Common Vision Blox provides a flexible and structured approach to configuring the acquisition stack and connected devices. Configuration is managed through a hierarchical feature tree referred to as Node Map, and individual parameters referred to as nodes. Nodes can be queried and modified by the user.
Device configuration is based on a collection of configurable features, each represented as a node within a node map. Device features are accessed using unique names, which may be defined in the Standard Feature Naming Convention (SFNC). This ensures consistent meaning and behavior across devices from different vendors. Writing to a node will automatically store the changes in the device independently from the transport technology (e.g. USB or ethernet) used.
You can use the GenICam Browser to get an overview over all available nodes. Nodes often contain additional information about a feature like the minimum or maximum value, the unit or even a tool tip.
Quick configuration allows users to provide configuration parameters that are applied during device open. This approach ensures that the device and acquisition stack are configured in an aligned manner, reducing the need for manual adjustments after initialization. While this method is less transparent than direct node manipulation, it can be more convenient for common setups and rapid deployment.
The following options are available independently from the underlying technology. See GigE Vision or USB 3 Vision for technology specific parameters.
| Name | Description | Default |
|---|---|---|
| AttachChunk | Enables and attaches chunk data in the device ("0" or "1") | as device |
| UseRdma | Enables RDMA protocols for this device (GEV only) ("0" or "1") | "0" |
| NumBuffer (deprecated) | Number of buffers to allocate for acquisition. Use Cvb::CompositeStreamBase::RegisterManagedFlowSetPool instead. | "3" |
| PixelFormat (deprecated) | Automatically convert the pixel format (see CVB 14.0) | "5" |
| RotateImage (deprecated) | Rotate the memory view on the image buffer (see CVB 14.0) | "0" |
| WidthOverride (deprecated) | Override the image width reported by the device | not used |
| HeightOverride (deprecated) | Override the image height reported by the device. Useful for frame grabbers and line scan cameras. | not used |
In a production-line environment where device configurations are fixed and known in advance, or in an installation with a large number of cameras, discovering and enumerating all devices on every startup can be time-consuming and resource-intensive. Instead, the application can open a known device directly by using a preconfigured access token. This can accelerate and simplify device opening by avoiding the need to discover and enumerate all devices before opening the target device.
If your application does not use a preconfigured access token and instead discovers and enumerates devices before opening one, see Device Discovery.
This section focuses on the access token format and workflow for opening a GigE Vision device directly. The preconfigured access-token mechanism also supports USB3 Vision (U3V) devices, but U3V devices use different device-identification fields, which are not covered here.
When the target device is known in advance, the application can open it directly by passing a preconfigured access token to a device-opening method of DeviceFactory. A preconfigured access token is a string containing data in JSON format. The data contains the information required to describe the target device and its connection through the acquisition stack.
Unlike the discovery-based workflow, this approach does not require the application to discover or enumerate devices before opening the target device. The following sections describe the structure of the access token and show how to use it with the supported APIs.
The examples in this section show the JSON content for readability. When implementing this workflow, define the access token as a string literal using the syntax of the programming language. Escape quotation marks and any other special characters as required by that syntax.
A preconfigured access token uses a hierarchical JSON structure that follows the GenTL transport-layer structure:
tls contains the transport-layer entries.ifaces contains the GenTL interface entries associated with a transport layer.devices contains the device entries associated with a GenTL interface.Each entry has an id property that identifies the corresponding transport layer, interface, or device. The lvl property indicates the entry's level in the hierarchy: 3 for the transport layer, 4 for the GenTL interface, and 5 for the device. The path property specifies the path to the GenTL Producer.
The following example shows a minimal access token for a GigE Vision device:
In this example, tls[].id and tls[].path specify the GenTL Producer (*.cti), ifaces[].id identifies the GenTL interface, and devices[].id identifies the target device.
The features and infos properties are not required for this use case and can be omitted.
The devices[].id property identifies the device to open. For a GigE Vision device, its value contains the device MAC address and the device IP address:
For example:
The device entry is associated with a network interface through its parent ifaces entry. The ifaces[].id property identifies the GenTL interface entry and includes the driver type used to access the network interface. Its format is:
Common Vision Blox supports a socket driver and a filter driver for accessing the network interface. Set <driver-type> to SD when using the socket driver, or to FD when using the filter driver. For example, the following value identifies a network interface with the specified MAC address and selects the socket driver:
The MAC address in devices[].id identifies the target device, whereas the MAC address in ifaces[].id identifies the network interface through which the device is accessed.
The tls[].id and tls[].path properties identify the GenTL Producer used to access the device. When opening a GigE Vision device, they must refer to the GigE Vision GenTL Producer.
On Windows, the GigE Vision GenTL Producer provided with Common Vision Blox is located below the directory referenced by the CVB environment variable. For example:
After resolving the CVB environment variable, this path may look as follows:
On Linux, the GigE Vision GenTL Producer is located at:
After resolving the CVB environment variable, this path may look as follows:
In the access token, tls[].id and tls[].path must specify the path to the same GenTL Producer. The path is platform-dependent and must refer to the GenTL Producer installed on the target system.
The identifiers and paths in the access token must describe the environment in which the application runs. Therefore, an access token created for one device or network configuration becomes invalid if the device, network interface, driver type, or IP address changes.
When preparing an access token for another device, update the corresponding devices[].id and ifaces[].id values. If the driver type used to access the network interface changes, update the driver type in ifaces[].id as well. The tls[].id and tls[].path values must refer to the GenTL Producer used to access the device.
After defining the access token, pass it to the device-opening method provided by DeviceFactory. The API interprets the JSON document contained in the string and opens the device identified by the token. If the string does not contain valid JSON or does not conform to the expected access token format, device opening fails.
The following examples use the same demo access token with the C++, Python, and C#/.NET APIs. In each example, the access token is passed as a string to the device-opening API.
First, define the demo access token:
Then, pass the access token to the device-opening API to open the target device:
The example above uses the Windows path to GEVTL.cti. On Linux, use the path to the installed Linux GenTL Producer instead:
The path must be used consistently in both tls[].id and tls[].path. The device MAC address, the MAC address of the network interface, the driver type, and the IP address must also match the target environment exactly. If any of these values changes, the access token becomes invalid and the device cannot be opened with that token.
The access token can contain additional configuration parameters in addition to the information required to identify the target device. These parameters configure the acquisition environment; they are not used to identify the device.
Parameters are specified as name-value pairs in the optional params property. The params property does not have to be included in the access token. If specified, it must contain a JSON array. Each element of the array contains a parameter name and value. Parameter names and values are case-sensitive.
Parameter values are specified as strings in the access token, regardless of their logical type. The Type column below indicates the logical type of a parameter, not the JSON type of its value property.
Boolean parameter values can be specified as the strings true, false, 0, or 1. The values 0 and 1 are the only supported integer representations of Boolean values. Other integer values are not supported; in particular, a nonzero value other than 1 is not interpreted as true.
When writing the access token directly as JSON, separate elements in the params array with commas. Do not add a trailing comma after the last element. Trailing commas are not valid in JSON.
The parameters are divided into two groups:
The following parameters are specific to Common Vision Blox and can be specified in the params property of the corresponding GenTL interface entry.
| Name | Type | Description | Valid values | Default |
|---|---|---|---|---|
InterPacketDelay | Integer | Sets the minimum delay, in timestamp-counter units, between packets transmitted on the stream channel. Use this parameter to reduce the packet rate when the receiver cannot keep up. | >=0 | 0 |
PacketResend | Boolean | Enables packet resending when set to true or 1. Disables packet resending when set to false or 0. | true/false/0/1 | false |
The following parameters can be specified in the params property of the corresponding device entry. Their availability depends on the implementation of the device.
| Name | Type | Description | Valid values | Default |
|---|---|---|---|---|
AttachChunk | Boolean | Enables the transfer of GenICam-compliant chunk data containing metadata when set to true or 1. Disables the transfer when set to false or 0. | true/false/0/1 | false |
HeartbeatTimeout | Integer | Sets the heartbeat timeout in milliseconds. The value is internally rounded according to the heartbeat clock, in increments of 100 ms. The minimum value is 500 ms. | >=500 | 3000 |
PacketSize | Integer | Specifies the stream packet size, in bytes, for the selected stream channel. For a transmitter, this is the packet size to send; for a receiver, this is the maximum packet size supported. The value includes the IP, UDP, and GVSP headers. | >0 | 1500 |
UseRdma | Boolean | Enables RDMA transfer when set to true or 1. Disables RDMA transfer when set to false or 0. | true/false/0/1 | false |
UseTurboDrive | Boolean | Enables Turbo Drive when set to true or 1. Disables Turbo Drive when set to false or 0. | true/false/0/1 | false |
The following examples show how to create an access token containing the parameters described above.
In these examples, commas after elements are part of the C++, .NET, or Python collection syntax. The serialized result is valid JSON and does not contain trailing commas.
A preconfigured access token describes a specific acquisition setup. It can be reused on another system only if the relevant hardware, network configuration, and compatible software environment are unchanged. Otherwise, the token must be updated. In particular, it is not portable across different network infrastructures or operating systems.
The following information must match the environment in which the application runs:
tls[].id and tls[].path. The file must be located in one of the directories listed in the GENICAM_GENTL64_PATH environment variable.ifaces[].iddevices[].idThe GenTL Producer is searched for in the directories listed in the GENICAM_GENTL64_PATH environment variable. If the GenTL Producer specified by tls[].id and tls[].path cannot be found in these directories, loading the GenTL Producer fails and the device cannot be opened.
The access token may need to be updated when the device or acquisition environment changes. For example, update the token if:
This workflow is intended for environments in which the target device and its connection are known in advance. Because the application does not discover and enumerate devices before opening the target, an incorrect or outdated access token prevents the intended device from being opened. When the device or network configuration is not fixed, use the discovery-based workflow described in Device Discovery.
The preconfigured access-token mechanism also supports USB3 Vision (U3V) devices. However, the device-identification (id) fields used by U3V devices are different from and incompatible with those described in this section. Other machine vision standard-compliant devices are not supported by this mechanism.
Additional configuration parameters may be supported by the acquisition stack or the GenTL Producer. These parameters are separate from the identifiers required to locate the target device. Only parameters documented as supported for the selected acquisition stack and GenTL Producer should be included in the access token. The handling of an unsupported or unavailable parameter depends on the component that processes the token; applications must not rely on unsupported parameters being applied.
Configurations can apply at different level respectively modules of the acquisition stack. Each node map is accessible through a string ID:
Every module of the GenTL can provide a node map with potential features to configure. The above node maps can be explored in the GenICam Browser. In addition, Common Vision Blox introduces two specialized node maps:
Both node maps offer a node map interface but are not actual GenAPI XML node maps. The optimized access to vendor specific features, that are not covered by GenICam.
The VinDevice node map offers users to configure the driver-related device features. Specifically, the node map includes features that are related to TurboDrive feature, or the GenICam chunk data feature. The following list describes all available nodes that belong to the VinDevice node map:
true to the node .true to the node .The VinBuffer node map provides means to gather information about a single buffer returned/delivered by the stream's Wait method call. The VinBuffer node maps the following feature nodes:
true, it indicates that the buffer data is not logically complete. In case of incomplete transmission for some reasons such as missing packets, the number of bytes successfully written to the buffer are reported in the SizeFilled node.The CVB acquisition stack manages the lifetime of all node maps and nodes automatically using a reference counting mechanism. In addition a node will keep the node map alive and the node map will keep its provider alive.
The data stream node map provides both standard and vendor-specific nodes that offer insights into the acquisition engine. These statistics include buffer states, lost packets, and resend requests in the case of GigE Vision (GEV). Monitoring these values helps diagnose performance issues and optimize data flow within the acquisition pipeline.
| Example | Description |
|---|---|
| Vin Node Maps | Accessing the Vin node maps. |
| Software Trigger | Configuring and sending a software trigger. |
Getting started with C++
Getting started with .NET
Getting started with Python