Skip to content

Send commands for MindConnect Software Agent

The commanding functionality provides you to send data directly from cloud applications and from Insights Hub 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 and is also supported for advanced driver protocols IEC61850, S7+ and Sinumerik. It is possible to write data in the following data types:

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

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.
  • If there is an ongoing command for the datapoint, the user will not be allowed to create a new one until the ongoing specific datapoint is finalized.

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.

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, IEC61850, S7PLUS, SINUMERIK
protocol OPCUA, S7, IEC61850, S7PLUS, SINUMERIK
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.

Last update: February 16, 2024