Fields for the Communication with the PLC

The documentation on this page is currently only available in English.

The SIMATIC S7 plug-in makes use of the SIMATIC S7 communication protocol to communicate with the PLC. The transmitted information is defined by the configuration of the plug-in. For each type of information, for example, the requested command or a result value, a so-called "field" is provided. The set of fields is exported to an .xml file when the plug-in is started and it represents the set of global "tags" for the PLC. The exported .xml file can be imported into the PLC programming software TIA Portal - SIMATIC STEP 7 where it is used as the basis for the PLC program.

For each field in the .xml file, a specific memory block is reserved on the PLC. The fields are used by both the PLC and by the plug-in to write and read the required data. The fields can be separated into two blocks in the PLC's memory. One block of fields is used by the PLC to request commands or to define arguments for the execution. The other block is used by the plug-in to write information provided by the vision system, for example, general information on the vision system or the results of an execution. The PLC can read and process the information provided in the fields that are written by the plug-in and vice versa. Each field has a predefined name.

Some of the fields are a fixed part of the setup and will always be provided, for example, the field containing the current state of the vision system. We will refer to these types of fields as static fields. In contrast, there are also some dynamic fields which depend on the configuration of the plug-in and are provided only if the respective parameters of the plug-in are set accordingly, for example, the fields for result values. In the following sections, you can find an overview of the static fields, which are a fixed part in the protocol, and the dynamic fields, which are added only if the plug-in is configured accordingly.

Exporting the Fields for the PLC

The set of fields can be exported in the "Communication" tab of the MERLIC RTE Setup.

Select the desired SIMATIC S7 plug-in instance on the left to show the configuration of the plug-in.
If necessary, adjust the location and file name of the .xml file to be exported. The respective parameters are provided in the parameter category Export Tags.
Click on the "Start plug-in" button on the bottom of the MERLIC RTE Setup to export the fields to the specified .xml file.

An .xml file will be exported automatically as soon as the plug-in is started, that is, as soon as you click on the start button. It contains information on all required fields, the respective data type, and the assigned memory addresses. The file can be created independently of the PLC. A connection to the PLC is not required for the export. However, if the connection is not established yet, an error message occurs that the plug-in could not be started. You can ignore this error if you only wanted to export the .xml file.

When implementing the program for the PLC in TIA Portal - SIMATIC STEP 7, the exported file serves as input which fields and memory blocks are required for the communication. For this, you can imported file as described in the next section.

Importing the "Tags" File

After exporting the selected fields of your plug-in configuration to a "Tags" .xml file, you can import this file in TIA Portal - SIMATIC STEP 7 and use the respective fields for the implementation of the PLC program.

For our documentation, we make use of TIA Portal - SIMATIC STEP 7 v18. If you are using a different version of SIMATIC STEP 7, the user interface and parameter names might differ from the ones that are visible in our example images. For information on SIMATIC STEP 7 in general, its features, and how to work with it to program and monitor SIMATIC PLCs, please refer to the website of Siemens.

In SIMATIC STEP 7, you can import the file as described in the following steps.

Go to the "PLC tags" section of your project.
Create a new table and open it, or just open the "Default tag table".
In the Tags window that just opened, click on the "Import" button.
Navigate to the file location and open it. The tags will then be available.

If you need to update a file from a project because the configuration changed, for example, to add new results, you must first delete all old variables from MERLIC in the PLC project before importing the new ones.

Static Fields

Fields of this type are always available for the communication. Most of them are written by the plug-in to provide information on the vision system or on the current execution. The PLC writes only a few of the static fields.

Static Fields Written by Plug-in

