Getting Started with Plug-in Development

This page provides startup help for developing communication plug-ins for the use with the process integration mode of MERLIC. If you develop a communication plug-in for the first time or if you are not sure how to start, you can use this guide to get information about the first steps and the general workflow for the plug-in development.

The easiest way to develop a custom communication plug-in is to use one of the provided example plug-ins as a basis and customize it as required to your use case. The following sections describe the general workflow for this including how to test the plug-in during the development.

Using an Example Plug-in as Basis

Customizing the Code of the Plug-in

Testing the Plug-in

Using an Example Plug-in as Basis for a Custom Plug-in

You can use one of our example communication plug-ins as basis for your plug-in and customize the existing code as required. This way, you do not have to start from scratch and save a lot of time.

1. Go to the example directory of the communication plug-ins. It is located in the subdirectory "examples\communication_plugins" within the MERLIC installation directory. For example:
   • Windows installation for all users: "%PROGRAMFILES%\MVTec\MERLIC-26.03\examples\communication_plugins"
   • Windows installation for the current user: "%LOCALAPPDATA%\Programs\MVTec\MERLIC-26.03\examples\communication_plugins"
   • Linux: "<INSTALLATION_DIR>/merlic_26.03.0/examples/communication_plugins"
2. Copy the folder of example plug-in you want to use as basis, for example, "event-logger".
3. Rename the .cpp file of the example plug-in, for example, "event-logger.cpp".
4. Adjust the respective "CMakeList.txt" file:
   • File name of the .cpp file
   • Name of the target
   • (Description)
5. Check if all includes required for your plug-in are defined. For communication plug-ins, the following includes are mandatory:

   #include <mvtec/plugin/mv_plugin_api_v2.h>
   #include <mvtec/plugin/mv_version.h>

6. Start to customize the .cpp file as described in the following sections.

Customizing the Code of the Plug-in

API Functions of the Plug-in

Check the implementation of the plug-in functions in your plug-in. Some of the functions are required for each communication plug-in:

• MVInfo
• MVInit_V2
• MVOpen
• MVClose
• MVStart
• MVStop

As these functions are mandatory, you can already find an implementation of them in your copied plug-in. You just need to customize the code for your plug-in.

There are also some optional functions:

• MVExpose
• MVValidate

These are required if you want to define plug-in parameters that can be configured via the graphical user interface of the MERLIC Runtime Environment Setup (MERLIC RTE Setup), and if you want to provide a proper validation of the parameter changes.

Adjusting the Functions for a Custom Plug-in

Expand the following drop-down sections to get more detailed information about the function declarations and individual functions that are required for each communication plug-in. The sections show the respective code excerpts based on the example plug-in "event-logger" and describe which parts of the code need to be customized when developing your plug-in. The drop-down sections for the optional functions also give more detailed information about their basic structure and for which use cases they should be implemented.

See also the page Life Cycle of a Plug-in Instance for specific information about the life cycle of a plug-in instance, especially regarding the implementation and use of the plug-in API functions MVStart, MVStop, MVOpen, and MVClose. You can get information how to ensure that your plug-in is valid and compatible for the use with MERLIC. It also contains information about the internal processes when starting MERLIC RTE and describes the steps that are performed when an instance of a plug-in is used, for example, which functions are called for certain situations.

Required function declarations

Make sure to keep the following function declarations for the API functions symbols, which are expected to be present in the plug-in shared library, in your .cpp file. They are required for each communication plug-in.

extern "C" MVUserExport MVCode_t MVInfo(MVPluginInfo_t* pMVInfo);
extern "C" MVUserExport MVCode_t MVInit_V2(MVClass_V2_t* MVClass);

If the plug-in is written in a language different from C, these functions need to be given C linkage, for example, by marking them as extern "C" in the case of plug-ins written in C++. All further API functions do not need to have C linkage as the MVInit_V2 function is expected to set up pointers to the appropriate functions.

MVInfo and MVInit_V2

MVInfo

In MVInfo, you just have to set the capability of the plug-in, that is, the value of the placeholder <CAPABILITY> in the code. You can choose between "monitor", "control" or both capabilities:

• eMVCapabilities_Monitor
• eMVCapabilities_Control
• eMVCapabilities_Monitor | eMVCapabilities_Control

