Introduction

The Hardware Abstraction Layer allows you to operate event-based cameras and access their features in a hardware-agnostic way.

An event-based camera is represented by an instance of the Metavision::Device class, which is the entry point to access all camera capabilities using the facilities.

As a front-end for the application, the HAL library provides:

• the ability to discover connected devices by:

  • listing serial numbers of compatible devices

  • opening a live camera from a chosen serial number or manufacturer

• the ability to replay pre-recorded RAW file

• the ability to operate live or pre-recorded data streams in a unified way by:

  • controlling the start and stop of the streaming

  • decoding information coming from the stream

  • accessing device information through facilities (e.g. Metavision::I_Geometry or Metavision::I_HW_Identification)

  • controlling hardware features through facilities (e.g. Metavision::I_ROI or Metavision::I_LL_Biases)

The purpose of this hardware-agnostic API is to enable operating several event-based cameras from a unified API. This makes it much easier:

• for camera manufacturers to integrate with existing event-based applications

• for application developers to support different devices

The dynamic plugin-based architecture of Metavision HAL enables an easy integration of event-based camera drivers with the Metavision SDK, while enabling each camera manufacturer to make different system integration choices, e.g. for the board communication using protocols like USB, MIPI, Ethernet, etc. This can be achieved by implementing the camera driver in the form of a plugin, i.e. a shared library providing the right entry points and implementations for the HAL facilities. This dynamic plugin-based architecture hence enables an easier isolation of driver implementations while allowing applications to support new devices without recompiling.

The following sections describes in more details the device discovery mechanism and the support of RAW files.

Discover Devices

As mentioned above, the communication with a camera device is handled by the plugin itself, hence the first step is to load the relevant plugin.

Metavision HAL plugins are searched in the following folders (listed by order of priority):

• the folder list provided by the environment variable MV_HAL_PLUGIN_PATH (note that folders are separated by ‘:’ under Unix and ‘;’ under Microsoft environment)

• <install-prefix>/lib/metavision/hal/plugins/ (i.e. /usr/lib/metavision/hal/plugins/ by default on Ubuntu OS)

Note

The folders in which plugins are searched for can be customized with the environment variable MV_HAL_PLUGIN_SEARCH_MODE as explained in the Camera Plugins Installation page.

Every shared library in these folders is considered as a potential plugin, but only those with the required entry points will be recognized as plugins.

Note

In case a plugin in MV_HAL_PLUGIN_PATH or in the installation path is not loaded properly, setting the environment variable MV_HAL_DEBUG_PLUGIN will provide more information about which libraries Metavision HAL tried to load and why the loading failed.

To list the connected devices, every recognized plugin is first interrogated about the connected devices that it can handle. Each plugin returns the list of device IDs for compatible devices. Since a given device ID could be supported by several plugins, the enumerated raw device IDs are prefixed by the HAL with the integrator’s (i.e. manufacturer) name and plugin’s name to build a unique serial number in the form of IntegratorName:PluginName:DeviceID. The plugin’s name is deduced from the name of the corresponding shared library by removing the “lib” prefix and the file extension.

In practice, a device can be opened using the function Metavision::DeviceDiscovery::open(), by providing a serial number in the following forms:

• Empty String: this will use the first available plugin compatible with a connected device

• DeviceID: this will open the specified device using the first compatible plugin

• Name:DeviceID: this will open the specified device using the first plugin with matching Integrator or Plugin name

• IntegratorName:PluginName:DeviceID: this will open the specified device ID using the specified plugin. The fields IntegratorName or PluginName can be empty, and if so, are ignored.

The first plugin that fulfills the requirements of the Integrator’s name and the Plugin’s name and that is able to open the DeviceID is used to open the device.

Also, the camera initialization can be customized by providing a configuration structure to the Metavision::DeviceDiscovery::open() function.

Note

One camera device may be supported by several plugins, thus you may want to specify the plugin to be used by Integrator or Plugin name.

See also

See our HAL samples showing how to discover and open devices.

Data Recording to RAW files

While a device is streaming, the RAW stream can be recorded to a file as shown in the metavision_hal_showcase sample.

To replay a RAW file, the function Metavision::DeviceDiscovery::open_raw_file() creates a Metavision::Device instance able to stream data from the RAW file and behaving similarly to a live device, but with the hardware control features disabled (e.g. biases, etc).

Every RAW file contains a header with information about the actual device and plugin that generated it. See details about the RAW formats.

Similarly than the real device, the Metavision::DeviceDiscovery::open_raw_file() function iterates over all the available plugins to find one that is able to read and decode the data from the file. The first one found to be compatible is used.