Skip to end of metadata
Go to start of metadata


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.

On this page ...


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 DescriptionA 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
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 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 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, which 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 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 TimeoutThe 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 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, which 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 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 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.

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

Equipment

StringThe 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 NameDatatypeDescription

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 NameDatatypeDescription

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 ConnectionThe 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. 





  • No labels