Plug-ins with the "monitor" capability can receive "events" that are provided by MERLIC whereas plug-ins with the "control" capability are allowed to send actions to MERLIC using either the MV_QueueAction() or MV_QueueAction_WithInfo() function. If you want to allow your plug-in to receive "events" and send "actions", you have to set the capability to "eMVCapabilities_Monitor | eMVCapabilities_Control".

Define the capability of the plug-in:

MVCode_t MVInfo(MVPluginInfo_t* pMVInfo)
{
  pMVInfo->ApiMajor = MV_API_MAJOR;
  pMVInfo->ApiMinor = MV_API_MINOR;
  pMVInfo->ApiPatch = MV_API_PATCH;
 
  pMVInfo->Flags = <CAPABILITY>;
  return MV_CODE_OK;
}

MVInit_V2

In MVInit_V2, you have to set the function pointers to the remaining plug-in API functions to make them known to MERLIC RTE. In our example plug-ins, the mandatory plug-in functions MVOpen, MVStart, MVStop, and MVClose are used. In addition, the function pointers to the optional functions MVExpose and MVValidate are set in MVInit_V2.

To customize the MVInit_V2 function for your plug-in, it is sufficient to set up the pointers for the optional functions MVExpose and MVValidate depending on whether you want to implement the respective function or not. The function MVExpose is required if you want to define parameters for the plug-in and to enable the configuration of your plug-in parameters via the MERLIC RTE Setup. The function MVValidate is required if you also want to provide a proper validation of the parameter changes. Please see also the sections for MVExpose and MVValidate for more information.

Set up MVExpose and MVValidate functions:

MVCode_t MVInit_V2(MVClass_V2_t* MVClass)
{
  MVClass->MVOpen     = MVOpen;
  MVClass->MVStart    = MVStart;
  MVClass->MVStop     = MVStop;
  MVClass->MVClose    = MVClose;
  MVClass->MVExpose   = <nullptr|MVExpose>;
  MVClass->MVValidate = <nullptr|MVValidate>;
  return MV_CODE_OK;
}

It is possible to use arbitrary names for the functions. However, you have to make sure to set up the function pointer members of the MVClass_V2_t data structure accordingly as shown in the example code below:

Example: Set up the functions with arbitrary names

MVCode_t MVInit_V2(MVClass_V2_t* MVClass)
{
  MVClass->MVOpen     = OpenPlugin;
  MVClass->MVStart    = StartPlugin;
  MVClass->MVStop     = StopPlugin;
  MVClass->MVClose    = ClosePlugin;
  MVClass->MVExpose   = ExposeConfiguration;
  MVClass->MVValidate = ValidateChanges;
  return MV_CODE_OK;
}

The name of the MVInit_V2 function indicates the major version number of the API that is used for the plug-in development. This mechanism allows a plug-in to support multiple, otherwise incompatible, major versions of the API in the future by implementing MVInit_Vx for each supported major version and setting up the function pointers to either the same or different implementations as required.

MVOpen and MVClose

MVOpen

In MVOpen, a "user data" structure can be created which aggregates the collective state of one plug-in instance. The use of such a user data structure is the recommended way to ensure that the plug-in can manage some internal state which is then accessed and modified by each of the plug-in API functions as well as any additional threads that the plug-in might create. Typically, the data structure can be allocated in MVOpen and is then associated with the plug-in handle via MV_Plugin_SetUserData() to make sure that it is available for the entire existence of the plug-in instance. The pointer to the user data can then be retrieved from the plug-in handle in each of the other plug-in API functions via MV_Plugin_GetUserData(), for example, in MVClose to free up the memory again.

Using the user data mechanism ensures that the same plug-in can be instantiated multiple times and that the internal state of the plug-in instances does not interfere with one another as would be the case if globals or singletons were used instead. In case global state cannot be avoided due to requirements from third-party dependencies and a plug-in cannot be instantiated safely multiple times, it is recommended to detect a repeated instantiation and return from MVOpen with a return code which is different from MV_CODE_OK.

If there are no restrictions that keep you from using this user data mechanism, you can customize the functions of the example plug-in by adjusting the type of the user data structure as required. In our example plug-ins, the pointer to the user data is called *ud.

Adjust the user data struct:

