--- alias: user-guide-driver-secsgem tags: - connect iot description: "This documentation details the SECS/GEM driver for connecting to industrial equipment, facilitating data exchange within a manufacturing environment" --- # Connect IoT - SECS/GEM Driver The SECS/GEM is the semiconductor's equipment interface protocol for equipment-to-host data communications. In an automated fab, the interface can start and stop equipment processing, collect measurement data, change variables and select recipes for products. The SECS (SEMI Equipment Communications Standard)/GEM (Generic Equipment Model) standards do all this in a defined way. The Connect IoT SECS/GEM driver is the implementation of the SECS/GEM driver for a Critical Manufacturing MES environment. For more information, see this [Guide](). ## Data Types These are the supported specific data types: Name | Description ----------- |------------------------- U1 | Unsigned integer 1 byte U2 | Unsigned integer 2 bytes U4 | Unsigned integer 4 bytes U8 | Unsigned integer 8 bytes I1 | Signed integer 1 byte I2 | Signed integer 2 bytes I4 | Signed integer 4 bytes I8 | Signed integer 8 bytes F4 | Float 4 bytes F8 | Float 8 bytes (double) A | ASCII value (text string) BI | Binary value BO | Boolean value L | List Table: SECS/GEM specific data types !!! note All types (except for L) also support arrays ## Protocol Parameters The protocol supports the following parameters, used to define the communication parameters, as well as the expected behavior of the driver: Name | Type | Possible Values | Default Value | Description -------------------- | ------- | --------------- | ------------- | ------------ autoConfigure | Boolean | | `true` | Automatically establish communications, set online and configure the equipment (reports, events, alarms, links) customLibrary | String | | `""` | Enter the full path of a custom library in `xsc` file format with the customized SECS/GEM transactions. Leave empty to use the default library. Note: Communication attempts will fail if the library file is not found. variableIdType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `U4` | Type of variable Id (used when linking/requesting/setting values) reportIdType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `U4` | Type of report Id (used when creating/deleting/linking) alarmIdType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `U4` | Type of alarm Id (used when enabling/disabling) eventIdType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `U4` | Type of event Id (used when enabling/disabling/linking) dataIdType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `U4` | Type of data Id (used on all messages containing DATAID items) commandType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `A` | Type of command (used when sending command name, aka 'RCMD') commandParameterNameType | Enum | U1
U2
U4
U8
I1
I2
I4
I8
F4
F8
A
BI
BO | `A` | Type of command parameter name (used when sending commands, aka 'CPNAME') netCoreSdkVersion | String | | | This will indicate the exact version of the .net core sdk to use when instancing a version of the driver protocol | Enum | HSMS
RS232
TCP | `HSMS` | Protocol used to connect to the equipment connectionMode | Enum | Active
Passive | `Active` | (`HSMS`) Mode used for connection
`Active` means the equipment must be acting as a server and the integration as client
`Passive` means the integration works as a server and the machine as client networkAddress | String | | 127.0.0.1 | (`HSMS`) Address of the remote connection (Active mode) or Address of the local connection (Passive mode) networkPort | Integer | | 5000 | (`HSMS`) Port of the remote connection (Active mode) or Port of the local connection (Passive mode) serialPortName | String | | | (`Serial/TCP`) COM port name to use autoBaudRate | Boolean | | `true` | (`Serial/TCP`) Automatic adjust the Baud Rate isSecsHost | Boolean | | `true` | (`Serial/TCP`) Define who plays the role of the Host baudRate | Integer | | 9600 | (`Serial/TCP`) Connection Speed (bps) t1 | Integer | | 1 | (`Serial/TCP`) T1 Timeout (seconds) t2 | Integer | | 1 | (`Serial/TCP`) T2 Timeout (seconds) t3 | Integer | | 60 | T3 Timeout (seconds) t4 | Integer | | 15 | T4 Timeout (seconds) t5 | Integer | | 10 | (`HSMS`) T5 Timeout (seconds) t6 | Integer | | 10 | (`HSMS`) T6 Timeout (seconds) t7 | Integer | | 10 | T7 Timeout (seconds) t8 | Integer | | 10 | T8 Timeout (seconds) linkTestInterval | Integer | | 60 | (`HSMS`) Interval for testing link (seconds) monitorEnabled | Boolean | | `false` | Secs/Gem underlying communication debug mode deviceId | Integer | | 0 | Identifier of the device retryLimit | Integer | | 1 | (`Serial/TCP`) Maximum number of retries allowInterleave | Boolean | | `true` | (`Serial/TCP`) Message ordering mode allowMultipleOpen | Boolean | | `true` | (`Serial/TCP`) Allow Multiple messages requested allowDuplicatedBlocks | Boolean | | `true` | (`Serial/TCP`) Allow duplicated messages deleteReportsMode | Enum | DeleteAllCreatedReports
DeleteCreatedReportsOneByOne
DeleteAllReports
DeleteNothing | `DeleteAllCreatedReports` | Method used for deleting reports during the setup phase
`DeleteAllCreatedReports` Delete all reports with the same Id as the ones being created all in the same message
*DeleteCreatedReportsOneByOne* Delete all reports with the same Id as the ones being created each one on a separated message
*DeleteAllReports* Delete all reports present in the machine enableDisableEventsMode | Enum | DisableAllEnableSelection
EnableAllDisableSelection
EnableDisableNothing| `DisableAllEnableSelection` | Define behavior regarding enabling/disabling events during setup phase
*DisableAllEnableSelection* Disable all events first, then enable the ones enabled in the driver definition
`EnableAllDisableSelection` Enable all events, then disable only the ones disabled in the driver definition enableDisableAlarmsMode | Enum | DisableAllEnableSelection
EnableAllDisableSelection
EnableDisableNothing| `DisableAllEnableSelection` | Define behavior regarding enabling/disabling alarms during setup phase
`DisableAllEnableSelection` Disable all events first, then enable the ones enabled in the driver definition
`EnableAllDisableSelection` Enable all events, then disable only the ones disabled in the driver definition Table: SECS/GEM specific parameters ## Extended Parameters ### Property All **Automation Properties** defined in the *Driver Definition* that use this protocol will have the following extended (extra) attributes available to customize | Name | Type | Possible Values | Default Value | Description | | ------------ | ---- | ------------------------------------------ | -------------- | ------------------------------------------------------------ | | variableType | Enum | DataVariable
StatusVariable
Constant | `DataVariable` | Secs/Gem variable type. Based on the variable type, Setting/Getting values of the properties will yield different Secs/Gem messages | Table: SECS/GEM specific extended properties ### Event All **Automation Events** defined in the *Driver Definition* that use this protocol will have the following extended (extra) attributes available to customize | Name | Type | Possible Values | Default Value | Description | | ------- | ------- | --------------- | ------------- | ------------------------------------------ | | isAlarm | Boolean | | `false` | Identify this event as an alarm in SecsGem | Table: SECS/GEM specific extended events ### Event Property All **Automation EventProperty** defined in the *Driver Definition* that use this protocol will have the following extended (extra) attributes available to customize | Name | Type | Possible Values | Default Value | Description | | ------------- | ------- | ------------------ | ------------- | --------------------------------------------- | | reportId | String | | | Id of the report to link with the event (blank means auto generated). Use this property to force a report identifier. This is necessary if the machine as pre-defined reports that cannot be changed.| ### Command All **Automation Command** defined in the *Driver Definition* that use this protocol will have the following extended (extra) attributes available to customize | Name | Type | Possible Values | Default Value | Description | | --------------- | --------------- | --------------- | ------------- | --------------------------------------------------- | | messageType | Enum | S2F41
S2F49 | `S2F41` | Stream/Function of message to use for the command | | successAckCodes | Array of Values | | [0x00, 0x04] | List of reply codes that can be accepted as success | Table: SECS/GEM specific command ## Initial configuration flow When connection is requested and the **autoConfigure** configuration is set, the following message exchange is performed to configure the equipment: * Establish Communication (`S1F13`) * Expect `S1F14` with 0x00 ACK * Set Online (`S1F17`) * Expect `S1F18` with 0x00 or 0x02 ACK * Delete Reports (`S2F33`) based on `deleteReportsMode` setting * Expect `S2F34` with 0x00 ACK * Define Reports (`S2F33`) * Expect `S2F34` with 0x00 ACK * Link Events with reports (`S2F35`) * Expect `S2F36` with 0x00 ACK * Enable/Disable events (`S2F37`) based on `enableDisableEventsMode` setting * Expect `S2F38` with 0x00 ACK * Enable/Disable alarms (`S5F3`) based on `enableDisableAlarmsMode` setting * Expect `S5F4` with 0x00 ACK ## Driver Extensions This protocol driver provides a set of extension that allow the customization to perform actions that are independent of the Driver Definitions associated. This means you can, using customization, register events that are not present in the Driver Definition. > This is particularly useful when accessing equipment data that is shared/too complex to access using the regular mechanisms. Also useful when needing to access data whose naming convention may vary from device to device. ## Objects The objects are structures that are either passed as parameters or returned as result values. ### RegisterHandler | Name | Type | Possible Values | Description | | ---- | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | type | String | | SECS/GEM transaction name (primary message) to register. Example: `S1F13` | | mode | `HandlerMode` | `None`
`NotifyOnly`
`HandleReply`
`HandleFullProcess` | Behavior for the handler:
`None`: No handling at all. Everything is processed by the driver. Not even notifications are sent.
`NotifyOnly`: Just be notified of message. Both handling and reply will be handled by driver.
`HandleReply`: Driver is responsible for handling the message, Customization is responsible for reply (driver will not reply directly to equipment)
`HandleFullProcess`: Customization is responsible for processing message and reply | Table: SECS/GEM specific handler registration ### UnregisterHandler | Name | Type | Description | | ---- | ------ | ------------------------------------------------------------ | | type | String | Id of the event to unregister notifications. Example: `S1F13` | Table: SECS/GEM specific handler unregistration ### SecsMessage | Name | Type | Mandatory | Description | | ----------- | ---------- | --------- | ------------------------------------------------------------ | | name | String | No | Name of the message to send | | description | String | No | Description of the message | | type | String | Yes | SECS/GEM message type using the format `SxFy`. Example `S1F13`. | | item | `SecsItem` | Yes/No | Root node of the message. If not used, message present in the library will be used. | Table: SECS/GEM specific SecsMessage ### SecsItem | Name | Type | Possible Values | Mandatory | Description | | ------- | ------ | ------------------------------------------------------------ | --------- | ----------------------------------- | | type | String | `U1`, `U2`, `U4`, `U8`, `I1`, `I2`, `I4`, `I8`, `F4`, `F8`, `A`, `BI`,`BO` | Yes | Data type of SECS/GEM item | | name | String | | No | Name of the item | | comment | String | | No | Comment to add to the item | | value | any | | Yes | Value of the item (can be an array) | Table: SECS/GEM specific SecsItem ### SecsTransaction | Name | Type | Description | | ----------- | ------------- | ------------------------------------------------------------ | | id | String | Id of the message. Unique during the communication lifetime. | | systemBytes | Buffer | Message Id according to SECS/GEM. Host and Equipment have their own numbering and can be duplicated | | needsReply | Boolean | Flag indicating if the message requires a reply to be sent | | primary | `SecsMessage` | Message received | | secondary | `SecsMessage` | Template of the reply that will be sent | Table: SECS/GEM specific SecsTransaction ## Methods ### Register Handler Notifies the protocol driver to raise the occurrences of a specific SECS/GEM message type when it occurs. `void connect.iot.driver.secsgem.registerHandler(data: RegisterHandler)` !!! note The events will be published to the listener `connect.iot.driver.secsgem.receivedMessage.` appended with the type registered. Example: `connect.iot.driver.secsgem.receivedMessage.S1F13` #### Example Notify `connect.iot.driver.secsgem.registerHandler` ```json { "type": "S1F13", "mode": "HandleFullProcess" } ``` ### Unregister Handler Notifies the protocol driver to stop raising the occurrences of a specific message when it occurs. `void connect.iot.driver.secsgem.unregisterHandler(data: UnregisterHandler)` ### Example Notify `connect.iot.driver.secsgem.unregisterHandler` ```json { "type": "S1F13" } ``` ### Send Message Sends a message (or reply) to the equipment. `any connect.iot.driver.secsgem.sendMessage (data: SecsMessage)` ### Example SendRequest `connect.iot.driver.secsgem.sendMessage` ```json { "type": "S1F13", "item": { "type": "L", "value": [ { "type": "A", "name": "MLDN", "value": "Equipment TopModel" }, { "type": "A", "name": "SOFTREV", "value": "Software Rev 1.0" } ] } } ``` #### Example (Reply) SendRequest `connect.iot.driver.secsgem.sendMessage` ```json { "type": "REPLY_1234567890", "content": { "type": "S1F14", "item": { "type": "BI", "name": "COMMACK", "value": 0x00 } } } ``` ### Internal Delete Reports Sends the message Delete Reports (`S2F33`) based on `deleteReportsMode` setting. This is used if you desire to send some custom handshake flow. `bool connect.iot.driver.secsgem.internalDeleteReports()` ### Internal Define Reports Sends the message Define Reports (`S2F33`). This is used if you desire to send some custom handshake flow. `bool connect.iot.driver.secsgem.internalDefineReports()` ### Internal Link Events Sends the message Link Events with reports (`S2F35`). This is used if you desire to send some custom handshake flow. `bool connect.iot.driver.secsgem.internalLinkEvents()` ### Internal Enable Disable Events Sends the message Enable/Disable events (`S2F37`) based on `enableDisableEventsMode` setting. This is used if you desire to send some custom handshake flow. `bool connect.iot.driver.secsgem.internalEnableDisableEvents()` ### Internal Enable Disable Alarms Sends the message Enable/Disable alarms (`S5F3`) based on `enableDisableAlarmsMode` setting. This is used if you desire to send some custom handshake flow. `bool connect.iot.driver.secsgem.internalEnableDisableAlarms()` ## Events ### connect.iot.driver.secsgem.receivedMessage.* Events are raised only if registered first. The content of the event is of type `SecsTransaction`, where the values will vary depending on the event that was triggered. The full name of the event triggered will have appended the full name of the event previously registered. Example (assuming the message `S1F13` was previously registered using `registerHandler`): ```json { "id": "1234567890", "systemBytes": [0x00, 0x01, 0x02, 0x03], "needsReply": true, "primary": { "type": "S1F13", "item": { "type": "L", "value": [ { "type": "A", "name": "MLDN", "value": "Equipment TopModel" }, { "type": "A", "name": "SOFTREV", "value": "Software Rev 1.0" } ] } }, "secondary": { "type": "S1F14", "item": { "type": "BI", "name": "COMMACK", "value": 0x00 } } } ``` To send a reply (and replace the template reply) for this message, use Publish/SendRequest `connect.iot.driver.secsgem.sendMessage` ```json { "type": "REPLY_1234567890", "content": { "type": "S1F14", "item": { "type": "BI", "name": "COMMACK", "value": 0x01 } } } ```