Skip to content

Send commands for MindConnect Software Agent

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 and OPC UA plugins. It is possible to write data in the following data types:

  • Integer
  • Long
  • Double
  • Boolean
  • Float
  • String (OPC UA only)

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:

ui-send-commands

The “Type” column represents “Data Acquisition Mode” type and 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:

S7-write-window

Commanding Device via API

In order to command the device, there are 3 critical id’s that needs to be get from the system. Those id’s are deviceId, datasourceId and datapointId. To get the id’s, follow these steps:

Getting deviceId

You can "GET" the "id" of your device using the "id" of your asset with a below request. /api/devicemanagement/v3/devices?assetId={id} In the response, device id will be displayed. For more information, Device Management Service see documentation.

Getting datasourceId and datapointId

In the second step, we need to make a request to mindconnectdevicemanagment service to "GET" the id of the datasource and the datapoint.

/api/mindconnectdevicemanagement/v3/devices/{assetId}/dataConfig

In the response of this request the id’s will be displayed and should be exdtracted for the final api call. Below is the response for the above request. The "id" field in dataSource item represents the datasourceId and the dataPointId represents the "id" of the datapoint.

    {
        "id": "392fe515-5b61-439d-814d-b37b9fa7ef7b",
        "agentId": "25137086d6c141b682d9fcb135c8168e",
        "uploadCycle": "10",
        "configurationId": "1650623649731",
        "dataSources": [
      {
        "id": "326340f5-88c6-409a-a5d9-03e95ce7af94",
        "name": "WindTurbine",
        "description": "datasource_description",
        "protocol": "S7",
        "readCycleInSeconds": "60",
        "protocolData": {
          "ipAddress": "192.168.1.1",
          "manualRackAndSlot": "Automatic",
          "rackNumber": "0",
          "slotNumber": "2"
        },
        "dataPoints": [
        {
            "id": "6efc38d1-b4e7-4e6e-98ce-cb6b3b3f36b2",
            "dataPointId": "36cd56f91c154",
            "name": "Energy",
            "description": "description",
            "unit": "kw",
            "dataType": "DOUBLE",
            "dataPointData": {
            "address": "DB1.DBD1",
            "hysteresis": "0",
            "onDataChanged": false,
            "acquisitionType": "READ"
          }
        }
      ]
    }
  ]
}

The final api call is to deploymentworkflow service. For more information, see Deployment Workflow Service. A "POST" request to the below endpoint should be made,

/api/deploymentworkflow/v3/instances

The body of the request should be, as below example:

    {
      "deviceId": "f5168f95-2cc6-4a2c-b598-bfd5dadfc4df",
      "model": {
        "key": "mdsp-core-commandDispatcher"
      },
      "data": {
      "type": "datapoint-write",
      "createdBy": "user@siemens.com",
      "version": "v1.0",
      "to": "some_protocol",
      "payload": {
        "desiredValue": "7",
        "dataSourceId": "10d9c36c-69f7-4c33-8624-f67537e142a4",
        "dataPointId": "b932b9da42f04",
        "protocol": "some_protocol"
      }
    }
}

In the below list, there are some fields which require certain data only:

Field Name Allowed Values
to OPCUA, S7
protocol OPCUA, S7
version v1.0
type datapoint-write
key mdsp-core-commandDispatcher

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 the 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 oldest 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, for example a command is sent for a "READ" typed datapoint.
  • Boolean type is only working strictly for ‘true’ and ‘false’ values.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.


Last update: September 29, 2022