opcua_server_integration_guide [ErgoTech Systems, Inc. TechWiki]

This is an old revision of the document!

Integration Guide for TransSECS OPCUA and OPCDA Servers

Starting the OPCUA or OPCDA Server

Use the run.bat or run.sh file generated for the server deployment. This will start a command shell or terminal.

Tag Names

The OPCUA or OPCDA server will generate tags prefaced by your toolname. For the examples in this guide the tool name is “GEMTool”. The tags will be grouped into .vids, .ceids, .alids, and .messagenames. Within the .vids will be each vid (svid or ecid) by .name. For each alid and ceid, there will be an enable (not usually used except for testing) and a trigger.

Set the SVIDs OnlineOfflineState and LocalRemoteState to “true” (enabled) for testing.

Use your OPCUA or OPCDA Client to set both of these vids to “true” so that the test Host may connect to the tool for testing. These VIDs are normally set with a hardware or software (GUI) switch or button on the tool.

Triggering Messages

SECS messages are sent to the host by first setting the data values in the message, if any, then setting the sendmessage tag of the outgoing message to a non-zero value. Before sending the message set the “responsestatus” tag to a value > 10. This response status value will change after the message is triggered to a value reflecting the success of the sent message. A “0” indicates success. Other values indicate an error.

JSON is used to format the list elements of a message, for example, a list of recipe names for an S7F20 message. These will all be strings in a JSON format. Per the JSON standard, all keys should be quoted, as you will see in the examples below.

For example, S7F20 for the recipe list, if you have defined the message with an empty list you will see a hint in the OPCUA Server. The OPC Tag corresponding to the recipe list will look something like:

{ "values": [ ] }

in your OPCUA or OPCDA client you will make a string of the recipe names in this format and write it to the tag for this list.

For example, it might look like:

{ "values": [ "recipe1","recipe2", "recipe3", "recipe4"] }

then send the message as usual using the trigger data item.

There are more things you can do with the JSON format for the lists, including making lists of lists and specifying the SECS format for the data in the list. See the JSON Hints below.

Receiving Messages

When a message is received the data values from the incoming message will appear in the message tags. If you have defined a Host Message generically with an empty parameter list, the received list data can be parsed as a JSON string to get the host command parameters.

ECID value updates

When the host sends an S2F15 message with a ECID value changes, the tag corresponding to the ecidname (that you defined in TransSECS) will be automatically updated with the value. The ECID tags are in the toolname.vids branch.

Important Note On Initial Values of ECIDs

When the OPCUA or OPCDA server starts up these values will not have been initialized by the client or host yet, and they will all be “0” and bad quality. Make sure that when your Client reads these values that you only accept quality “good” data to update your client. As soon as your Client writes an initial value to the server the quality will become good, or if the host writes new values in an S2F15 message the quality will also be good.

Updating SVIDs

The OPCUA Client should update the SVID data values in the toolname.vids tags.

Triggering Alarms (ALIDs)

Use the boolean “trigger” data item for the toolname.alids.alidname to trigger an alarm. The alarm will not be sent to the host unless the host has enabled the alarm. The ALCD and Enabled tags for the alarm are exposed in the OPC Server but should not be used by the Client except for testing purposes.

Triggering Events (CEIDs)

SECS Events are triggered by setting the

toolname.ceids.eventname.trigger

value with a String. The event will only be sent from the tool if the host has enabled this event. The enabled tag is exposed but should not be set by the Client except for testing purposes.

For a simple CEID, without using DVIDs, the event is triggered by an empty string value (or a string containing only spaces). If the CEID was defined with DVIDs, the string should contain a JSON formatted list of DVID values, for example:

{  "values":[
    { "dvid":"WaferCount", "dvval":"15"  },
    { "dvid":"ProcessProgram",  "dvval":"25SecDip"  }
 ] }

More JSON Hints

Some reference notes on JSON as it applies to TransSECS (SECS formats and list structures)

If a specific type is required, it can be specified if needed. For example for the recipe list, the data is ASCII, type 20:

 { "values": [ "recipe1","recipe2", "recipe3", "recipe4"], "type":"20" }

type is per the SECS Standard:

00 - List
10 - Binary (can be an array)
11 - Boolean
20 - String
30 - 8 byte floating point
34 - 4 byte floating point
40, 41, 42, 44 - 8, 1,2,4 byte signed integers
50, 51, 52, 54 - 4 byte signed integer

each element of the array can have a different type in this format (might be useful in some message replies with different data types):

 {"values":[
      {"value":"1.2", "type":"34"},
      {"value":"Test", "type":"20"},
      {"value":["5","6","7","8"], "type":"10"},
      {"value":"1", "type":"10"}
   ]
 }

Events can be triggered with a list of DVVALS if DVIDs have been associated with the event. To do this you can define the list, then use this as the trigger input to the CEID. If you are using DVVALs in your tool project you would associate the DVVALS when you define your CEID (you may have noticed this list if you have DVVALS, this is a recent change to TransSECS).

Example of DVVALS as a JSON String sent to the trigger of a CEID:

{  "values":[
    { "dvid":"WaferCount", "dvval":"15"  },
    { "dvid":"23456",  "dvval":"Hello World"  }
 ] }

Another note: You can specify any VID with either its name (for example WaferCount), or its vid number (for example 23456) as the above example demonstrates.

Example, Host Command

If you publish the whole of the data from a host command, the structure is a list (with the host command), then the list elements for the parameters for the command.

