--- alias: user-guide-automation-task-core-driver-command tags: - automation tasks description: "This documentation details the Driver Command task, the driver lifecycle commands it sends, and the CurrentDefinitions reply that returns the driver definition in use" --- # Driver Command :iot-driver-command-lg:{style="font-size: 100px"} 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. ![Driver Command task settings with the Connect command selected](../images/driver_command_connect.png) !!! note "Related Tasks" This task results from a split of the Equipment Setup and Equipment Setup Result tasks. Use it along with [[user-guide-automation-task-core-equipmentconfig]] and [[user-guide-automation-task-core-driver-event]]. ## Workflows | Data Flow | Control Flow | | :--------: | :---------: | | :material-check:{ style="color: #4DB6AC" } | :material-check:{ style="color: #4DB6AC" } | ## Inputs | Name | Data Type | Description | | -------- | --------- | ------------------ | | Activate | `any` | Sends the configured command to the driver. | Table: Driver Command inputs ## Outputs | Name | Data Type | Description | | ------- | --------- | ------------------------------------------------------ | | Reply | `Object` | The driver definition in use. Only available when `Command` is `CurrentDefinitions`. See [Reply Payload](#reply-payload). | | Success | `Boolean` | Emits `true` after the command is sent to the driver. It does not mean the equipment is already connected or disconnected. | | Error | `Error` | Emits the error when the driver is not ready to receive commands or rejects the command. | Table: Driver Command outputs ## Settings On the *General Tab*, you have the usual settings and the following setting: | Name | Data Type | Default | Description | | ------- | --------- | --------- | -------------------- | | Command | `Enum` | `Connect` | Lifecycle command to send. See [Commands](#commands). | 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 [[user-guide-automation-protocol-protocols-index]]. The timeouts and intervals below are the settings of the **Equipment Configuration** task. ```mermaid 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 [[user-guide-extend-automation-controller|extendable controller]], this includes the driver definitions inherited from the parent controllers. 1. The built-in templates shipped with the driver package, added only when no element with the same name exists. 1. The templates of the [[user-guide-automation-task-core-customtemplates]] 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. !!! info "Troubleshooting Failed Commands" When the driver never raises an event or the equipment rejects a command, compare the element's `deviceId` and `extendedData` in the reply with what the equipment expects. A template may have overridden them, or the driver may have normalized them. ### Reply Payload The reply for the `CurrentDefinitions` driver command is an object with the following fields: | Field | Data Type | Description | | --------------- | ---------- | -------------------------------------------------------------------- | | `properties` | `Object[]` | Properties known to the driver. | | `events` | `Object[]` | Events the driver can raise. Each event carries its own `properties` list. | | `commands` | `Object[]` | Commands the driver accepts. Each command carries its `parameters` list. | | `communication` | `Object` | Communication parameters in use: the generic ones sent by the **Equipment Configuration** task (`connectingTimeout`, `setupTimeout`, `heartbeatInterval`, `intervalBeforeReconnect`) plus the protocol-specific ones. | Table: CurrentDefinitions reply payload Every element of these lists has the following fields, where applicable: | Field | Applies to | Description | | -------------- | ----------------------------------- | --------------------------------------------------------------------------- | | `systemId` | All | ID of the element in MES. It is `"-1"` for elements added by templates. | | `name` | All | Name of the element. | | `deviceId` | Properties, events, commands | Identifier in the equipment, after token replacement and driver normalization. | | `deviceType` | Properties, parameters | Data type in the equipment, as defined by the protocol. | | `dataType` | Properties, parameters | Data type in MES, for example, `String` or `Integer`. | | `isReadable`, `isWritable` | Properties | Whether the driver can read or write the property. | | `isEnabled` | Events | Whether the event is enabled. | | `isMandatory`, `defaultValue` | Parameters | Whether the parameter is required and the value sent when the workflow provides none. | | `extendedData` | All | Protocol-specific attributes. For a property inside an event, it also merges the extended data of the event-property link. | 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: ```json { "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 } } ```