Field	Data type	Description
gMV_VersionMajor	UINT	Major version number of the plug-in.
gMV_VersionMinor	UINT	Minor version number of the plug-in.
gMV_Heartbeat	UINT	Heartbeat count.
gMV_CurrentState	INT	Current state of MERLIC, for example, 72 for "SingleExecution". For more information on the values of the different state and how they are encoded, see the section MERLIC States.
gMV_LastResultId	UDINT	ID of latest result.
gMV_NumberOfRecipes	DINT	Number of recipes that are available.
gMV_PreparedRecipeIds	DWORD	Indicator which recipe is currently prepared. It contains an bit-array (one DWord) in which each entry indicates whether the recipe corresponding to the index is currently prepared. This only works if 32 or fewer recipes are defined. In addition, only one recipe can be prepared when MERLIC is used.
gMV_RunningJobId	UDINT	ID of the job that is currently running.
gMV_AcquisitionDoneCount	UDINT	Number of image acquisitions that have been performed for the current job. Initially it is set to 0 which indicates that no images have been acquired yet. It is reset for each new job.
gMV_AckCommandCode	INT	Code of the requested command that has been acknowledged last by the plug-in.
gMV_ErrorCode	WORD	Numeric error code. It provides information on the nature of the error, the severity, and the affected component. For more information on how errors are returned, see the topic Error Handling.
gMV_ErrorCause	INT	Code of the command that caused an error. It assumes the same numeric value as given in the "gMV_ReqCommandCode" and "gMV_AckCommandCode" fields. For more information on how errors are returned, see the topic Error Handling.
gMV_DroppedResultCount	UDINT	Number of results that have been dropped when using the result mode "Dequeue from buffer". Initially, it is set to 0 and incremented for each result that has been dropped. If the PLC does not dequeue the results fast enough and the result buffer capacity is exceeded, the oldest result in the buffer is dropped, that is, the result which would have been dequeued next.
gMV_ResultId	UDINT	ID of the currently displayed result.
gMV_ResultRecipeId	UDINT	ID of the recipe which produced the displayed result.
gMV_ResultJobId	UDINT	ID of the job which produced the displayed result.
gMV_ResultState	INT	State of the displayed result: 1 = completed 2 = processing 3 = aborted 4 = failed

Static Fields Written by PLC

Field	Data type	Description
gMV_ReqCommandCode	INT	Code of the requested command. For more information on the available commands and their codes, see the topic Communication between Plug-in and PLC .
gMV_CommandRecipeIdInUse	BOOL	Indicator of whether the recipe that is defined in "gMV_CommandRecipeId" shall be used for the command requested in "gMV_ReqCommandCode".
gMV_CommandRecipeId	DINT	ID of the recipe that will be used for the command requested in "gMV_ReqCommandCode" if the value of "gMV_CommandRecipeIdInUse" is set to TRUE.

Field

Data type

Description

gMV_ReqCommandCode

INT

Code of the requested command.

For more information on the available commands and their codes, see the topic Communication between Plug-in and PLC .

gMV_CommandRecipeIdInUse

BOOL

Indicator of whether the recipe that is defined in "gMV_CommandRecipeId" shall be used for the command requested in "gMV_ReqCommandCode".

gMV_CommandRecipeId

DINT

ID of the recipe that will be used for the command requested in "gMV_ReqCommandCode" if the value of "gMV_CommandRecipeIdInUse" is set to TRUE.

Dynamic Fields

Fields of this type are not provided by default. They are only added to the PLC memory if the plug-in is configured accordingly. Thus, the configuration of the plug-in determines which of the dynamic fields will be available for the communication. As with the static fields, some of the dynamic fields are written by the plug-in and some others are written by the PLC. The following sections provide an overview of the dynamic fields.

Dynamic Fields Written by the Plug-in