static MVCode_t MVOpen(MVPlugin_t handle)
{
  // Create the user data struct
  <USER_DATA_STRUCT_TYPE>* ud = new <USER_DATA_STRUCT_TYPE>;
 
  // ...and associate it with the plug-in handle.
  if (MV_Plugin_SetUserData(handle, static_cast<void*>(ud))
      != MV_CODE_OK)
    return MV_CODE_INTERNAL_ERROR;
 
  return MV_CODE_OK;
}

MVClose

In MVClose, the pointer to the user data is retrieved to free up the memory again. For this, you have to adjust the data type for the user data pointer as defined in MVOpen.

Adjust the user data struct:

static MVCode_t MVClose(MVPlugin_t handle)
{
  // Retrieve the pointer to the user data from the plug-in handle and
  // free up the memory.
  <USER_DATA_STRUCT_TYPE>* ud = nullptr;
 
  if (MV_Plugin_GetUserData(handle, reinterpret_cast<void**>(&ud)) != MV_CODE_OK)
    return MV_CODE_INTERNAL_ERROR;
 
  delete ud;
 
  return MV_CODE_OK;
}

MVStart and MVStop

MVStart and MVStop are invoked when a plug-in instance is started and stopped, respectively. In between, the plug-in is considered to be running and is allowed to queue actions (in case of "control" capability) and to receive events (in case of the "monitor" capability). The same plug-in may be started and stopped multiple times and its configuration may be changed while it is not running. Hence, MVStart is typically the place where you can read the configuration options using MV_Plugin_GetConfig() and MV_PluginConfig_GetUserParameter().

MVStart

To access the internal state of the plug-in instance, you can recall the pointer to the user data. In the code snippet below, it is called *ud. You can then use and modify the field of <USER_DATA_STRUCT_TYPE> in the custom implementation.

In addition, you can remove the code that defines how the example plug-in reacts to "events" (in case, you are using the "event-logger" plug-in as basis) and add the desired implementation of your custom plug-in instead.

In the implementation of your plug-in, the plug-in should be able to process events as fast as MERLIC is sending them and must be able to handle dropped events. If a plug-in is processing events slower than MERLIC is sending them, events are queued which 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. Therefore, this issue should already be considered during the development of the plug-in.

Adjust the user data struct and insert your code:

static MVCode_t MVStart(MVPlugin_t handle)
{
  // Retrieve the pointer to the user data from the plug-in handle.
  <USER_DATA_STRUCT_TYPE>* ud = nullptr;
  if (MV_Plugin_GetUserData(handle, reinterpret_cast<void**>(&ud)) != MV_CODE_OK)
    return MV_CODE_INTERNAL_ERROR;
 
   // Start the event thread and store its handle in the user data struct.
  ud->mEventThread = std::thread([handle] {
    bool stop_event_thread = false;
    while (!stop_event_thread)
    {
      MVEvent_t event;
      MVCode_t  status = MV_TryGetEvent(handle, MV_TIME_INFINITE, &event);
 
      // Insert your implementation here
 
      MV_Event_Clear(&event);
    } // end event polling thread
 
  });
  return MV_CODE_OK;
}

For plug-ins with the capability eMVCapabilities_Monitor, that is, plug-ins that handle "events", it is quite typical to use the user data to store the handle to a thread which continuously polls for new events, that is, an "event loop". In order to be able to terminate such an event loop thread again, a special event of type eMVEvent_Shutdown will be enqueued when a plug-in is stopped. This guarantees to be the last event that the plug-in will receive before it is restarted and thus it is possible to break out of the event loop at that point.

In the "event-logger" example, this is done by setting "stop_event_thread" to "true":

Terminate the event loop in case of the Shutdown event:

case eMVEvent_Shutdown:
{
    MV_Log(handle, eMVSeverity_Info, format_msg("Event '%s' received; terminating event loop.", EventToString(event_type)));
    stop_event_thread = true;
    break;
}

MVStop

In case an event loop thread has been started in MVStart, you have to join that thread again in MVStop. MVStop is called by MERLIC RTE at the same time the Shutdown event is enqueued, so there is no need to take any additional action to stop the thread. In case your plug-in manages additional resources from third-party libraries, such as an I/O context or a database connection, it may be necessary to terminate those explicitly in MVStop.

