Prerequisites

MERLIC Installation

For the implementation of communication plugins, you have to install the current MERLIC version. It contains the required files for the plugin implementation such as header files, libraries, or example plugins. The following sections give an overview of the files that are contained in the MERLIC installation for the plugin development.

Header Files

The header files are installed in the "include" directory within the MERLIC installation directory.

Libraries

The libraries are installed in the "lib" and "bin" directory within the MERLIC installation directory.

Platform	File
Linux (Arm®-based)	lib/aarch64-linux/libcommunicator.so
Linux (PC-based)	lib/x64-linux/libcommunicator.so
Windows	bin/x64-win64/communicator.dll lib/x64-win64/communicator.lib

Example Plugins

MERLIC provides various example plugins which can be used as basis for the plugin development. You can find them in the MERLIC installation directory in the following sub-directory: "examples\communication_plugins".

The example plugins are implemented in C++ 17. You have to make sure to use a compiler that supports this revision of C++. For more information about the example plugins, see Example Communication Plugins in the MERLIC Manual.

Further Prerequisites

If you want to use CMake for the implementation of a plugin, you can use the provided CMake file CommunicatorConfig.cmake to automatically set the correct paths. You can find the file in the MERLIC installation directory in the following sub-directory: "cmake". However, you have to make sure to install CMake first.

When using the provided CMake configuration file in combination with find_package, as shown below, at least version 3.0 is required. For the example plugins, CMake 3.15 or higher is required.

find_package(Communicator CONFIG REQUIRED)

When generating the makefiles for a plugin with CMake, the location of the MERLIC installation needs to be specified via the command line option "-DCMAKE_PREFIX_PATH". For more information, see Building a Plugin.

In addition, a functional C toolchain is required.

Required Specifications

Includes and Functions

A plugin should include the header mv_plugin_api_v2.h which can be found in the directory "include\mvtec\plugin" within your MERLIC installation and reference the API version defines in its implementation of MVInfo.

The following functions must be defined for the plugin:

MVInfo
MVInit_V2
MVOpen
MVStart
MVStop
MVClose

The following functions are optional:

MVDetails
MVExpose
MVValidate

The function MVDetails can be defined to add general information such as a version number of the plugin or a short description that will be displayed when adding a new plugin instance in the MERLIC RTE Setup. The functions MVExpose and MVValidate can be defined to support configurable plugins.

For more information about the roles of these functions, see Life Cycle of a Plugin Instance.

For more information about writing configurable plugins, see Plugin Configuration.

Capabilities of the Plugin

You have to define the desired capabilities of your plugin in the function MVInfo. You can choose between the following:

Capability	Description
`eMVCapabilities_Monitor`	The plugin can receive "events".
`eMVCapabilities_Control`	The plugin can send "actions".
`eMVCapabilities_Monitor \| eMVCapabilities_Control`	The plugin can send "actions" and receive "events".

Required Prefix for Plugin Names

To ensure that your plugin is recognized by MERLIC RTE, the name of the corresponding dynamic library has to start with the prefix "pMV". In the "Communication" tab of the MERLIC RTE Setup, this prefix is not shown in the names of the listed plugins but it is used to differentiate plugins from any other dynamic libraries which may be placed in the same directory as plugin dependencies. For instance, "pMVevent-logger.dll" on Windows or "pMVevent-logger.so" on Linux corresponds to the plugin named "event-logger".

The plugin library as well as any of its dependent libraries need to be placed in the designated plugin directory. For more information on the plugin directory, see Providing the Plugins for MERLIC RTE.

Synchronization Requirement for Custom Plugins

If a plugin is processing events slower than MERLIC is sending them, events are queued. This may lead to delays. If the queue is full, additional events will be dropped. This may happen if MERLIC is running in continuous mode and the plugin takes longer to process events than MERLIC needs for a single iteration, or when a plugin is triggering single executions faster than another plugin is handling the results.

MERLIC supports slower plugins, but they must be able to handle the case that events are dropped. To avoid dropping events, a custom plugin should be able to process events as fast as MERLIC is sending them.