This document describes two approaches for sending SECS/GEM messages to equipment through AMQP routing keys: the REST Emulator and the Message Transaction. Both accept a JSON payload published to an AMQP topic, but they differ in how they handle message ordering, execution, and response reporting.

For general information on AMQP routing key formats, data types, and the request/response pattern used by built-in message types (SV requests, terminal display, etc.), see Controlling SECS/GEM Messages via AMQP Routing Keys.

Both approaches allow an external system to construct a SECS message by publishing a single JSON object to an AMQP topic. The JSON keys are target descriptors that identify the message parameters within the TransSECS equipment model, and the values are the parameter data.

Each key in the JSON payload is a target descriptor that identifies a parameter in the TransSECS equipment model. The format is:

/<ToolName>/<MessageName>><ParameterName>

For example, for the PRJobCreateEnh (S16F11) message on tool EIHost:

/EIHost/PRJobCreateEnh>DATAID
/EIHost/PRJobCreateEnh>PRJOBID
/EIHost/PRJobCreateEnh>MIDs
/EIHost/PRJobCreateEnh>PRRECIPEMETHOD
/EIHost/PRJobCreateEnh>RCPSPEC
/EIHost/PRJobCreateEnh>PRPROCESSSTART
/EIHost/PRJobCreateEnh>sendMessage

The sendMessage key is special — it triggers the actual SECS message to be sent to the equipment. Its value should be an empty string (“​”).

Most parameters are simple strings. The system interprets the string according to the SECS type defined in the equipment model.

"/EIHost/PRJobCreateEnh>DATAID": "1"
"/EIHost/PRJobCreateEnh>PRJOBID": "TestJob-001"
"/EIHost/PRJobCreateEnh>PRRECIPEMETHOD": "2"
"/EIHost/PRJobCreateEnh>PRPROCESSSTART": "true"

Parameters that correspond to SECS lists (such as MIDs — a list of material IDs) use the JSON object format with a “values” array. You can optionally include a “type” field to specify the SECS data type of the list elements.

"/EIHost/PRJobCreateEnh>MIDs": {"values": ["Wafer01", "Wafer02"], "type": 20}

This creates a SECS list containing two ASCII (type 20) strings. If “type” is omitted, elements default to ASCII strings. See List Format for the full specification of list encodings including mixed types and nested lists.

The PRJobCreateEnh message creates an enhanced process job on the equipment. Its SECS structure is:

S16F11 W
  L [7]
    A DATAID
    A PRJOBID
    A MF
    L [n]           ← MIDs (list of material IDs)
      A MID
      ...
    L [3]
      U1 PRRECIPEMETHOD
      A RCPSPEC
      L [1]
        L [2]
    BOOLEAN PRPROCESSSTART
    L [0]

The corresponding JSON payload is:

{
  "/EIHost/PRJobCreateEnh>DATAID": "1",
  "/EIHost/PRJobCreateEnh>PRJOBID": "TestJob-001",
  "/EIHost/PRJobCreateEnh>MF": "14",
  "/EIHost/PRJobCreateEnh>MIDs": {"values": ["Wafer01", "Wafer02"], "type": 20},
  "/EIHost/PRJobCreateEnh>PRRECIPEMETHOD": "2",
  "/EIHost/PRJobCreateEnh>RCPSPEC": "MyRecipe",
  "/EIHost/PRJobCreateEnh>PRPROCESSSTART": "true",
  "/EIHost/PRJobCreateEnh>sendMessage": ""
}

Note that parameters which are structural (the nested L[3], L[1], L[2], and L[0] in the SECS structure) are managed by the equipment model and do not need to be specified in the JSON. You only set the leaf-level data values.

1. The external system publishes a JSON payload to devices.utilityservers_servers.restemulator.
2. The REST Emulator script iterates over each key/value pair in the JSON.
3. For each pair, it resolves the target descriptor and sets the parameter value on the corresponding server in the TransSECS model.
4. If a sendMessage key is present, the parameter is set (triggering the message send).
5. Errors from individual updates are collected and concatenated.
6. The result is published to devices.utilityservers_servers.restresponse — an empty string if all updates succeeded, or a concatenated error string if any failed.

<WRAP center round warning> The REST Emulator does not guarantee the order in which JSON keys are processed. The JSON specification does not define key ordering, and Java's JSONObject does not preserve insertion order. This means the sendMessage key may be processed before all parameters have been set, resulting in a message being sent with stale or incomplete data. </WRAP>

To mitigate this when using the REST Emulator, split the operation into two separate publishes:

