SECS/GEM Equipment Connections

Connection Types

Equipement connections can be created using one of two different connection types: Ethernet through a TCP/IP network, or Serial using an RS-232 serial cable. Each uses a different protocol to communicate.

Ethernet Connections

Ethernet connections use the HSMS protocol for communication. The name of the standard for HSMS is SEMI E37, and are much faster than serial connections. The SECS/GEM module enables ethernet connections automatically and are the preferred method of connection.

Serial Connections

Serial connections use the SECS-I protocol for communication. The name of the standard for SECS-I is SEMI E4. To use a serial connection, the Serial Support Gateway Module must be installed in addition to the SECS/GEM module. The equipment must also have a direct serial connection to the Ignition Gateway server.

Equipment Connection Properties

When setting up an equipment connection through either ethernet or serial, there are various properties that can be configured.

Common Properties

Property Name	Description	Default
Equipment Name	The name to give this equipment connection.
Equipment Description	A description of this equipment connection.
Enabled	Whether the equipment connection is enabled or disabled. A disabled equipment connection will prevent communication between the Gateway and the equipment.	TRUE
Active IP Address	IP Address of the equipment to connect to when in Active mode.	localhost
Active Port	The Port number of the equipment to connect to when in Active mode, which must match the port number used to create the Simulaor.	5000
Passive IP Address	IP Address of the equipment to connect to when in Passive mode.	localhost
Passive Port	The Port number of the equipment to connect to when in Passive mode, which must match the port number used to create the Simulaor.	5000
Connection Mode	The Method used to connect to Equipment. ACTIVE- Will attempt to connect to the equipment at the given Active IP Address and Active Port. PASSIVE - Will listen for a connection from the equipment at the given Passive IP Address and Passive Port. ALTERNATING - Will switch between Active mode and Passive mode until a connection is made.	ACTIVE
Device ID	A unique identifier of the equipment, which is defined by the equipment. Must be an integer.	0
Database Connection	The Database Connection that will be used to store messages in for audit purposes as well as some configuration data.
Database Table Prefix	The prefix that will be prepended to each of the database table names that get automatically setup when the connection is made. Used to help differentiate one equipment's tables from another equipment's tables. If no prefix is specified, then no prefix will be used.
SECS Definition Language (SDL) File	The file that validates SECS messages sent and received between the Gateway and the equipment. If none is specified, a default messages.sdl file is used. See SECS Definition Language (SDL) File for the default file.	messages.sdl
T3 Reply Timeout	The number of seconds to wait for an expected SECS message reply.	45

Properties for Equipment Connections using the Ethernet/HSMS Connection Type

Connects to equipment using HSMS over TCP.

Property Name	Description	Default
Active IP Address	IP Address of the equipment to connect to when in Active mode.	localhost
Active Port	The Port number of the equipment to connect to when in Active mode, which must match the port number used to create the Simulaor.	5000
Passive IP Address	IP Address of the equipment to connect to when in Passive mode.	localhost
Passive Port	The Port number of the equipment to connect to when in Passive mode, which must match the port number used to create the Simulaor.	5000
Connection Mode	The Method used to connect to Equipment. ACTIVE- Will attempt to connect to the equipment at the given Active IP Address and Active Port. PASSIVE - Will listen for a connection from the equipment at the given Passive IP Address and Passive Port. ALTERNATING - Will switch between Active mode and Passive mode until a connection is made.	ACTIVE
T5 Connect Separation Timeout	The number of seconds which must elapse between successive attempts to connect to the equipment after disconnection.	10
T6 Control Transaction Timeout	The number of seconds which a control transaction (such as LinkTest or Select) may remain open before it is considered a communications failure.	5
T7 Not Selected Timeout	The number of seconds which a TCP/IP connection can remain in NOT SELECTED state (i.e. no HSMS activity) before it is considered a communications failure. This timeout is only used for Passive Connection Mode.	10
T8 Network Intercharacter Timeout	The maximum number of seconds between successive bytes of a single HSMS message before it is considered a communications failure. This applies to HSMS messages received from the equipment.	5
Keep Alive Timeout	The number of seconds interval for sending LinkTest control messages for testing a connection. Automatically reconnects if the test fails. A value of 0 will disable it.	300

Properties for Equipment Connections using the Serial/SECS-I Connection Type

Connects to equipment serially using SECS-I.

Property Name	Description	Default
Serial Port Name	The name of the serial port, e.g. "COM1" or "/dev/ttyS0".	COM1
Data Bit Rate	The bit rate of data that is being sent and received. Possible values are: BR_9600 BR_4800 BR_2400 BR_1200 BR_19200 BR_150	BR_9600
T1 Inter-Character Timeout	The maximum number of seconds allowed for interruptions between characters being sent.	0.5
T2 Protocol Timeout	The maximum number of seconds for a lack of protocol response.	10
T4 Inter-Block Timeout	The maximum number of seconds allowed for interruptions in multi-block messages.	45
Retry Limit	The maximum number of send retries allowed.	3