Field	Description
gMV_ResultUseArray_<TYPE>_<INDEX>	Indicator of whether any results of the respective data type are available to be queried. It contains a bit array (allocated as individual WORD values) in which each bit serves as indicator for a specific result of this data type. The number of WORDs allocated depends on the configuration of the plug-in, that is, it depends on the setting for the respective result data type in the category Writing Data to PLC Memory. For each 16 results of one data type, the <INDEX> value is increased by one and a new word is allocated. For example, if the plug-in parameter "INT (signed 16-bit integer) result allocation" is set to 2, the field "gMV_ResultUseArray_Int_0" will be added to the PLC memory. If the two least significant bits of "gMV_ResultUseArray_Int_0" are TRUE, both results of data type INT are available. Available data types: BOOL BYTE WORD DWORD SINT INT DINT REAL LREAL
gMV_Result_<TYPE>_<INDEX>	These types of fields will only be added to the PLC memory if the configuration of the plug-in is set accordingly in the category Writing Data to PLC Memory. For example, if the plug-in parameter "INT (signed 16-bit integer) result allocation" is set to 2, two fields for the result values will be added to the PLC memory: "gMV_Result_Int_0" and "gMV_Result_Int_1". The field with the label "gMV_Result_Int_0" will be used for the value of the first result of data type INT and the field with the label "gMV_Result_Int_1" will be used for the second gMV_Result_Int_1 result. After an execution, the first two bits of "gMV_ResultUseArray_Int_0" will indicate whether these gMV_Result_Int_1 results are available.

Field

Description

gMV_ResultUseArray_<TYPE>_<INDEX>

Indicator of whether any results of the respective data type are available to be queried.

It contains a bit array (allocated as individual WORD values) in which each bit serves as indicator for a specific result of this data type. The number of WORDs allocated depends on the configuration of the plug-in, that is, it depends on the setting for the respective result data type in the category Writing Data to PLC Memory. For each 16 results of one data type, the <INDEX> value is increased by one and a new word is allocated.

For example, if the plug-in parameter "INT (signed 16-bit integer) result allocation" is set to 2, the field "gMV_ResultUseArray_Int_0" will be added to the PLC memory. If the two least significant bits of "gMV_ResultUseArray_Int_0" are TRUE, both results of data type INT are available.

Available data types:

BOOL
BYTE
WORD
DWORD
SINT
INT
DINT
REAL
LREAL

gMV_Result_<TYPE>_<INDEX>

These types of fields will only be added to the PLC memory if the configuration of the plug-in is set accordingly in the category Writing Data to PLC Memory.

For example, if the plug-in parameter "INT (signed 16-bit integer) result allocation" is set to 2, two fields for the result values will be added to the PLC memory: "gMV_Result_Int_0" and "gMV_Result_Int_1". The field with the label "gMV_Result_Int_0" will be used for the value of the first result of data type INT and the field with the label "gMV_Result_Int_1" will be used for the second gMV_Result_Int_1 result. After an execution, the first two bits of "gMV_ResultUseArray_Int_0" will indicate whether these gMV_Result_Int_1 results are available.

Dynamic Fields Written by the PLC

Field	Description
gMV_ItParamUseArray_<TYPE>_<INDEX>	Indicator of whether the recipe parameters of the respective data type shall be overwritten for the next execution by the values defined in the fields of the corresponding iteration parameters. It contains a bit array (allocated as individual WORD values) in which each bit serves as indicator for a specific iteration parameter of this data type. The size of the array depends on the configuration of the plug-in, that is, it depends on the setting for the respective iteration parameter data type in the category Reading Data from PLC Memory. For each 16 results of one data type, the <INDEX> value is increased by one and a new word is allocated. For example, if the plug-in parameter "Int (signed 16-bit integer) iteration parameter allocation" is set to 2, the field "gMV_ItParamUseArray_Int_0" will be added together with the fields "gMV_ItParam_Int_0" and "gMV_ItParam_Int_1" for the values of the iteration parameters. If the first two bits of "gMV_ItParamUseArray_Int_0" are set to TRUE, the first two recipe values of data type INT will be overridden for the next execution with the values defined in "gMV_ItParam_Int_0" and "gMV_ItParam_Int_0".
gMV_ItParam_<TYPE>_<INDEX>	Values for the iteration parameters of the respective data types. The label of an iteration parameter field is composed of the prefix "gMV_ItParam_" followed by the data type and the index of the iteration parameter. These types of fields will only be added to the PLC memory if the configuration of the plug-in is set accordingly in the category Reading Data from PLC Memory. For example, if the plug-in parameter "Int (signed 16-bit integer) iteration parameter allocation" is set to 2, two fields for the result values will be added to the PLC memory: gMV_ItParam_Int_0" and "gMV_ItParam_Int_1". The field with the label "gMV_ItParam_Int_0" is used for the value of the first iteration parameter of data type Int and the field with label "gMV_ItParam_Int_1" is used for the value of the second Int parameter. When requesting a "StartSingleJob" or "StartContinuous" command, the first two bits of "gMV_ItParamUseArray_Int_0" will indicate whether these values will be used to override the respective values defined in the recipe.

