SECS Message Basics

From the SECS-II standard:

"SECS-II defines the method of conveying information between equipment and host in the form of messages. These messages are organized into categories of activities, called streams, which contain specific messages, called functions. "

Each SECS message specifies a stream and a function. Specific SECS messages are often referred to in this format: S(number)F(number). For example S1F13 refers to SECS message Stream 1, Function 13.

Requests and Responses

There are two kinds of messages:

  • Request: sometimes called the primary message. These originate from the Host, which in the context of Ignition, is the Ignition Gateway. Requests are odd-number functions, such as S1F1. 
  • Response: sometimes known as a secondary message. These originate from the Equipment. Responses are even-number functions, such as S1F2

Thus, the Host can send an S1F1 Request, which establishes if the Equipment is on-line. If so, then the Equipment will respond with an S1F2 Response, which signifies that the Equipment is on-line. Each request can only have a single response message, or no response message if none is needed. This Request-and-Response pattern is the basis of the module, and the standard. 





SECS Message Format

Every SECS message is a JSON formatted string, which contains a header. The header contains the stream, function, and if the message expects a response message. Optionally, the SECS message can have a body, which consists of a list of one or more data items. Each data item can also be a list of other data items. This forms the basis for which all SECS messages should look like, regardless of if they are a request or response.

SECS Message Example

The following is an example of a S1F11 request:

{  
   "header":{  
      "doc":"Status Variable Namelist Request",
      "stream":1,
      "function":11,
      "reply":true
   },
   "body":[  
      {  
         "doc":"SVID, Status Variable ID",
         "format":"U4",
         "value":4
      }
   ]
}

When making this request from a script, the sendRequest function takes in the header values as parameters, with the whole body as another parameter.

body = [{"format":"U4", "value":4}]
 
transactionID = system.secsgem.sendRequest("S1F11",True,body,"Equip4")

A typical response to the above request would look something like this:

{  
   "header":{  
      "doc":"Status Variable Namelist Reply",
      "stream":1,
      "function":12,
      "reply":false
   },
   "body":[  
      [  
         {  
            "doc":"SVID, Status Variable ID",
            "format":"U4",
            "value":4
         },
         {  
            "doc":"SVNAME, Status Variable Name",
            "format":"A",
            "value":"RandomBinaryData"
         },
         {  
            "doc":"UNITS, Units Identifier",
            "format":"A",
            "value":"B"
         }
      ]
   ]
}

Each response message would be received using the getResponse function, which would use the transactionID from the sendRequest call above, and then do something with the response such as printing it.

response = system.secsgem.getResponse(transactionID, "Equip4")

print response

This simple request/response between the Gateway and Equipment forms the basis for communication using the SECS/GEM module. However, there are some other tools that allow you to receive the response message in different ways: through Tags and Message Handlers.

In order to send a certain function request, the equipment connection must have that function defined in the SDL File.



SECS Messages through Tags

Any SECS messages that contain data can be captured in Tags that can then be used within a project. This can be really useful for something like data coming back from tool traces within the S6F1 messages. When properly configured, the system will automatically create the appropriate Tags within the equipment's folder in the SECSGEM Realtime Tag Provider. While the Tags that get created can be bound to components, they cannot be written to and they can't be edited which means no Tag History, no Alarming, etc. Also note that if the Gateway is ever restarted those Tags will disappear, so they will need to be recreated. To have responses generate Tags, the function must be configured to do so within the SDL File.  This is done by adding an object called 'SQLTags' with a value of 'true', along with a 'CommonID' array that holds an identifier. The default SDL file is preconfigured to create Tags for S6F1 messages. Sending a S2F23 request with the appropriate trace parameters to the tool will produced Tags based on the response message. With each new S6F1 message that is received, the Tags will update their values. Using the built in simulator, you can easily create Tag values by calling the S2F23 request with the body below.



[  
   {  
      "doc":"TRID, Trace Request ID.",
      "format":"U4",
      "value":1
   },
   {  
      "doc":"DSPER, Data sample period.",
      "format":"A",
      "value":"000002"
   },
   {  
      "doc":"TOTSMP, Total Samples",
      "format":"U4",
      "value":10
   },
   {  
      "doc":"REPGSZ, Reporting Group Size",
      "format":"U4",
      "value":1
   },
   [  
      {  
         "doc":"SVID Status Variable ID",
         "value":1,
         "format":"U4"
      },
      {  
         "doc":"SVID Status Variable ID",
         "value":2,
         "format":"U4"
      },
      {  
         "doc":"SVID Status Variable ID",
         "value":3,
         "format":"U4"
      }
   ]
]


An Example with S2F14 using the Simulator

This example sets up the S2F14 message to create Tags that we can see in the Tag provider. It assumes the equipment connection is made to a simulator with the default SDL file. In order to capture other messages in Tags, the SDL File will need to be configured to allow that. Here, we setup the SDL File to have S2F14 to create Tags.

  1. Go to the Gateway Webpage Configure section, and navigate to SECSGEM -> Equipment.
    1. On the equipment connection, edit the SDL File.
  2. Locate the S2F14 message in the list.
    1. Add "SQLTags" as an Auto type object with a value of "true" directly under the S2F14 root.
    2. Create an array called "CommonID" directly under the S2F14 root.
      1. Add "0: ECV" to the CommonID array as an Auto type object.
  3. Save the SDL file and restart the equipment connection.

  4. Once the equipment connection has been reestablished, send it an S2F13 message with the body below:


    [  
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":200
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":201
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":203
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":205
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":206
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":207
   }
]




