Configuring the TCP Socket Plug-in

The configuration of the TCP Socket plug-in can be adjusted in the "Communication" tab of the MERLIC Runtime Environment Setup (MERLIC RTE Setup). In the "Communication" tab, you can add an instance of the plug-in, configure the parameters, and you can start and stop the plug-in directly in the user interface. For more information on the MERLIC RTE Setup, see the topic MERLIC RTE Setup in the MERLIC manual.

Enabling the Configuration in the MERLIC RTE Setup

To enable the configuration of the plug-in in the "Communication" tab of the MERLIC RTE Setup, you first have to start the MERLIC Communicator and perform the following steps:

  1. Open the MERLIC RTE Setup and go to the "Communication" tab. In case the MERLIC Communicator is not running, you can start it directly from the "Communication" tab.
  2. Add the TCP Socket plug-in to the list of plug-in instances on the left.

  3. Make sure that the plug-in is currently not running. Otherwise, the parameters are not available for the configuration. You can see the current state of the plug-in at the respective status icon in the list of plug-in instances. If the status shows the icon , the plug-in is running. In this case, you have to stop it by clicking the " Stop plug-in" button on the bottom of the MERLIC RTE Setup. If the status shows the icon instead, the plug-in is currently not running. In the example image below, the selected instance of the TCP Socket plug-in is currently not running and therefore the configuration is possible.

  4. Select the TCP Socket plug-in on the left to display its parameters and to start with the configuration.

The parameters of the selected TCP Socket plug-in are shown on the right of the "Communication" tab.

Plug-in Parameters

Parameters of this type represent general parameters for the Communicator plug-in that cannot be adjusted in the configuration area of the "Communication" tab. They may show the version number of the plug-in, the current parameter value for the log level, the access level of the plug-in, and the setting for the validation of the plug-in configuration. These values need to be set in different locations or with different methods, respectively.

Version

This parameter shows the version number that has been defined during the plug-in implementation. It consists of a major, minor, and maintenance version. It is also shown when adding a new plug-in instance. The version is optional. Therefore, it is possible that no version number has been defined during the implementation.

Log level

This parameter shows the log level that is used for the TCP Socket plug-in. By default, the log level of the Communicator is used which is "Info". This means that all types of messages of severity "critical", "error", "warning", and "info" are logged, i.e., messages for general non-critical information.

You can also set a different log level for the Communicator in general or for a specific plug-in instance only. For more information, see the section Starting a Plug-in with a Specific Log Level in the topic Starting and Stopping Plug-ins of the MERLIC manual.

Access level

This parameter shows the access level that is set for the plug-in. For the TCP Socket plug-in, the access level is set to "monitor and control" by default. This means that the plug-in can receive "events" and send "actions". The access level correlates with the capability that is defined in the implementation of the plug-in. The implemented capability cannot be adjusted in the MERLIC RTE Setup. However, it is possible to restrict the access level of the plug-in to only "monitor" or "control".For more information, see the topic Changing Communicator and Plug-in Settings in the MERLIC Communicator manual.

Supports rapid validation

This parameter shows whether the plug-in supports the immediate validation of the current plug-in configuration. For this plug-in, the check box is ticked indicating that "rapid validation" is supported. This means that the configuration of the plug-in is validated with each modification of any editable parameter in the "Communication" tab of the MERLIC RTE Setup. If the plug-in does not support "rapid validation", the configuration of the plug-in is validated only when saving the configuration.

User Parameters

The "User parameters" represent the set of parameters that can be configured for the plug-in. They are displayed in different categories which can be expanded or closed.

The following sections describe the parameters for each category.

General

The parameters in this category define general settings with respect to the connections and the messages.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Port

This parameter defines the port on which the plug-in operates. By default, the parameter is set to 65433.

Limit number of simultaneous connections

This parameter defines whether the number of allowed connections is restricted to the value defined in the parameter "Maximum number of connections". By default, the parameter is not set which means that there is no restriction on how many connections are allowed.

Maximum number of connections

This parameter enables you to define how many connections are allowed. By default, it is set to 10. The parameter is only available if the parameter "Limit number of simultaneous connections" is set. Otherwise, it has no effect.

Allowed IP address

