**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.  [[ModbusDevicesExample_OnlineOffline_LocalRemote|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 <file>SOFTREV.20Char=true</file> 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.

<code javascript>
var GemHandler = Java.type("com.ergotech.secs.gem.GemHandler");
GemHandler.setS1F3ReturnsValues(true);
</code>