Starting the Communicator and Plug-ins

There are different ways to start the Communicator, a Communicator plug-in, and the process integration mode of MERLIC, i.e. MERLIC RTE MERLIC RTE (Runtime Environment) is the name of the application that is used to start MERLIC in process integration mode. It can be started either via the Windows start menu or via the command line with the executable "merlic_rte.exe".. You can start the Communicator on its own or together with a Communicator plug-in. It is also possible to start the Communicator and MERLIC RTE in one step.

To start a Communicator plug-in, the Communicator itself must already be running. Therefore, if you start the plug-in separately from the Communicator, you have to make sure that the Communicator is already running. Otherwise, the plug-in cannot be started. Provided that the Communicator is running, a plug-in can be started and stopped at any time, regardless if MERLIC RTE is running unless stated otherwise in the plug-in. If the Communicator is running, you can also access the configuration of a plug-in in the MERLIC RTE Setup. For more information on the configuration in the MERLIC RTE Setup, see the topic Configuring Communicator Plug-ins. Beside the configuration of Communicator plug-ins, you can also start and stop the plug-ins in the MERLIC RTE Setup.

The following sections describe the different ways to start and stop the Communicator, Communicator plug-ins, and MERLIC in process integration mode.

Starting the Communicator

The following sections describe the different ways to start the Communicator. The easiest way is to use the Windows start menu. However, in some cases it might be useful to start the Communicator via the command line and make use of the available command line options.

If you want to start the Communicator with specific settings, e.g., the used ports, you can either set these in an .ini file or with command line options. For more information, see the topic Changing Communicator and Plug-in Settings.

Starting the Communicator via the Windows Start Menu
  1. Open the Windows start menu.
  2. Navigate to "MVTec MERLIC 5.6 > MERLIC 5.6 Communicator" to start the Communicator.
Starting the Communicator from the Command Line

To start the Communicator via the command line, change to the "bin\x64-win64" directory within the MERLIC installation and use the following command:

Copy 
merlic_communicator.exe

This command starts the Communicator without any plug-in. To start a plug-in with the Communicator, you can use the "--plugin" option as described in the section Starting the Plug-in from the Command Line.

There are also some further command line options available that enable you to set specific settings for the Communicator. They are described in detail in the drop-down menu below. See also the topic Changing Communicator and Plug-in Settings for more information on how to define specific settings for the Communicator

Command line option

Description

--help, -h

Displays the MERLIC Communicator command line options.

--ini

Set the full path and file name of the .ini file that is used for the configuration of the Communicator.

--version, -v

Displays the MERLIC Communicator version.

--available_plugins, -l

Displays the names of compatible plug-ins found in the plug-in directory that contain the prefix pMV in their file name, e.g., pMVevent-logger.dll → event-logger. All dynamic libraries inside the plug-in directory are checked for compatibility. Enable the log level "debug" for more information about the reasons why additional .dll files in the folder were not accepted as plug-ins. Plug-ins that are given only by their name and not by the absolute path are interpreted relative to the plug-in directory.

--log-level, -d

Defines the used log level for the plug-in and the messages from the Communicator. The default log level is "info". With this option you can set a global log level and individual log levels for each plug-in. In contrast, with the flag "d:" after the option "--plugin" you can only set log levels for individual plug-ins. For more information see the section Defining the Log Level in the topic Changing Communicator and Plug-in Settings.

--plugin, -p

Defines the following options for the plug-in to be started. When using this option to start a plug-in, some side effects and restrictions occur that should be considered. See the section Side effects and restrictions more information.

  • Name

    The plug-in name is the name of the dynamic library to be loaded without a prefix. It must be entered and provided before any other options of the plug-in.

    Example:

    Copy 
    merlic_communicator.exe --plugin event-logger

    merlic_communicator.exe --plugin event-logger

  • Log level, d:

    To define the global log level, use the option "--log-level" or "-d" followed by the desired value. The default log level is "info". The available options are "debug", "info", "warning", "error", and "critical". To specify a different log level for a plug-in you can provide the desired level prefixed by "d:".

    Example:

    Copy 
    merlic_communicator.exe --plugin event-logger d:debug

    merlic_communicator.exe --plugin event-logger d:debug

    For more information see the section Defining the Log Level in the topic Changing Communicator and Plug-in Settings.

  • Access, a:

    The access level correlates with the capabilities that are defined for the plug-in in the function MVInfo. If the capability eMVCapabilities_MonitorAndControl ("monitor and control") has been set for a plug-in, you have the possibility to use this flag to restrict the access level of the plug-in to only "monitor" or "control".

    Example:

    Copy 
    merlic_communicator.exe --plugin OPC_UA a:monitor

    merlic_communicator.exe --plugin OPC_UA a:monitor

--plugin_dir

Defines the plug-in directory. This directory is used to store the plug-in files. The default plug-in directory is "%PROGRAMFILES%\MVTec\MERLIC-5.6\bin\x64-win64" if MERLIC was installed with administrator rights, otherwise "%LOCALAPPDATA%\Programs\MVTec\MERLIC-5.6\bin\x64-win64". It is also possible to define multiple plug-in directories as a semicolon-separated list. For more information see the section Changing the Plug-in Directory in the topic Changing Communicator and Plug-in Settings.

--config_dir

Defines the configuration directory. This directory is used to store the JSON configuration files for the plug-ins.

The default configuration directory is the standard configuration location of your system, e.g., "%AppData%/MVTec/Communicator/conf" on Windows.

For more information see the section Changing the Configuration Directory in the topic Changing Communicator and Plug-in Settings.