Field

Description

gMV_ItParamUseArray_<TYPE>_<INDEX>

Indicator of whether the recipe parameters of the respective data type shall be overwritten for the next execution by the values defined in the fields of the corresponding iteration parameters.

It contains a bit array (allocated as individual WORD values) in which each bit serves as indicator for a specific iteration parameter of this data type. The size of the array depends on the configuration of the plug-in, that is, it depends on the setting for the respective iteration parameter data type in the category Reading Data from PLC Memory. For each 16 results of one data type, the <INDEX> value is increased by one and a new word is allocated.

For example, if the plug-in parameter "Int (signed 16-bit integer) iteration parameter allocation" is set to 2, the field "gMV_ItParamUseArray_Int_0" will be added together with the fields "gMV_ItParam_Int_0" and "gMV_ItParam_Int_1" for the values of the iteration parameters. If the first two bits of "gMV_ItParamUseArray_Int_0" are set to TRUE, the first two recipe values of data type INT will be overridden for the next execution with the values defined in "gMV_ItParam_Int_0" and "gMV_ItParam_Int_0".

gMV_ItParam_<TYPE>_<INDEX>

Values for the iteration parameters of the respective data types. The label of an iteration parameter field is composed of the prefix "gMV_ItParam_" followed by the data type and the index of the iteration parameter.

These types of fields will only be added to the PLC memory if the configuration of the plug-in is set accordingly in the category Reading Data from PLC Memory.

For example, if the plug-in parameter "Int (signed 16-bit integer) iteration parameter allocation" is set to 2, two fields for the result values will be added to the PLC memory: gMV_ItParam_Int_0" and "gMV_ItParam_Int_1". The field with the label "gMV_ItParam_Int_0" is used for the value of the first iteration parameter of data type Int and the field with label "gMV_ItParam_Int_1" is used for the value of the second Int parameter. When requesting a "StartSingleJob" or "StartContinuous" command, the first two bits of "gMV_ItParamUseArray_Int_0" will indicate whether these values will be used to override the respective values defined in the recipe.

MERLIC States

When using the SIMATIC S7 plug-in, the internal state of MERLIC is transmitted to the PLC via the field "gMV_CurrentState".

The byte that transmits the information about the current state is encoded as follows:

Bit field position	Numeric value	MERLIC state	Description
0	1	Preoperational	If this bit is set to 1, MERLIC is in the state "Preoperational".
3 3, 4 3, 5 3, 6 3, 7	8 24 40 72 136	OperationalAutomaticMode Initialized Ready SingleExecution ContinuousExecution	If this bit is set to 1, MERLIC is in the state "OperationalAutomaticMode". This means that MERLIC is either in the state "Initialized", "Ready", "SingleExecution", or "StartContinuous": If the 3rd and 4th bit are set, MERLIC is in the state "Initialized". If the 3rd and 5th bit are set, MERLIC is in the state "Ready". If the 3rd and 6th bit are set, MERLIC is in the state "SingleExecution". If the 3rd and 7th bit are set, MERLIC is in the state "ContinuousExecution".
1	2	Halted	If this bit is set to 1, MERLIC is in the state "Halted".
2	4	Error	If this bit is set to 1, MERLIC is in the state "Error".
3, 8	264	OperationalFrontendAccessMode	If the 3rd and 8th bit are set, MERLIC is in the manual mode. This means that MERLIC can be controlled only via the MERLIC Frontend. For more information about the manual mode, see the topic Write Access in the Frontend in the MERLIC manual.

For more information about the available states of MERLIC and its transitions, see the topic MERLIC States in the MERLIC manual.