This parameter defines the IP address from which a connection to the plug-in is possible. By default, it is set to "0.0.0.0" which means that connections from all IPv4 addresses are allowed. If you want to allow the connection only from a specific system, you have to set the parameter to the respective IP address. If the IP address is set to "127.0.0.1", only connections from the system on which the Communicator is running are allowed.

The parameter supports only Internet Protocol version 4 (IPv4) addresses.

Command separator for incoming message

This parameter defines which character must be used to separate values in incoming messages, that is, the arguments of commands sent to the plug-in. You can choose the desired separator from the drop-down menu. However, it is not possible to select the same value as for the "Terminator for incoming message" or "Decimal point character for incoming message" parameters. The following options are available:

Separator

Description

Space

A space character is expected between the values in incoming messages.

Semicolon

A semicolon (;) is expected between the values in incoming messages.

Comma

A comma (,) is expected between the values in incoming messages.

At

An at sign (@) is expected between the values in incoming messages.

Asterisk

An asterisk (*) is expected between the values in incoming messages.

Percentage

A percentage sign (%) is expected between the values in incoming messages.

By default, it is set to "Space" which means that the respective arguments for the command must be separated by a space, for example, "PrepareRecipe "2"".

Example

The following code shows an example how the command for loading the recipe with ID 2 must be specified when this parameter is set to "At" and the parameter defining the terminator is set to "Semicolon".

Copy 
PrepareRecipe@"2";
Decimal point character for incoming message

This parameter defines which character must be used as decimal point character in incoming messages, that is, in commands sent to the plug-in. You can choose the desired character from the drop-down menu. However, it is not possible to select the same value as for the "Command separator for incoming message" parameter. The following options are available:

Character

Description

Dot

A dot (.) is expected as decimal point character for floating point numbers in incoming messages.

Comma

A Comma (,) is expected as decimal point character for floating point numbers in incoming messages.

By default, it is set to "Dot" which means that a dot must be used for any non-integer numbers that are given in incoming messages.

Example

The following code shows an example how the command for starting a single execution with an iteration parameter value 1.2 must be specified when the parameter is set to "Comma" and the parameter defining the terminator is set to "Semicolon". The first argument defines the ID of the recipe to be executed. The second argument defines the value of the iteration parameter. In this case, the value must be specified with a comma.

Copy 
StartSingleJob "2" 1,2;
Terminator for incoming message

This parameter defines which terminator must be used for messages sent to the plug-in. You can choose the desired terminator from the drop-down menu. However, it is not possible to select the same value as for the "Command separator for incoming message" parameter. The following options are available:

Terminator

Description

EndOfText

An end-of-text (\ETX) control character is expected at the end of an incoming message.

Semicolon

A Semicolon (;) is expected at the end of an incoming message.

Space

A space character is expected at the end of an incoming message.

CarriageReturn LineFeed

The control characters for a carriage return and line feed (\CR\LF) are expected at the end of an incoming message.

LineFeed

The control character for a line feed (\LF) is expected at the end of an incoming message.

By default, it is set to "LineFeed" which means that a line feed control character (\LF) is expected at the end of incoming messages.

Example

The following code shows an example how the command for starting a single execution must be specified when this parameter is set to "Semicolon".

Copy 
StartSingleJob;
Start character of incoming message

This parameter defines which start character must be used for messages sent to the plug-in. You can choose the desired start character from the drop-down menu. The following options are available:

Start character

Description

StartOfText

A start-of-text (\STX) control character is expected at the beginning of an incoming message.

Semicolon

A Semicolon (;) is expected at the beginning of an incoming message.

Space

A space character is expected at the beginning of an incoming message.

CarriageReturn LineFeed

The control characters for a carriage return and line feed (\CR\LF) are expected at the beginning of an incoming message.

LineFeed

The control character for a line feed (\LF) is expected at the beginning of an incoming message.

None

No start character is expected.

By default, it is set to "None" which means that no start character must be added.

Example

The following code shows an example how the message for starting a single execution must be specified when this parameter is set to "Semicolon" and the parameter defining the terminator is also set to "Semicolon".

Copy 
;StartSingleJob;
Terminator for outgoing message

This parameter enables you to define a terminator for outgoing messages, that is, for messages sent by the plug-in when specific events occur. By default, \r\n is defined which means that a line break is added after each message. If you want to use a different terminator, you can specify the desired terminator in the text field of the parameter.

