Driver Command#

The Driver Command task sends a lifecycle command to the driver instance associated with the workflow: connect to the equipment, disconnect, reconnect, report the result of the setup phase, or return the driver definition currently in use.

Workflows#

Inputs#

Table: Driver Command inputs

Outputs#

Table: Driver Command outputs

Settings#

On the General Tab, you have the usual settings and the following setting:

Table: Driver Command settings

Behavior#

The task sends the selected command only when the driver process is running, the controller is connected to it, and the Equipment Configuration task already sent the driver definition. Otherwise, nothing is sent and the task emits an Error with the message Connection with driver instance was not yet established or it was not yet configured. In practice, run this task after the OnInitialize event of the Driver Event task and the Equipment Configuration task, or after the OnSetup event for the setup commands.

The driver reports every state change through the OnCommunicationChange event of the Driver Event task. Use that event, not the Success output, to know the actual connection state.

Driver Lifecycle#

All drivers follow the communication state model described in Communication Drivers. The timeouts and intervals below are the settings of the Equipment Configuration task.

sequenceDiagram
    participant W as Workflow
    participant D as Driver
    participant E as Equipment
    W->>D: Equipment Configuration
    W->>D: Driver Command "Connect"
    D->>E: Open connection
    Note over D: Connecting (fails after Connecting Timeout)
    E-->>D: Connected
    Note over D: Setup (fails after Setup Timeout)
    D-->>W: Driver Event "OnSetup"
    W->>E: Initialization tasks
    W->>D: Driver Command "SetupSuccess"
    Note over D: Communicating (OnHeartbeat every Heartbeat Interval)
    W->>D: Driver Command "Disconnect"
    D->>E: Close connection
    Note over D: Ready

After Connect, the driver keeps the connection up on its own. When a connection attempt fails, the setup fails, or the equipment drops the connection, the driver waits for the Reconnect Interval and starts a new cycle. Only Disconnect stops this behavior.

Commands#

Connect#

Opens the connection to the equipment and starts the cycle above. If the driver is already Communicating, the request is ignored and the task still emits Success.

Use it after the Equipment Configuration task succeeds, or to resume communication after a Disconnect.

Disconnect#

Closes the connection to the equipment and stops automatic reconnection. The driver ends in the Ready state until a new Connect.

Use it for maintenance windows, to release equipment that accepts a single client, or to stop the driver gracefully before updating the controller.

Reconnect#

Sends Disconnect immediately followed by Connect. The full cycle runs again, including the Setup phase and the OnSetup event.

Use it when the protocol does not detect a broken session, for example, from a workflow that reads a known property on OnHeartbeat and reconnects when the read fails.

SetupSuccess#

Ends the setup phase. The driver moves to Communicating and starts the heartbeat. Send it only in response to the OnSetup event: in any other state the driver logs Ignoring the SetupComplete action because the state is not 'Setup' and keeps its current state, although the task still emits Success.

Use it after the initialization the equipment requires, for example, after enabling event reports on a SECS/GEM equipment or after checking the equipment identification with Get Equipment Properties. If no initialization is needed, enable Automatic Setup on the Driver Event task instead and skip this command.

SetupFailure#

Aborts the setup phase. The driver moves to ConnectingFailed, disconnects from the equipment, and retries after the Reconnect Interval, which raises a new OnSetup event.

Use it when the equipment identification does not match or a mandatory initialization command fails. Not answering within the Setup Timeout has the same effect.

CurrentDefinitions#

Returns the full driver definition the driver is using at that moment on the Reply output. It is read-only and works in any communication state.

Driver Definition#

The drivers' definition is assembled by the controller from three sources, in this order:

1. The Automation Driver Definition associated with the driver. In an extendable controller, this includes the driver definitions inherited from the parent controllers.
2. The built-in templates shipped with the driver package, added only when no element with the same name exists.
3. The templates of the Custom Driver Definition task, which replace elements with the same name. When several tasks define the same element, the last one to run takes precedence.

The controller then resolves the $(Property) and ${Attribute} tokens with the values of the entity linked to the driver instance, for example, a Resource. Tokens are resolved in every text field of a property, event, or command, including its extended data. The controller also parses each ExtendedData JSON text into an object and sorts event properties and command parameters by their Order. Some drivers normalize the result further. For example, the File Raw driver sets the deviceId of properties, events, and commands from their propertyType, eventTrigger, and commandType extended data.

MES shows only the first source. CurrentDefinitions driver command is the only way to see the assembled final result, in the format:

• CamelCase field names
• Resolved tokens
• Extended data as objects

Use it to check what an extendable controller or a Custom Driver Definition task actually produced.

Reply Payload#

The reply for the CurrentDefinitions driver command is an object with the following fields:

Table: CurrentDefinitions reply payload

Every element of these lists has the following fields, where applicable:

Table: Fields of the reply payload elements

The following example shows a reply from a File Raw driver with one property, one event, and one command:

{
    "properties": [
        {
            "systemId": "-1",
            "name": "FileAccessTime",
            "deviceId": "AccessTime",
            "deviceType": "String",
            "dataType": "String",
            "isReadable": true,
            "isWritable": false,
            "extendedData": { "propertyType": "AccessTime" }
        }
    ],
    "events": [
        {
            "systemId": "-1",
            "name": "FileDeleted",
            "deviceId": "DeletedFile",
            "isEnabled": true,
            "properties": [
                {
                    "systemId": "-1",
                    "name": "FileAccessTime",
                    "deviceId": "AccessTime",
                    "deviceType": "String",
                    "dataType": "String",
                    "isReadable": true,
                    "isWritable": false,
                    "extendedData": { "propertyType": "AccessTime", "identifierType": "None" }
                }
            ],
            "extendedData": { "eventTrigger": "DeletedFile" }
        }
    ],
    "commands": [
        {
            "systemId": "-1",
            "name": "FileExists",
            "deviceId": "Exists",
            "parameters": [
                {
                    "systemId": "-1",
                    "name": "path",
                    "deviceType": "String",
                    "dataType": "String",
                    "isMandatory": false,
                    "defaultValue": "/data/archive/file.txt",
                    "extendedData": {}
                }
            ],
            "extendedData": { "commandType": "Exists" }
        }
    ],
    "communication": {
        "connectingTimeout": 30000,
        "setupTimeout": 10000,
        "heartbeatInterval": 60000,
        "intervalBeforeReconnect": 5000
    }
}