--command_timeout

Defines the duration for a command timeout. A pending command to the vision system will time out after the defined duration. The default duration is 5000 milliseconds. If you want to disable the timeout, enter a negative number.

--command_port

Defines the port that is used for commands, e.g., "actions". For more information see the section Defining the Ports in the topic Changing Communicator and Plug-in Settings.

--event_port

Defines the port that is used for "events". For more information see the section Defining the Ports in the topic Changing Communicator and Plug-in Settings.

--plugin_config_ports

Defines the ports that are opened by the Communicator to allow the configuration of plug-ins. If this option is used, only one instance of the Communicator can be started. For more information, see the description of the respective configuration property PluginConfigurationPorts.

Starting the Process Integration Mode with the Communicator

You can also start the process integration mode, i.e., MERLIC RTE, and the Communicator in one step either via the Windows start menu or via the command line. In some cases it might be useful to use the command line and make use of the available command line options, e.g., if you want to use specific ports.

Starting MERLIC RTE and the Communicator in One Step via the Windows Start Menu
  1. Open the Windows start menu.
  2. Navigate to "MVTec MERLIC 5.6 > MERLIC 5.6 RTE with Frontend + Communicator" to start MERLIC RTE, the respective Frontend, and the Communicator.
Starting MERLIC RTE and the Communicator in One Step via the Command Line

To start MERLIC RTE and the Communicator via the command line, change to the "bin\x64-win64" directory of the MERLIC installation and start MERLIC RTE, i.e., "merlic_rte.exe", with the command line option "--communicator" or "-c".

Copy 
merlic_rte.exe --communicator

If you also want to start the respective Frontend, you can add the command line option "--frontend" or "-f". This would be equivalent to the option via the Windows start menu.

For more information about how to start MERLIC RTE and the available command line options, see the topic Starting the Process Integration Mode in the MERLIC manual.

If you want to change default settings for MERLIC RTE, e.g., the used ports, you can use the .ini file for MERLIC (MERLIC5.ini) to set the desired values. When starting MERLIC process integration via the start menu, the settings in the MERLIC5.ini file will be used. For more information about the MERLIC5.ini file, see the topic The MERLIC .ini File in the MERLIC manual.

If you start the Communicator and MERLIC RTE via the command line and define the ports for "events" and commands with the command line options "--event_port" and "--command_port", you have to make sure that the port settings of "merlic_rte.exe" and "merlic_communicator.exe" match to establish a connection.

Starting and Stopping a Communicator Plug-in

You can start a Communicator plug-in in the "Communication" tab of the MERLIC RTE Setup and via the command line. In the MERLIC RTE Setup, you can also access the configuration of a plug-in instance. If you change the configuration, you can immediately start the plug-in from the MERLIC RTE Setup.

Starting the Plug-in in the MERLIC RTE Setup
  • Select the desired plug-in from the list of plug-in instances on the left side and click on the button " Start plug-in" at the bottom of the MERLIC RTE Setup.
  • Alternatively, you can use the menu of the respective plug-in instance.

To get more detailed information about how to start and stop a Communicator plug-in in the MERLIC RTE Setup, see the topic Starting and Stopping Communicator Plug-ins in the MERLIC manual.

Starting the Plug-in from the Command Line

To start one or multiple plug-ins with the Communicator, change to the "bin\x64-win64" directory within the MERLIC installation and use the following command:

Copy 
merlic_communicator.exe --plugin <NAME1> [--plugin <NAME2> ...]

The Communicator will be started and the plug-in will be loaded and started automatically. For more information on the available command line options for "merlic_communicator.exe", see the section Starting the Communicator from the Command Line.

When starting the plug-in via the command line, some side effects and restrictions need to be considered. Therefore, we recommend to start the plug-in in the "Communication" tab of the MERLIC RTE Setup.

  • Configuration:
    • The plug-in is loaded and started with its default configuration.
    • Any changes to the plug-in configuration will be lost. The changes are not saved in the respective JSON configuration file of the plug-in.
    • If you want to save the changes in your configuration, you need to use the command line option "--config_dir" to define the location for the configuration file for this particular plug-in instance. However, it is recommended to specify a location different from the existing ones to avoid that previous configurations of the plug-in are overwritten.
  • State of the plug-in:
    • The plug-in is automatically started even if the "--config_dir" option is used and the last state of the respective plug-in was "not running".
Stopping a Communicator Plug-in

You can stop a plug-in instance in the "Communication" tab in the following ways:

  • Select the desired plug-in from the list of plug-in instances on the left side and click on the button " Stop plug-in" at the bottom of the MERLIC RTE Setup.
  • Alternatively, you can use the menu of the respective plug-in instance.

Result Format

To get information about the format in which the results are returned, see the topic Result Format in the reference documentation of the Communicator API.

Stopping the Communicator

To stop the Communicator, open the respective command shell and press "Ctrl+C". You can end and restart MERLIC or the Communicator at any time.

Stopping MERLIC While the Communicator is Running

If MERLIC is ended safely while the Communicator is still running, the respective plug-ins receive the information that MERLIC changed to the "Halted" state. When MERLIC is started again, the information about the changes of the MERLIC states are forwarded to the plug-ins via the events. The connection to the plug-ins is restored.

Stopping the Communicator While MERLIC is Running

If the Communicator is stopped while MERLIC is still running, only the plug-ins are closed. MERLIC keeps running. When the Communicator is started again, it reconnects automatically with MERLIC. The plug-ins will be reopened and are ready to receive events.

All events that are sent while the Communicator is not connected are lost. They are not stored in any way.