Example

The following code shows an example how the message about a "StateChanged" event may look like when the following terminator is defined: " || ".

Copy 
PrepareRecipe "4";
StateChanged: 16 5 PrepareRecipe Initialized Ready || RecipePrepared: 16 5 "4" || 

State Changed

The parameters in this category define the settings for messages with respect to "StateChanged" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when a "StateChanged" event occurred, that is, when the state of MERLIC has changed. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when a "StateChanged" event occurred. It is only available for editing if the respective "Enable event" parameter for "StateChanged" events is activated.

By default, the format is set as follows: StateChanged: {actionId} {pluginId} {cause} {fromState} {toState}

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "StateChanged" event messages may contain the following placeholders:

Placeholder

Description

{cause}

The action that triggered the "StateChanged" event.

{fromState}

The initial state before the state change.

{toState}

The state to which MERLIC changed.

{actionId}

The ID of the action that triggered the event.

{pluginId}

The ID of the plug-in that triggered the action that led to the event.

Error

The parameters in this category define the settings for messages with respect to "Error" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when an "Error" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when an "Error" event occurred. It is only available for editing if the respective "Enable event" parameter for "Error" events is activated.

By default, the format is set as follows: Error: {actionId} {pluginId} {code} {severity} {cause} "{brief}" "{message}"

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "Error" event messages may contain the following placeholders:

Placeholder

Description

{brief}

A short description

{cause}

The action that caused the error, for example, "PrepareRecipe".

{code}

The error code.

{actionId}

The ID of the action that triggered the event.

{pluginId}

The ID of the plug-in instance that sent the message.

{message}

A detailed error message.

Recipe Prepared

The parameters in this category define the settings for messages with respect to "RecipePrepared" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when a "RecipePrepared" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when a "RecipePrepared" event occurred. It is only available for editing if the respective "Enable event" parameter for "RecipePrepared" events is activated.

By default, the format is set as follows: RecipePrepared: {actionId} {pluginId} "{recipeId}"

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "RecipePrepared" event messages may contain the following placeholders:

Placeholder

Description

{recipeId}

The ID of the recipe that has been loaded.

{actionId}

The ID of the action that triggered the event.

{pluginId}

The ID of the plug-in instance that sent the message.

Recipe Unprepared

The parameters in this category define the settings for messages with respect to "RecipeUnprepared" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when a "RecipeUnprepared" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when a "RecipeUnprepared" event occurred. It is only available for editing if the respective "Enable event" parameter for "RecipeUnprepared" events is activated.

By default, the format is set as follows: RecipeUnprepared: {actionId} {pluginId} "{recipeId}"

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "RecipeUnprepared" event messages may contain the following placeholders:

Placeholder

Description

{recipeId}

The ID of the recipe that was unloaded.

{actionId}

The ID of the action that triggered the event.

{pluginId}

The ID of the plug-in instance that sent the message.

Job Started

The parameters in this category define the settings for messages with respect to "JobStarted" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when a "JobStarted" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when a "JobStarted" event occurred. It is only available for editing if the respective "Enable event" parameter for "JobStarted" events is activated.

By default, the format is set as follows: JobStarted: {actionId} {pluginId} {jobId} "{recipeId}" {jobType} {parameters}

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "JobStarted" event messages may contain the following placeholders:

Placeholder

Description

{jobId}

The ID of the job that was started.

{jobType}

The type of the job that was started, that is, either "SingleJob" or "ContinuousJob".

{parameters}

The iteration parameter values that were specified as input argument for the execution. If multiple values were specified, the character defined in "Separator for iteration parameter values" will be used to separate the values in the message.

{recipeId}

The ID of the recipe whose execution was triggered.

{actionId}

The ID of the action that triggered the event.

{pluginId}

The ID of the plug-in instance that sent the message.
Separator for iteration parameter values

This parameter enables you to define how iteration parameter values will be separated in messages for JobStarted events if the respective job has been started with multiple iteration parameters. By default, a space is defined which means that the parameter values will be separated by a space. If you want to use a different separator, you can change the value in the text field of the parameter.

Example

The following code shows an example of an outgoing message for a JobStarted event that occurred after starting a single execution for the recipe with ID 2 and two iteration parameters. The values of the iteration parameters are listed at the end of the message if the default format is used. The example shows how the values of the iteration parameters are listed if the separator is set to "--".

