Protocols for the Data Exchange

Besides configuring the Hilscher card, you also have to make sure that the programmable logic controller (PLC) is configured correctly. It must be set up to send and receive data in a predefined structure that is required and expected by MERLIC. If the data is not transmitted in the required structure, MERLIC or the PLC will not be able to process the data correctly. The required structure for the data exchange is defined in the following protocols:

  • FromMerlicProtocol
  • FromPLCProtocol

They define which information is transmitted together with the respective data types.

To establish the communication between MERLIC and the Hilscher card, you also have to consider the available internal states of MERLIC during the process integration and the available commands, for example to start a single execution. This information is required to correctly configure the communication process for the process integration. For more information, see MERLIC State Machine and Commands (Hilscher).

If data is exchanged as a whole memory array, for example, by defining data struct declarations, some PLCs add padding bytes between the members of the struct declarations by default.

FromPLCProtocol

This protocol defines the expected structure of the data that is transmitted from the PLC to MERLIC. The following code block shows the order and data types in which the data from the PLC is expected and interpreted by MERLIC.

Copy 
TYPE FromPLCProtocol :
STRUCT
    Preamble : BYTE;
    CommandCode : WORD;
    Selector : DINT;
END_STRUCT
END_TYPE

The following table describes the respective members that are required in this protocol.

Member

Description

Offset

Size in Byte

Preamble

Preamble that defines where the data of the actual protocol start. MERLIC expects the value 17.

0

1

CommandCode

Code of the command which the PLC requests MERLIC to execute. For more information about commands, see Commands (Hilscher).

1

2

Selector

Possible parameter for a command. It is currently used in combination with the commands "PrepareRecipe" and "GetResult" to pass a recipe ID or result ID, respectively.

3

4

FromMerlicProtocol

This protocol defines the structure of the data that is transmitted from MERLIC to the PLC. The following code block shows the order and data types in which the data are transmitted from MERLIC.

Copy 
TYPE FromMerlicProtocol :
STRUCT
    Preamble : BYTE;
    VersionMajor : USINT;
    VersionMinor : USINT;
    RecipeId : INT;
    CommandCode : WORD;
    ActionResponse : WORD;
    CurrentState : WORD;
    LastResultId : UDINT;
    LastStartedJobId : UDINT;
    Reserved : ARRAY[1..5] OF BYTE;
    ResultState : BYTE;
    BoolCount : USINT;
    ByteCount : USINT;
    WordCount : USINT;
    DWordCount : USINT;
    LWordCount : USINT;
    SIntCount : USINT;
    USIntCount : USINT;
    IntCount : 0USINT;
    UIntCount : USINT;
    DIntCount : USINT;
    UDIntCount : USINT;
    LIntCount : USINT;
    ULIntCount : USINT;
    RealCount : USINT;
    LRealCount : USINT;
    TimeCount : USINT;
    TimeOfDayCount : USINT;
    LTimeCount : USINT;
    DateCount : USINT;
    DateAndTimeCount : USINT;
    Str80Count: USINT;
    TotalResultCount : UINT;
    // For each transmitted result, the data integrity
    // and value is returned.
    // They are assigned by their index i.
    DataIntegrity{i} : BYTE;
    Result{i} : VALUE_TYPE;
    DataIntegrity{i+1} : BYTE;
    Result{i+1} : VALUE_TYPE;
    ...
END_STRUCT
END_TYPE

The following table describes the respective members that are required in this protocol.

Member

Description

Offset

Size in Byte

Preamble

Preamble that defines where the data of the actual protocol starts. By default it is set to 17 by MERLIC.

0

1

VersionMajor

Major version number of the protocol.

1

1

VersionMinor

Minor version number of the protocol.

2

1

RecipeId

ID of the loaded recipe.

3

2

CommandCode

Command code, mirrored by MERLIC to the PLC to acknowledge that a command has been read.

5

2

ActionResponse

Response to the requested command. For more information on the possible values, see the section ActionResponse.

7

2

CurrentState

Current state of MERLIC. For more information about the supported state, see MERLIC State Machine.

9

2

LastResultId

ID of the complete set of results that have been calculated in the last iteration of an MVApp. The ID begins with 0 and increases for each result.

11

4

LastStartedJobId

ID of the last started job in the type UDINT.

15

4

Reserved

Reserved for future use.

19

5

ResultState

State of the queried result data. It is set whenever a result is queried. The following "ResultState" values are possible:

  • 0 (Undefined)
  • 1 (Completed): The processing was carried out correctly.
  • 2 (Processing): The processing has not been finished yet.
  • 3 (Aborted): The processing was stopped at some point before the completion.
  • 4 (Failed): The processing failed in some way.

24

1

BoolCount

Number of the Boolean results that are transmitted to the PLC.

25

1

ByteCount

Number of the BYTE results that are transmitted to the PLC.

26

1

WordCount

Number of the WORD results that are transmitted to the PLC.

27

1

DWordCount

Number of the DWORD results that are transmitted to the PLC.

28

1

LWordCount

Number of the LWORD results that are transmitted to the PLC.

29

1

SIntCount

Number of the SINT results that are transmitted to the PLC.

30

1

USIntCount

Number of the USINT results that are transmitted to the PLC.

31

1

IntCount

Number of the INT results that are transmitted to the PLC.

32

1

UIntCount