Database Tables

Regardless of the type of equipment connection, database tables are created for each connection based on the prefix specified in the connection if they do not already exist.

caution

No automatic maintenance (such as pruning or partitioning) is performed on these tables. Some of the tables can grow quite large, so it is up to the user to properly manage each set of tables from each equipment connection.

SECSGEM_EquipmentInfo Table

The SECSGEM_EquipmentInfo table is unique in that only one will get created for all databases that use the same database connection and will not use a prefix in its name. Each row of the SECSGEM_EquipmentInfo table contains information about a specific Equipment Connection.

SECSGEM_EquipmentInfo

Column Name	Datatype	Description
Equipment	String	The name of the equipment
Prefix	String	The prefix that the equipment connection uses for its unique tables.
Status	String	The status of the equipment connection.
SDL File	String	The SDL File that was uploaded for this equipment connection. If no file was uploaded, it will use the default messages.sdl.

Messages Table

The Messages table is where SECS messages are stored after they are sent or received. It will include a prefix in the name if one was specified in the equipment connection. Multiple equipment connections can use the same prefix which will have them write to the same messages table. Because this table records every message between the Gateway and equipment, it can grow quite large.

prefixMessages

Column Name	Datatype	Description
ID	Auto incrementing PrimaryID, Integer	The ID of the row.
Equipment	String	The name of the equipment.
StreamFunction	String	The Stream and Function such as "S1F1".
Direction	String	Whether the message was received or sent.
RequestResponse	String	Whether the message was a request or a response.
CommonID	String	A special identifier that will link together multiple related messages.
TxID	Integer	The transaction ID of the message.
Reply	Integer	Whether the message expects a reply or not.
Message	String	The JSON string message.
TimeSentReceived	DateTime	A datetime value of when the message was sent or received.

Errors Table

Any errors that occur are logged to the Errors table. It will include a prefix in the name if one was specified in the equipment connection. Multiple equipment connections can use the same prefix which will have them write to the same errors table.

prefixErrors

Column Name	Datatype	Description
ID	Auto incrementing PrimaryID, Integer	The ID of the row.
Equipment	String	The name of the equipment.
StreamFunction	String	The Stream and Function such as "S1F1". Only used if the error is related to a SECS Message
ErrorType	String	The type of error that occurred, such as Connection Error, Timeout, or JSON Syntax Error.
Error	String	The error message.
Time	DateTime	The date and time when the error occurred.

Creating an Equipment Connection

In order to communicate with an equipment or the built-in simulator, an Equipment Connection must be configured in the Gateway. This example walks you through configuring an equipment connection for a piece of equipment.

1. Go to the Configure section of the Gateway webpage and select SECS/GEM > Equipment.
2. On the Equipment Connections page, click on Create new Equipment Connection....
3. On the Add Equipment Connection Step 1: Choose Type page, select Ethernet/HSMS Connection, and click Next.
4. On the Equipment Connection page:
   1. Equipment Name - enter equipment name, (i.e., EquipOne).
   2. Enabled - set to 'true'. Enables communication to the target equipment.
   3. Active IP Address - use the default of localhost, or enter the IP address of equipment to connect to when in Active mode.
   4. Active Port - set the port number (i.e., 5007). The Active and Passive port numbers must be unique for each piece of equipment. Note, the Active Port must match the port number used in the equipment or simulator configuration setup.
   5. Passive IP Address - use the default of localhost, or enter the IP address of the equipment to connect to when in Passive mode.
   6. Passive Port - set the port number (i.e., 5007). The Active and Passive port numbers must be unique for each piece of equipment. Note, the Passive Port must match the port number used in the equipment or simulator configuration setup.
   7. Connection Mode - the default is set to Active. The Connection Mode is a property that is configured in both the Simulator and Equipment Connection settings, and cannot be set to the same method. Alternating mode can be used, in which case, it will switch between Active and Passive modes until a connection is made.
   8. Device ID - enter an equipment ID (i.e. 1). Each piece of equipment must have a unique ID.
   9. Database Connection - enter the database that will be used to send and receive data (i.e, SecsGem).
   10. Database Table Prefix - enter a prefix to prepend to the database table names. (i.e. EquipOne_). A prefix will be prepended to each of the database table names that are automatically setup when the connection is made. This is an optional setting, so if no prefix is specified, the table will still get created. The advantage of using a prefix is it helps keep database tables organized, and used to differentiate one equipment's tables from another equipment's tables. It also allows you to filter a project based on the prefix.
   11. SECS Definition Language (SDL) File - the default file is messages.sdl. Validates sent and recieved messages.

5. Once all the configuration settings are entered, click on the Create new Equipment Connection. The window will refresh showing a status of "Connecting" until the equipment connection is created. When the status changes to "Communicating", the Equipment Connection is successfully created.