Copy 
JobStarted 11 5 1 "2" SingleJob true--4 

Acquisition Done

The parameters in this category define the settings for messages with respect to "AcquisitionDone" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when an "AcquisitionDone" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when an "AcquisitionDone" event occurred. It is only available for editing if the respective "Enable event" parameter for "AcquisitionDone" events is activated.

By default, the format is set as follows: AcquisitionDone: {jobId}

At the beginning, the name of the event is given followed by a placeholder for the job ID. You can customize the format to your requirements and add further text or remove the placeholder as desired. The format for "AcquisitionDone" event messages may contain the following placeholder:

Placeholder

Description

{jobId}

The ID of the job that was started.

Ready

The parameters in this category define the settings for messages with respect to "Ready" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when a "Ready" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when a "Ready" event occurred. It is only available for editing if the respective "Enable event" parameter for "Ready" events is activated.

By default, the format is set as follows: Ready: {actionId} {pluginId} {jobId}

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "Ready" event messages may contain the following placeholders:

Placeholder

Description

{jobId}

The ID of the job that was started.

{actionId}

The ID of the action that triggered the event.

{pluginId}

The ID of the plug-in instance that sent the message.

Result Ready

The parameters in this category define the settings for messages with respect to "ResultReady" events.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when a "ResultReady" event occurred. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in if a "ResultReady" event occurred. It is only available for editing if the respective "Enable event" parameter for "ResultReady" events is activated.

By default, the format is set as follows: ResultReady: {resultId} "{recipeId}" {jobId} {timestamp} {resultState} {content}

At the beginning, the name of the event is given followed by placeholders for some content with respect to the event. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for "ResultReady" event messages may contain the following placeholders:

Placeholder

Description

{content}

The results that were generated. The individual result values of the execution will be separated by the character defined in the parameter "Separator for result content".

{id}

The ID of the results that were generated.

{jobId}

The ID of the job that generated the results.

{recipeId}

The ID of the recipe whose execution was triggered.

{resultState}

The state of the result, for example, "Completed".

{timestamp}

Time and date when the results were generated.
Separator for result content

This parameter enables you to define which separator is to be used between the individual result values. By default, a space is defined which means that the results are separated by spaces. If you want to return the results in the message with a different separator, you can change the value in the text field of the parameter.

Example

The following code shows an example how the outgoing message for a "ResultReady" event may look like if the following separator is defined for the results: "|".

Copy 
ResultReady 43 "1" 5 2024-02-15T09:43:59.931Z Completed true|0.99|"B21TA9322"

The generated results are returned at the end of the message. In this example, three result values were generated:

  • true
  • 0.99
  • "B21TA9322"

Vision System Available

The parameters in this category define the settings for messages that can be send by the plug-in when the vision system becomes available. The vision system, that is, MERLIC, is only available if MERLIC RTE is running. If the MERLIC Communicator and the plug-in have been started, no communication is possible until MERLIC RTE has also been started. In this parameter category, you can define whether you want the plug-in to send a message as soon as the vision system is available when starting MERLIC RTE after the plug-in.

The following image shows an overview of the parameters with the respective default setting. A detailed description of the parameters follows after the image.

Enable event

This parameter defines whether the plug-in sends a message when the vision system is available, that is, when MERLIC RTE is started while the plug-in is already running. By default, this parameter is set. The content and format of the message can be defined in the respective "Format" parameter.

Format

This parameter defines the format and content of the message that is sent by the plug-in when the vision system is available. It is only available for editing if the respective "Enable event" parameter is activated.

By default, the format is set as follows: VisionSystemAvailable: {state} {mode} "{recipeId}" {jobId}

At the beginning, the name of the event is given followed by placeholders for some content with respect to the vision system, the prepared recipe, and a possible running job. You can customize the format to your requirements and add further text or remove placeholders as desired. The format for this type of messages may contain the following placeholders:

Placeholder

Description

{mode}

The current operational mode of the vision system. This could be "Automatic" or "FrontendAccess".

{recipeId}

The ID of the currently prepared recipe.

{jobId}

The ID of the currently running job, for example, if MERLIC RTE was started from command line using "merlic_rte.exe --execute".

{state}

The current state of the vision system.