SECS Messages through Message Handlers

Similar to how SECS message data can be captured in tags, they can instead be made to call a custom Python script. To implement a custom Python script, the message will need to call a Message Handler with the name onSecsGemRealtimeUpdate. This Message Handler must have that exact name, though a handler can be specified for both the Client Event Scripts and the Gateway Event Scripts. Within the Message Handler, the SECS message will pass in information into the payload object.

Payload KeyValue
CommonIDThe common ID of the message.
EquipmentThe name of the equipment that the message is coming from.
DirectionThe direction of the message.
RequestResponseIf this was from a request or a response.
TxIDThe transaction ID of the message.
ReplyIf this message expected a reply.
MessageThe message contents.

This script can handle the message in any way such as storing data in the database or writing to Tags. The example below will take the information and create a logger object with it that will then be printed to the console.

# This message handler is very simple in that it will create a logger with the SECS message data that prints to the console.

commonID = payload['CommonID']
equipment= payload['Equipment']
direction = payload['Direction']
reqResp = payload['RequestResponse']
txId = payload['TxID']
reply = payload['Reply']
message = payload['Message']

msg = "CommonID=" + commonID
msg += ", Equipment=" + equipment
msg += ", Direction=" + direction
msg += ", RequestResponse=" + reqResp
msg += ", TxID=" + str(txId)
msg += ", Reply=" + str(reply)
msg += ", Message=" + message
logger = system.util.getLogger("SECSGEM.Gateway.onSecsGemRealtimeUpdate")
logger.info(msg)

Once an onSecsGemRealtimeUpdate Message Handler has been specified, it needs to be specified within the Gateway. Within the Gateway Webpage Configure section, the Module Settings page under the SECS/GEM header will have Properties to specify which project holds the Gateway Message Handler and which project holds the Client Message Handler. These can be the same project or different projects.

An Example with S2F14 using the Simulator

This example sets up the S2F14 message to call the Gateway Message Handler that we setup. It assumes the equipment connection is made to a simulator with the default SDL file. In order to capture message with the onSecsGemRealtimeUpdate, the SDL File will need to be configured to allow that. Here we setup the SDL File to have S2F14 to go through the message handler.

  1. Create a Gateway Message Handler called onSecsGemRealtimeUpdate.
  2. Go to the Gateway Webpage Configure section, and navigate to the SECS/GEM ->Module Settings page.
    1. Specify the project that the Gateway Message Handler was created on in the Gateway Message Handler Project setting.
  3. Within the Gateway Webpage Configure section, navigate to SECS/GEM -> Equipment.
    1. On the equipment connection, edit the SDL File.
  4. Locate the S2F14 message in the list.
    1. Add "realtime" as an Auto type object with a value of "true" directly under the S2F14 root.
    2. Create an array called "CommonID" directly under the S2F14 root.
      1. Add "0: ECV" to the CommonID array as an Auto type object.
  5. Save the SDL file and restart the equipment connection.

  6. Once the equipment connection has been reestablished, send it an S2F13 message with the body below:


    [  
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":200
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":201
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":203
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":205
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":206
   },
   {  
      "doc":"ECID, Equipment Constant ID",
      "format":"U4",
      "value":207
   }
]




Custom SECS Message Response Handlers

For messages that expect a response, the system is setup to automatically send a response based on what is configured in the SDL file. However, a custom response can be created using a Message Response Handler, allowing you to build custom responses completely in the Python scripting language. Only one custom response to a stream function can be configured per equipment connection, but each equipment connection can have multiple custom responses, each to a different stream function. By setting up a custom Message Response Handler for a stream function, the handler will be used for all responses to the specified stream function.

A Message Response Handler is setup on an equipment connection and pointed at a Gateway Event Script Message Handler. Each Message Handler will have a payload object that will contain information from the default message response.

Payload KeyValue
EquipmentThe name of the equipment that the message is coming from.
TxIDThe transaction ID of the message.
SystemBytesThe system bytes of the response.
MessageThe message contents.

Using the data given to us in the payload, the Message Handler can then manipulate it in any way before calling the system.secsgem.sendResponse function, which will send the response back to the equipment.



As of 7.9.15, custom response handlers will execute when receiving messages over the SECS-1 (serial) protocol. 


Once a Message Handler has been created, the equipment connection needs to specify that it will be using that as a custom message response. To do this, navigate to the Gateway Webpage Configure section, navigate to SECS/GEM -> Equipment. For the equipment connection, click the more button on the right and select the Custom Responses option

On the Message Response Handlers page, we can setup a link between the stream function response we want to intercept and which Message Handler will be used to handle it. Each Message Response Handler has the following settings.

SettingDescription
Enabled

If true, the specified script message handler will be fired when the specified StreamFunction is encountered.

Intercept Stream FunctionThe SECS stream and function type of the message that will be intercepted. Use a value such as "S6F2"
Gateway Message HandlerThe name of the script message handler that will create the SECS response message. This message handler must be created in a project to provide custom responses, and must be a Gateway Event Script message handler.
Project NameThe project that contains the script message handler specified above.