Step 1 — Set parameters (no sendMessage key):

{
  "/EIHost/PRJobCreateEnh>DATAID": "1",
  "/EIHost/PRJobCreateEnh>PRJOBID": "TestJob-001",
  "/EIHost/PRJobCreateEnh>MF": "14",
  "/EIHost/PRJobCreateEnh>MIDs": {"values": ["Wafer01", "Wafer02"], "type": 20},
  "/EIHost/PRJobCreateEnh>PRRECIPEMETHOD": "2",
  "/EIHost/PRJobCreateEnh>RCPSPEC": "MyRecipe",
  "/EIHost/PRJobCreateEnh>PRPROCESSSTART": "true"
}

Step 2 — Trigger the message (only the sendMessage key):

{
  "/EIHost/PRJobCreateEnh>sendMessage": ""
}

Subscribe to devices.utilityservers_servers.restresponse before publishing the request.

The REST Emulator response indicates whether the parameter updates succeeded. It does not contain the SECS reply from the equipment. If you need the equipment's response to the message, use the Message Transaction approach instead.

1. The external system publishes a JSON payload to devices.utilityservers_servers.messagetransaction.
2. The Message Transaction script parses the JSON and identifies the sendMessage key.
3. The sendMessage key is removed from the JSON before processing.
4. The remaining parameters are forwarded to the REST Emulator for bulk update (ensuring all parameters are set first).
5. If the REST Emulator reports errors, those are returned immediately.
6. Otherwise, the script invokes sendMessageAndWait() on the message bean, which sends the SECS message and blocks until the equipment responds.
7. The equipment's SECS reply message is published to devices.utilityservers_servers.messageresponse.

This two-phase approach (set parameters, then send) eliminates the JSON key ordering problem entirely.

Subscribe to devices.utilityservers_servers.messageresponse before publishing the request.

The response will contain the actual SECS reply from the equipment. For example, a PRJobCreateEnh (S16F11) will return the S16F12 acknowledgement. The response content depends on the specific message:

The complete sequence for sending a PRJobCreateEnh via the Message Transaction:

1. Subscribe to devices.utilityservers_servers.messageresponse
2. Publish the JSON payload to devices.utilityservers_servers.messagetransaction:

{
  "/EIHost/PRJobCreateEnh>DATAID": "1",
  "/EIHost/PRJobCreateEnh>PRJOBID": "TestJob-001",
  "/EIHost/PRJobCreateEnh>MF": "14",
  "/EIHost/PRJobCreateEnh>MIDs": {"values": ["Wafer01", "Wafer02"], "type": 20},
  "/EIHost/PRJobCreateEnh>PRRECIPEMETHOD": "2",
  "/EIHost/PRJobCreateEnh>RCPSPEC": "MyRecipe",
  "/EIHost/PRJobCreateEnh>PRPROCESSSTART": "true",
  "/EIHost/PRJobCreateEnh>sendMessage": ""
}

1. Wait for a message on devices.utilityservers_servers.messageresponse
2. Check the response for the acknowledge message (e.g. PRJobCreateEnhAcknowledge)

The HostCommand message sends a remote command to the equipment. Its structure is simpler:

S2F41 W
  L [2]
    A Command
    L [1]
      L [2]
        A PPIDParamName
        A PPIDParamName1

Via Message Transaction (preferred):

{
  "/EIHost/HostCommand>Command": "START",
  "/EIHost/HostCommand>PPIDParamName": "PPID",
  "/EIHost/HostCommand>PPIDParamName1": "recipename",
  "/EIHost/HostCommand>sendMessage": ""
}

Publish to devices.utilityservers_servers.messagetransaction and monitor devices.utilityservers_servers.messageresponse for the reply.

Via REST Emulator (two-step):

Step 1 — set parameters:

{
  "/EIHost/HostCommand>Command": "START",
  "/EIHost/HostCommand>PPIDParamName": "PPID",
  "/EIHost/HostCommand>PPIDParamName1": "recipename"
}

Step 2 — trigger:

{
  "/EIHost/HostCommand>sendMessage": ""
}

Use the Message Transaction when:

• You need to send a SECS message and receive the equipment's reply
• You want guaranteed parameter-then-send ordering in a single publish
• You need to verify the equipment acknowledged the message

Use the REST Emulator when:

• You only need to set parameter values without sending a message
• You want to pre-configure parameters across multiple messages in bulk
• You are performing the two-step (configure, then trigger) pattern explicitly

For most SECS messaging workflows, the Message Transaction is the recommended approach.