Prerequisites

MERLIC 5.5.2 Installation

For the implementation of Communicator plug-ins, you have to install the current MERLIC version. It contains the required files for the Communicator and the plug-in implementation such as header files, libraries, or example plug-ins.

The following sections give an overview of the files for the Communicator that are contained in the MERLIC installation.

Header Files

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

Libraries

Operating system	File
Windows	lib/x64-win64/communicator.lib

Example Plug-ins

We provide various example plug-ins. They are installed in the same directory in which the MVApp examples are stored, i.e., by default in "examples\communicator_pluging\save-image" within the MERLIC installation directory.

The provided example plug-ins 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 plug-ins, see the topic "Example Plug-ins" in the Communicator Manual.

Further Prerequisites

If you want to use CMake for the implementation of a plug-in, you can use the provided CMake file CommunicatorConfig.cmake to automatically set the correct paths. You can find the file in the directory "cmake" within the MERLIC installation (e.g., "%PROGRAMFILES%\MVTec\MERLIC-5.4" if MERLIC was installed with administrator rights or "%LOCALAPPDATA%\Programs\MVTec\MERLIC-5.4" if it was installed without administrator rights). 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 plug-ins, CMake 3.15 or higher is required.

find_package(Communicator CONFIG REQUIRED)

When generating the makefiles for a plug-in with CMake, the location of the MERLIC installation needs to be specified via the command line option "-DCMAKE_INSTALL_PREFIX". See the topic "Example Plug-ins" in the Communicator Manual for an example how to generate the makefiles.

In addition, a functional C toolchain is required.

Required Specifications

Includes and Functions

A plug-in should include the header mv_plugin_api_v2.h which can be found in the directory "include/mvtec/plugin" within your MERLIC installation ( e.g., "%PROGRAMFILES%\MVTec\MERLIC-5.4") and reference the API version defines in its implementation of MVInfo.

In addition, the following functions must be defined for the plug-in:

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 plug-in or a short description that will be displayed when adding a new plug-in instance in the MERLIC RTE Setup. The functions MVExpose and MVValidate can be defined to support configurable plug-ins.

For more information about the roles of these functions, see the topic Life Cycle of a Plug-in Instance. For more information about writing configurable plug-ins, see the topic Plug-in Configuration.

Specifying the Capabilities of the Plug-in

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

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

If you define both capabilities, it is possible for the user to restrict the access level for the plug-in to only one of the capabilities when starting the plug-in via the command line. For more information on how to restrict the access level of a plug-in, see the topic "Changing Communicator and Plug-in Settings" in the Communicator Manual.

Required Prefix for Plug-in Names

To ensure that your plug-in is recognized by the Communicator, 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 plug-ins but it is used to differentiate plug-ins from any other dynamic libraries which may be placed in the same directory as plug-in dependencies. For instance, "pMVevent-logger.dll" on Windows or "pMVevent-logger.so" on Linux corresponds to the plug-in named "event-logger".

The plug-in library as well as any of its dependent libraries need to be placed in the designated plug-in directory, e.g., "%PROGRAMFILES%\MVTec\MERLIC-5.4\bin\x64-win64". For more information how to change the plug-in directory, see the topic "Changing Communicator and Plug-in Settings" in the Communicator manual.

Synchronization Requirement for Custom Plug-ins

If a plug-in 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 plug-in takes longer to process events than MERLIC needs for a single iteration, or when a plug-in is triggering single executions faster than another plug-in is handling the results.

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