Introduction

Common Vision Blox (CVB) provides a uniform method for accessing GenICam-compliant camera features, independent of the underlying transport layer. This is achieved through the GenICam GenApi, which standardizes feature access and control.

Purpose of GenApi

GenApi enables devices to be self-describing in a vendor-independent way. Instead of requiring custom drivers or proprietary protocols for each device, GenApi provides a standardized mechanism for discovering, accessing, and configuring features. This ensures interoperability between different cameras and software solutions (Transport Layers), simplifying integration and reducing development effort.

Benefits of the XML-Based Approach

Although the XML-based camera description file is not directly exposed to the user, it plays a crucial role in feature management. By defining high-level features and dependencies in XML, complex feature interactions can be handled by the host software rather than the device. This approach:

Reduces I/O operations, minimizing communication overhead with the device.
Improves safety, preventing misconfigurations that could lead to device damage.
Simplifies feature control, allowing the host to enforce constraints and manage interdependencies automatically.
Enhances portability, ensuring consistent behavior across different GenICam-compliant cameras.

GenApi Details

GenApi is a standardized implementation maintained by the GenICam working group as part of the GenICam standard. Its primary technical purpose is to parse XML description files from devices or GenTL modules and translate node access into register read and write calls. This abstraction ensures that feature access remains consistent across different hardware and vendors.

Each GenICam-compliant device provides a structured hierarchy of nodes, organized in a node map. Nodes represent device features and expose specific properties through well-defined interfaces. While some nodes directly correspond to user-accessible camera settings like exposure time or gain, others serve internal purposes, such as enforcing dependencies or calculating derived values.

Hidden nodes help model relationships between different parameters, ensuring that constraints—such as valid value ranges or dependencies on other settings—are enforced. This mechanism allows for intelligent configuration handling on the host side, reducing the risk of invalid or conflicting settings and offloading complexity from the device firmware.

Namespaces

Feature names in GenApi are structured into namespaces to prevent conflicts and ensure consistency across devices. Standardized names follow the SFNC (Standard Feature Naming Convention), while vendors may introduce custom names for proprietary features. In order to fully qualify a feature name it must be prefixed with a namespace e.g. Std::Foo or Cust::Foo. Every node resides in a namespace.

Value	Description
Standard	The standard namespace is for features reside in the GenICam Standard Features Naming Convention (SFNC) document. The standard document describes the data types and behavior of the features and can be found on the EVMA website. All features in that namespace must comply with the document.
Custom	The custom namespace is for features that do not reside in the SFNC document.

Visibility

Visibility levels of nodes are primarily hints for user interfaces to determine which features should be presented to users. These levels do not affect programmatic access via the API. The visibility categories include:

Value	Description
Beginner	Basic, commonly used settings.
Expert	More advanced configuration options.
Guru	Very complex settings requiring deep technical knowledge.
Invisible	Internal nodes not meant for direct user access.

Direct Register Access

In addition to the structured node-based access provided by GenApi, direct register access is possible using port nodes. This method allows interaction with hardware registers either through a predefined (bootstrap) register or by using register addresses exposed by dedicated register nodes.

While direct register access can provide low-level control over a device, it carries inherent risks:

Device instability: Writing incorrect values to registers may leave the device in an undefined or non-functional state.
Configuration conflicts: Bypassing GenApi’s dependency management can lead to misconfigurations that violate device constraints.
Potential hardware damage: Some registers control critical device functions, and improper modification may cause permanent damage.

Due to these risks, direct register access should only be used when absolutely necessary and with thorough knowledge of the device’s register map and behavior.

C++

#include <cvb/driver/genicam_device.hpp>
#include <cvb/genapi/node_map.hpp>
 
auto nodeMap = device->NodeMap(Cvb::NodeMapID::Device);
auto registerNode = nodeMap->Node<Cvb::RegisterNode>("SpecialRegister"); // (1)
auto devicePortNode = nodeMap->Node<Cvb::PortNode>("Device"); // (2)
std::vector<uint8_t> buffer(registerNode->Length());
devicePortNode->Read(registerNode->Address(), buffer.data(), buffer.size()); // (3)

Get the address space for direct access.
Get the port node to send read and write requests.
Perform an unsafe read access.

Cvb::GenApi::PortNode

The Port node class represents a module port for register access. It is considered an invisible entity in a GUI context. In general, it would be exceptional if there was an opportunity where CVB users needed to directly work with any port node objects.

File Upload and Download

GenApi supports file-based interactions, allowing firmware updates or configuration uploads and downloads directly through the API. This is particularly useful for storing camera settings or loading calibration data.

C++

#include <cvb/driver/genicam_device.hpp>
#include <cvb/genapi/node_map.hpp>
 
auto nodeMap = device->NodeMap(Cvb::NodeMapID::Device);
for(const auto& fileName : nodeMap->AvailableFiles())
  nodeMap->DownloadFile("./"s + fileName, fileName);

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
using Stemmer.Cvb.GenApi;
 
var nodeMap = device.NodeMaps[NodeMapNames.Device]; 
foreach (string fileName in nodeMap.GetAvailableFiles())
    nodeMap.DownloadFile("./" + fileName. fileName);

Python

import cvb
 
node_map = device.node_maps[cvb.NodeMapID.Device]
for file_name in node_map.available_files:
  node_map.download_file(f"./{file_name}", file_name)

Updating Camera Firmware

CVB offers a tool that updates the camera firmware based on the standard called FWUpdate. If a targeting camera is compliant with the standard and you have a camera fimware file that is also compliant with the standard, you can update the camera firmware using a console application program called FWUpdater. FWUpdater can be found in the following directories:

%CVB%Hardware\StemmerImaging\Utilities (Windows)
/opt/cvb/bin (Linux)

In addition FWUpdater also offers firmware updates through simple file uploads if supported by the camera.

Table of Contents