Prerequisites

MERLIC Installation

For the implementation of communication plug-ins, you have to install the current MERLIC version. It contains the required files for the plug-in implementation such as header files, libraries, or example plug-ins. The following sections give an overview of the files that are contained in the MERLIC installation for the plug-in 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 Plug-ins

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

The 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 Example Communication Plug-ins in the MERLIC 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 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 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_PREFIX_PATH". For more information, see Building a Plug-in.

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 and reference the API version defines in its implementation of MVInfo.

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 Life Cycle of a Plug-in Instance.

For more information about writing configurable plug-ins, see Plug-in Configuration.

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".

Required Prefix for Plug-in Names

To ensure that your plug-in 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 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. For more information on the plug-in directory, see Providing the Plug-ins for MERLIC RTE.

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.