Send commands

The commanding functionality provides you to send data directly from cloud applications and from MindSphere applications to your devices. The first example of this functionality was remote restart. The send command functionality is extended to cover writing data to the field via S7 plugin. It is possible to write data in the following data types:

  • Integer

  • Long

  • Double

  • Boolean

  • Float

WARNING

It is important to know the limitations of your devices, before you set a specific value for a datapoint.

Failure to check value ranges within your controllers may result in damages to your devices. We recommend to set and verify limits within your local program to block values out of device limits.

User interface

The following screen shows the data source configuration screen:

139260026763.png

The type column provides the following values:

Value

Description

Read

Within this type you can only collect data.

Write

Within this type you can only send data.

Read&Write

Within this type you can collect and send data.

The "Send a value" button is only visible on writeable data point types. This creates a command instance on cloud platform on Edge area for execution.

The "Log" column shows the general result of the latest operation made on the data point itself. For more information you can click on the data point name on the left hand side and view the details of the executed command.

The following screen shows the "Send value" detailed screen with the entry of the value to be written to the data point:

139262279563.png

Check written device data via API

You can check the list of the created commands via official API of Deployment Workflow’s endpoint GET /instances. The following call is an example of the request:

/api/deploymentworkflow/v3/instances?deviceId={id}&modelKey=mdsp-core-commandDispatcher

You will receive the following response:

139262343563.png

This example shows the details of the command e.g. when it is created or by whom it is created. The result also shows the status of the command and the value being written to the device.

Write data to a device via API

It is also possible to create commands to the device side by using API calls. The other endpoint again on Deployment Workflow POST /instances

/api/deploymentworkflow/v3/instances

The following template shows the payload of the call:

{

"deviceId": "string",

"model":{https://workspace.sips.siemens.com:4003/Themes/CustomControls/Viewlets/CloseBtn.gif

"key": "mdsp-core-commandDispatcher",

"customTransitions": [

{

"from": "CREATED",

"to": "EXECUTE",

"type": "BACKEND_TRIGGER",

"details": null

},

{

"from": "EXECUTE",

"to": "CANCELED",

"type": "BACKEND_TRIGGER",

"details": null

},

{

"from": "EXECUTING",

"to": "CANCELED",

"type": "BACKEND_TRIGGER",

"details": null

}

]

},

"data": {

"type": "datapoint-write",

"createdBy": "string",

"version": "v1.0",

"payload": {

"protocol": "S7",

"desiredValue": "string",

"dataSourceId": "string",

"dataPointId": "string"

}

}

The following list shows the details of the commanding functionality:

  • If command operation fails, then the box will set the state of the job to FAILED indicating some more details in the message column of the command itself. On the other hand, the state of the job will be EXECUTED if command operation succeeded. These updated states can be checked via Deployment Workflow’s endpoint GET /instances too.

  • The commanding operations are executed in a chronological order, starting first from the eldest to the newest. The execution of those commands is synchronized with the configuration updates to avoid inconsistencies between the device side content and cloud side content.

    • In order to keep the device configuration content up to date with the backend side do not forget to click the "Apply changes" button. Otherwise, some of your commands will get rejected by the device side if for example a command is sent for a READ typed datapoint.

  • Boolean type is only working strictly for ‘true’ and ‘false’ values.