Adjust the type of the user data struct:

static MVCode_t MVStop(MVPlugin_t handle)
{
  // Retrieve the pointer to the user data from the plug-in handle.
  <USER_DATA_STRUCT_TYPE>* ud = nullptr;
  if (MV_Plugin_GetUserData(handle, reinterpret_cast<void**>(&ud)) != MV_CODE_OK)
    return MV_CODE_INTERNAL_ERROR;
 
  // Rejoin the event thread. It should be in the process of terminating after
  // having received the shutdown event.
  if (ud->mEventThread.joinable())
    ud->mEventThread.join();
  return MV_CODE_OK;
}

MVExpose and MVValidate

MVExpose

This function must be implemented if you want to define parameters for the plug-in and enable the configuration of these parameters via the graphical user interface of the MERLIC RTE Setup.

You have to define the set of plug-in parameters and their meta data ("user parameter description") for the configuration and use the family of MV_PluginUserParameterDescription_*() API functions to expose the user parameter description. If only predefined values should be allowed for the parameters, you also have to impose the required constraints via MV_PluginUserParameterDescription_ImposeConstraint().

This function is optional. However, if it is not implemented, the configuration of the plug-in is not possible, neither via the MERLIC RTE Setup nor manually via JSON files because no parameters have been defined for the plug-in.

Define the user parameter description:

static MVCode_t MVExpose(MVPlugin_t, MVPluginConfig_t, MVPluginUserParameterDescription_t)
{
  // Insert your implementation here
 
  return MV_CODE_OK;
}

MVValidate

This function can be implemented if you want to provide a validation for more complex cases of parameter changes that are made in the MERLIC RTE Setup, for example, if the allowed value range of a parameter depends on other parameter values. MVValidate also enables you to provide feedback to the user about the state of the parameters, for example, to highlight invalid user parameter values or show specific error messages. This data structure is called "validation result".

For the implementation, you have to use the API functions MV_PluginConfig_* and MV_PluginConfigValidation_*.

Implement the validation of parameter changes and feedback of the parameter state:

static MVCode_t MVValidate(MVPlugin_t, MVPluginConfig_t, MVPluginConfigValidation_t)
{
  // Insert your implementation here
 
  return MV_CODE_OK;
}

While adjusting the implementation for your communication plug-in, you may want to test the plug-in from time to time as described in the following sections.

Testing the Plug-in

If you want to test your plug-in during the implementation, you have to build the plug-in and make sure that it is available for MERLIC RTE.

1. Build the communication plug-in. For detailed information on building plug-ins, see Building a Plug-in.
2. Make sure that the name of the plug-in library begins with the prefix "pMV" prefix as described in Providing the Plug-ins for MERLIC RTE.
3. Start the plug-in to test the implementation. You have the following options to start the plug-in:
   • Using the command line
   • Using the MERLIC RTE Setup

Testing the Plug-in via Command Line

MERLIC provides the executable "merlic_communication_plugin_host.exe" which can be used for testing purposes during the plug-in development. This executable starts the same process that is also started internally as a subprocess of MERLIC RTE when adding a communication plug-in in the MERLIC RTE Setup. It serves as a host process for a specific instance of a communication plug-in. Each plug-in instance that is added in MERLIC RTE Setup, is executed in its own host process.

The manual use of this executable is only intended for testing purposes during the development of communication plug-ins to enable a quick feedback loop when iterating on the code of the plug-in. The executable file is not intended to be started manually in productive use.

You can find the "merlic_communication_plugin_host.exe" executable next to the other MERLIC executable files in the MERLIC installation directory. On Windows system, they are installed by default in the subdirectoy "bin\x64-win64". On Linux systems, the executable files are installed in the subdirectory "x64-linux" or "aarch64-linux", respectively.

To start the host process for a plug-in, use the executable in combination with the command line options "--plugin" or "-p", respectively, and "--plugin_dir":

merlic_communication_plugin_host.exe --plugin <PLUGIN_NAME> --plugin_dir <PLUGIN_BUILD_OUTPUT_FOLDER>

Make sure to specify the directory in which the current build output of your custom plug-in is located. When starting the host process for a plug-in, the current configuration of the plug-in will be written to the standard output.

Example

