Message Structure

The SECS driver communicates with the device via binary encoded SEMI E5 messages. To make the E5 messages useable in WinCC OA, the SECS-II E5 messages are mapped to JSON strings.

Therefore, string DPEs must be used to request and respond. The general structure of the messages is defined by the E5 standard. Every message must have a header, which holds information about the deviceId, data length, etc. For further information refer to the E5 and E37 standard.

JSON Message Structure

The structure contains two main parts. The header and the body. The body is only needed for E5 messages which require data to be sent/received per body.

Header

The header is always a JSON-Object type with the following attributes:

JSON Object Name Type Mandatory Description
“function” Number x Describes the E5 function number
“stream” Number x Describes to which E5 stream the function is belonging
“reply” Boolean x Describes if the request awaits an answer or not
"requestId" Number Can be chosen by the operator to keep track of which request belongs to which response inside of the JSON-structure
“sessionId” Number Only needed when answering a request received from the equipment. Id of the session which can be retrieved from the equipment JSON request header.
“systemBytes” Number Only needed when answering a request received from the equipment. Unique identifier which can be retrieved from the equipment JSON request header.

Body

The Body can either be a JSON-Object or a JSON-Array (List). The Body structure is given by the E5 message definition. Body Objects which hold the data contain the following JSON Key-Value pairs:

JSON Object Name Type Mandatory Description
“format” String x Describes the format of the value of the same JSON-Data-Object. Has to be one of the abbreviations of the following data type table.
“value” Format specific x Holds the value of the JSON-Data-Object

The “format” can be one of the following data types:

Abbreviation Description
B Binary
BL Boolean
A ASCII
JIS JIS-8
V 2 byte character
I8 8 byte integer (signed)
I1 1 byte integer (signed)
I2 2 byte integer (signed)
I4 4 byte integer (signed)
F8 8 byte floating point
F4 4 byte floating point
U8 8 byte integer (unsigned)
U1 1 byte integer (unsigned)
U2 2 byte integer (unsigned)
U4 4 byte integer (unsigned)

The V(2 Byte Character) lists encodings in the SEMI E5 Standard chapter 9.4.2 Table 2. Not all the encodings are supported by WinCC OA. The following encodings are supported by WinCC OA:

  • ISO 10646 UCS-2
  • UTF-8
  • ISO 8859-1
  • TIS 620
  • Shift JIS
  • Japanese EUC-JP
  • Korean EUC-KR
  • Simplified Chinese EUC-CN
  • Traditional Chinese Big5

When one of the not supported encodings is used, a byte array will be given in the JSON object which can be validated by the user.

JSON Example

This is an example of a S1F3R sent from the host to the equipment to get the “Selected Equipment Status Request” and the answer from the equipment as an S1F4 response.

{
    "header": {
        "function": 3,
        "reply": true,
        "stream": 1
    },
    "body": [{
        "format": "U4",
        "value": 250
    }]
}
{
    "header": {
        "function": 4,
        "reply": false,
        "stream": 1
    },
    "body": [{
        "format": "A",
        "value": "2024111214454153"
    }]
}