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. TransSECS Devices example of using Modbus 0x (Coil) Registers for these VIDs.
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 reported 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.
S1F3 Returns Values
An early version of SECS/GEM erroneously returned the values of the SVIDs in a response to an empty S1F3 rather than the IDs as required by the standard. This error has been propagated and still exists in some implementations. Returning values is incorrect and counterintuitive. For example, there is no definition of the order in which they should be reported. Returning the IDs, as required by the standard, allows the iteration of the IDs to find values.
To emulate the behavior of returning values add this code to a script that is called before any S1F3. This need only be called once.
var GemHandler = Java.type("com.ergotech.secs.gem.GemHandler"); GemHandler.setS1F3ReturnsValues(true);