The following Windows command line starts a host process which attempts to load the plug-in library at "C:\Users\Public\Documents\MVTec\MERLIC\Custom_plugins\pMVmy_custom_plugin.dll":

merlic_communication_plugin_host.exe --plugin my_custom_plugin --plugin_dir C:\Users\Public\Documents\MVTec\MERLIC\Custom_plugins

Restrictions
When using the "merlic_communication_plugin_host.exe" executable to test the plug-in, the following information and restrictions should be considered:

• The executable only starts executing the specified communication plug-in. MERLIC RTE is not started. If you want to test any commands that require the communication with the vision system, you have to start a MERLIC RTE process or test via the MERLIC RTE Setup in the usual way.
• It is not possible to stop and restart the plug-in.

Available Command Line Options

For "merlic_communication_plugin_host.exe", the following command line options are available:

Command line option	Description
-h, --help	Get help for the available command line options and arguments.
-V, --version	Display the MERLIC version.
-l, --available_plugins	Display the list of available plug-ins. MERLIC searches for dynamic libraries with files prefix "pMV" within the specified plug-in directories.
-p, --plugin	Name of the plug-in to be registered. The corresponding plug-in library will be loaded and the plug-in will be started using its default configuration.
--plugin-dir	Defines the directory where to search for the plug-in library. By default, the directory containing the executable is searched.
-d, --log-level	The log level for the plug-in. The default log level is "debug". The available options are "debug", "info", "warning", "error", and "critical".
-o, --override <KEY>=<VALUE>	Override the default value of a configuration option. <KEY> must correspond to one of the plug-in's user parameters. <Value> is parsed as the corresponding data type. This option can be specified multiple times to override multiple parameters.
--command_timeout	Set the duration in milliseconds after which a pending command to the vision system will time out. The default is 5 seconds. A negative value indicates that pending commands should block indefinitely.
--command_port	Defines the port that is used for commands when using MERLIC RTE. It is set to 21591 by default.
--event_port	Defines the port that is used for "events" when using MERLIC RTE. It is set to 21590 by default.

Testing the Plug-in in MERLIC RTE Setup

If you want to test the communication between your plug-in and MERLIC RTE, or if you implemented the MVExpose and MVValidate functions for your plug-in and want to test the plug-in configuration and validation, you can test the plug-in in the MERLIC RTE Setup. In this case, you have to proceed in the same way as a MERLIC user with the final communication plug-in. This also implies that you have to ensure the plug-in is available for MERLIC RTE as described in Providing the Plug-ins for MERLIC RTE:

• The plug-in library must be located in the specified plug-in directory.
• The name of the plug-in library must begin with the prefix "pMV".

If these prerequisites are fulfilled, you can start testing in the MERLIC RTE Setup:

1. Open the MERLIC RTE Setup.
2. Start MERLIC RTE.
3. Add an instance of your communication plug-in in the "Communication" tab.
4. Adjust and test the configuration of the plug-in.
5. Start and stop the plug-in as required for testing.

For more information on working with communication plug-ins in the MERLIC RTE Setup, see the MERLIC Manual.

When you are finished implementing your communication plug-in, make sure to provide the plug-in library as described in Providing the Plug-ins for MERLIC RTE.

Logging

The logging information for communication plug-ins is written to the log file of MERLIC RTE. By default, the log files are written to the directory "%LOCALAPPDATA%\MVTec\MERLIC\" (on Windows systems) and "~/.local/share/MVTec/MERLIC/" (on Linux systems). The log file for MERLIC RTE begins with the prefix "merlic_rte_".

When adding a plug-in in the MERLIC RTE Setup, the log level of the plug-in is set to the log level of the respective MERLIC RTE process by default. In some cases, the log levels might differ, for example, if MERLIC RTE is stopped and restarted with a different log level. In this case, the log level of the plug-in instance that was added in the previous session is still set to the same log level as before.

If the log level of a plug-in instance differs from the log level of MERLIC RTE, the plug-in instance will only be able to use its log level in the following case: the log level of MERLIC RTE is lower or the same as the log level of the plug-in instance.

This behavior should be considered for use cases in which the log levels might differ. For example, if the plug-in was added with "debug" log level while MERLIC RTE uses the higher log level "info". In this case, only messages of log level "info" will be logged for the plug-in instance.