Number of the UINT results that are transmitted to the PLC.

33

1

DIntCount

Number of the DINT results that are transmitted to the PLC.

34

1

UDIntCount

Number of the UDINT results that are transmitted to the PLC.

35

1

LIntCount

Number of the LINT results that are transmitted to the PLC.

36

1

ULIntCount

Number of the ULINT results that are transmitted to the PLC.

37

1

RealCount

Number of the REAL results that are transmitted to the PLC.

38

1

LRealCount

Number of the LREAL results that are transmitted to the PLC.

39

1

TimeCount

Number of the TIME results that are transmitted to the PLC.

40

1

TimeOfDayCount

Number of the TIME_OF_DAY results that are transmitted to the PLC.

41

1

LTimeCount

Number of the LTIME results that are transmitted to the PLC.

42

1

DateCount

Number of the DATE results that are transmitted from to the PLC.

43

1

DateAndTimeCount

Number of the DATE_AND_TIME results that are transmitted to the PLC.

44

1

Str80Count

Number of the STRING_80 results that are transmitted to the PLC.

45

1

TotalResultCount

Number of all results that are transmitted to the PLC.

46

2

DataIntegrity{i}

Information about the validity and possible conversion errors of the result value with the index i. The index i begins with 0 and refers to the result value of the i-th MVApp result that has been returned for the requested "LastResultId".

The results are transmitted in the order described in the protocol above, for example, first all Boolean results are returned, then all BYTE results and so on.

For more information on the meaning of each bit, see the section Byte Information for DataIntegrity.

48

1

Result{i}

Value of the transmitted result with the index i. The index i begins with 0 and refers to the i-th MVApp result that has been returned for the requested "LastResultId".

The results are transmitted in the order as described in the protocol above, for example, first all results of Boolean type are returned, then all results of type BYTE and so on.

 

 

ActionResponse

The following table lists all possible values for the ActionResponse member.

Value

ActionResponse

Description

0x0000

Unknown

The response is unknown, for example, if no command has been executed yet.

0x0001

Success

The command could be processed successfully.

0x1110

InternalError

A severe error occurred that caused the internal state of the vision system to become inconsistent. A restart of the vision system is required.

0x1134

RecipeUnpreparationFailed

The application could not be unloaded; the system failed to restore the Initialized state.

0x2113

NotImplemented

The command is not supported.

0x2116

AcquisitionDeviceLost

The image acquisition device, that is, the camera or image file directory, is missing.

0x2130

UserAccessDenied

The requested command cannot be executed because the caller is not eligible to do so at this time.

0x2133

RecipePreparationFailed

The application that is specified in the recipe file could not be loaded.

0x2135

ResponsePromiseBroken

The status of the requested command is unknown and will not be set in the future.

0x2138

AcquisitionConflictingTimeout

The image acquisition partially timed out. In a multi-camera setup, the acquisition by some hardware-triggered cameras succeeded while the acquisition by other cameras timed out and it cannot be ensured that the image buffers of all cameras are in a consistent state.

0x2139

AcquisitionError

The image acquisition failed.

0x2175

UnknownRecipeId

The specified recipe ID is unknown.

0x2236

DataflowError

The dataflow of the application that is specified in the requested recipe file has blocks or races.

0x2801

MessageTooSmall

There is not enough space available for the transmission of the message.

0x4131

ActionRejected

The requested action is not allowed in the current state of the vision system.

0x4132

ActionSuperseded

The requested action will not finish as expected because it was superseded by another action which takes precedence.

0x4137

AcquisitionTimeout

The acquisition timed out. Perhaps a hardware triggered camera did not receive the trigger signal within the specified "grab_timeout" interval or the connection to a camera was lost during acquisition.

0x4176

UnknownResultId

The specified result ID is unknown. The corresponding result may have been dropped from the result store's ring buffer and is no longer available.

0x4296

IncompatibleParameters

The provided job parameter tuple does not conform to the recipe interface, for example, because the number of tuple elements does not match the number of recipe values or the conversion of the tuple elements to the data type of the respective recipe value is lossy.

Byte Information for DataIntegrity

The byte that is transmitted for the member DataIntegrity contains various information about the value of a specific result. The first two bits specify if the value is valid and if it contains any value at all.

Bit

Name

Description

0

Validity

This bit is set to 1 if the value is valid, otherwise it is set to 0.

1

Value of last iteration

This bit is set to 1 if the value has been determined in the last iteration of the MVApp. If the value was not calculated during the last iteration, for example, the parameter was in an inactive branch, this bit will be set to 0.

The following bits give information about the possible conversion errors.

Bit

Name

Description

2

Empty value

This bit is set to 1 if the value is empty, otherwise it is set to 0.

3

Lossy conversion

This bit is set to 1 if information was lost at the conversion of the value, otherwise it is set to 0.

4

Multiple values

This bit is set to 1 if the result contains multiple values, otherwise it is set to 0. This bit is reserved because multiple values are currently not supported.

5

Convertibility

This bit is set to 1 if the type of the result value is not convertible to the data type that has been selected for the respective MVApp result, otherwise it is set to 0.

6

Out of range

This bit is set to 1 if the value is not within the allowed range limits that have been selected for the respective MVApp result, otherwise it is set to 0.

7

String too long

This bit is set to 1 if the value represents a string that is too long, otherwise it is set to 0.