It may look something like:

 { "values": [  { "value":"PP-SELECT", "type":"20" } } { "values": [  { "values": [ "LOTID" ] , "type":"20" } { "values": [  { "value":"CHAMBER", "type":"20 } } { "value":"1", "type":"51" } } ]  } { "values": [ "PPID" ] , type:"20" } ]  } ]  }

Host commands received from the host are order independent, that is, the OPC Tag corresponding to the parameter name will be updated with the correct value regardless of the position in the message from the host.

Equipment TransSECS/GEM IDs

Some IDs required by GEM or by TransSECS are automatically added to a TransSECS equipment project when you add the VIDS node. These variable as case sensitive. All these variable must be present in the project. OnlineOfflineState and LocalRemoteState require an interface at the tool. MDLN and SOFTREV should be set but once set require no further attention. All other variable can be left at the default.

The OnlineOfflineState and LocalRemoteState are the most important variables. According to the standard you must provide a way (physical or logical button) for the operator to toggle between online/offline and local/remote. When OnlineOfflineState is offline there is no SECS communication. When OnlineOfflineState is online the host can successfully request to go online. When LocalRemoteState is local the host can monitor the tool but not send commands that will cause motion or control the tool in any way. The GEM spec is ambiguous as to what to do if the host sends a request to control the tool while in online local. If you set the SxF0InOnlineLocal to true, then the tool will return an SxF0 message (for example an S2F0 response to an S2F41 message). The state of the tool is report in the ControlState and LastControlState variables.

MDLN and SOFTREV are required by GEM and report in the S1F2 (as well as other places). The MDLN is a description of the tool and the SOFTREV the software revision number. These you should populate approriately. Until recently both MDLN and SOFTREV were limited to 6 characters. The recent standards now allow for 20 characters. You can put the parameter

SOFTREV.20Char=true

in the ErgoTechConfiguration.properties file and this will extend the variable to be 20 characters (allowed by the latest standards). However, it's possible that many older hosts expect that string to be only 6 and will fail on a 20 character value so I would not (yet) recommend that you make this change and TransSECS defaults to 6 characters.

Configuration Variables

If EventReportsReplyBit or S5F1ReplyBit are false, the event and alarm messages will be sent to the host without the “wait” bit set - meaning that they do not expect a response. The response to both these messages is unused - the standard does not require (or therefore permit) an intelligent behavior - such as resending on missing or error response. However, the industry standard is to send these messages expecting a reply and that's the default.

EventReportFunction if this value is 11 an “Event Report” (S6F11) will be sent if 13 an “Annotated Event Report” (S6F13) will be sent

EstablishCommunicationsTimeout is used by the SECS “active” connection - you should not normally set this. By default the tool is the “passive” connection - listening for a connection from the host. If this is non-zero the tool will attempt to contact the host. This variable defines how often that attempt should be made.

TimeFormat controls whether the data/time will be reported to the host as 12 or 16 bytes. If TimeFormat is 1 the date/time will be reported as “yyMMddHHmmss” if 2 the date/time will be reported with the full 4-digit year and centisecond precision - “yyyyMMddHHmmssSS”. The default is 1 - 12 byte.

PersistenceFilename If the persistencefilename String not blank (such as “GEMToolPersistence.xml”), this filename will be used to create a GEM model persistence record and will be updated whenever any GEM settings are changed in the tool, including alarm status, event status, report definitions, etc. which can be used to initialize the tool upon startup. Connection parameters such as HSMS Port and Device ID are not stored in this file, nor are the online/offline and local/remote state vids.

When the tool is started this peristence file will not be used until the OPC Client has written the name of this file into the toolname.configuration.persistencefilename tag. Therefore the recommended procedure for startup when using persistence will be to write to the filename to this tag as soon after tool startup as possible, usually as very soon after the OPC Client makes a connection to the OPC Server. When this filename String is written, and it matches an existing filename in the local file system, then model stored in this file will be imported and applied to the model in the tool. If the entered persistencefilename is a new filename, this will be used to create a new persistence record which will be updated as the GEM model in the tool changes.

Variables Populated by TransSECS. Do not write to these variables

CommunicationsState this is defined by the standard to be one of:

NOT_COMMUNICATING = 1
EQUIPMENT_INITIATED_CONNECT = 2
EQUIPMENT_INITIATED_CONNECT_WAIT_CRA =
EQUIPMENT_INITIATED_CONNECT_WAIT_DELAY = 4
HOST_INITIATED_CONNECT = 5
WAIT_CR_FROM_HOST = 6
COMMUNICATING = 7

7 - Communicating, indicates a good connection from a host.

ControlState and LastControlState report the control state of the tool. This is defined by the standard to be one of

EQUIPMENT_OFFLINE = 1
ATTEMPT_ONLINE = 2
HOST_OFFLINE = 3
LOCAL_ONLINE = 4
REMOTE_ONLINE = 5

The ControlState variable is controlled by the OnlineOfflineState and LocalRemoteState variables and the host. This variable should never be changed directly.

EventsEnabled provides a list of enabled events. AlarmsSet and AlarmsEnabled provide an array of set/enabled alarms - you do not need to do anything with any of these.

CLOCK provides the current time in the format defined by the TimeFormat variable.

SpoolCountActual, SpoolCountTotal, EnableSpooling, MaxSpoolTransmit, MaxSpoolSize, OverwriteSpool, SpoolStartTime, SpoolFullTime control the behavior of spooling as defined in the GEM standard.