Skip to main content
Version: 8.1

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 NameDescriptionDefault
Equipment NameThe name to give this equipment connection.-
Equipment Description -A description of this equipment connection.-
EnabledWhether the equipment connection is enabled or disabled. A disabled equipment connection will prevent communication between the Gateway and the equipment.TRUE
Device IDA unique identifier of the equipment, which is defined by the equipment. Must be an integer.0
Database ConnectionThe Database Connection that will be used to store messages in for audit purposes as well as some configuration data.-
Database Table PrefixThe 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) FileThe 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 TimeoutThe number of seconds to wait for an expected SECS message reply.45

Properties for Equipment Connections using the Ethernet/HSMS Connection Type

This type connects to equipment using HSMS over TCP.

Property NameDescriptionDefault
Active IP AddressIP Address of the equipment to connect to when in Active mode.localhost
Active PortThe 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 AddressIP Address of the equipment to connect to when in Passive mode.localhost
Passive PortThe Port number that an Equipment will connect to if the SECS/GEM module is in passive mode.5000
Connection ModeThe 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 TimeoutThe number of seconds which must elapse between successive attempts to connect to the equipment after disconnection.10
T6 Control Transaction TimeoutThe 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 TimeoutThe 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 TimeoutThe 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 TimeoutThe 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

This type connects to equipment serially using SECS-I.

Property NameDescriptionDefault
Serial Port NameThe name of the serial port, e.g. "COM1" or "/dev/ttyS0".COM1
Data Bit RateThe 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 TimeoutThe maximum number of seconds allowed for interruptions between characters being sent.0.5
T2 Protocol TimeoutThe maximum number of seconds for a lack of protocol response.10
T4 Inter-Block TimeoutThe maximum number of seconds allowed for interruptions in multi-block messages.45
Retry LimitThe 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 NameDatatypeDescription
EquipmentStringThe name of the equipment
PrefixStringThe prefix that the equipment connection uses for its unique tables.
StatusStringThe status of the equipment connection.
SDL FileStringThe 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 NameDatatypeDescription
IDAuto incrementing PrimaryID, IntegerThe ID of the row.
EquipmentStringThe name of the equipment.
StreamFunctionStringThe Stream and Function such as "S1F1".
DirectionStringWhether the message was received or sent.
RequestResponseStringWhether the message was a request or a response.
CommonIDStringA special identifier that will link together multiple related messages.
TxIDIntegerThe transaction ID of the message.
ReplyIntegerWhether the message expects a reply or not.
MessageStringThe JSON string message.
TimeSentReceivedDateTimeA 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 NameDatatypeDescription
IDAuto incrementing PrimaryID, IntegerThe ID of the row.
EquipmentStringThe name of the equipment.
StreamFunctionStringThe Stream and Function such as "S1F1". Only used if the error is related to a SECS Message
ErrorTypeStringThe type of error that occurred, such as Connection Error, Timeout, or JSON Syntax Error.
ErrorStringThe error message.
TimeDateTimeThe 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 Config 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. Make sure the Active Port matches 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.

    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.