Sending Commands

BioT sends Start and Stop command messages to the device, indicating that an operator has requested to execute a command on the device. During the command execution, the device is expected to send updates.
Each command has a unique name that appears in the topic name used to communicate with the device about this specific command.

📘

Note

The clientId in the following topics is configured in the device during the activation stage. See Direct Device Connection.

Start a Command

To start a command, the device needs to listen to the following topic:

$aws/things/<clientId>/shadow/name/<commandName>/update/delta

Message structure:

{
  "version": 1,
  "timestamp": 1661174307,
  "state": {
    "metadata": {
      "context": "eyJjb21tYW5kSWQiOiI2MTkzMTIwMy00MWRiLTQ2ODUtYWRjOS1mM2U1ODBmZWRhYzYifQ==",
      "state": "ACTIVE"
    },
    "data": {
      <CustomConfigurationAttributes>
    }
  },
  "metadata": {
    "metadata": {
      "context": {
        "timestamp": 1661174307
      },
      "state": {
        "timestamp": 1661174307
      }
    },
    "data": {
      "message": {
        "timestamp": 1661174307
      }
    }
  }
}
ParameterDescriptionFormat
contextA unique string representing the command.String
stateIndicates if the command should start or stop.String
Possible values: ACTIVE / IDLE
CustomConfigurationAttributesCustom configuration attributes defined in the command template and sent to the device as part of the command initial executionkey: value
Example:
"algo1": true,
"feature1": 17.5

To acknowledge, send an ACK message to the following topic:

$aws/things/<clientId>/shadow/name/<commandName>/update

ACK Message structure (note the “reported” section):

{
    "state": {
        "reported": {
          "metadata": {
             "context": "eyJjb21tYW5kSWQiOiI0MmM1Zjk0OC1iNWQzLTQyYzMtYjNiZi02YmYzMTI5NjcyYjgifQ==",
           "state": "ACTIVE"
       },
          "data": {
            <CustomConfigurationAttributes>
          }
      }
   }
}

The ACK message will include all the parameters sent in the start command message.

Stopping a Command

A device can stop a command after it was completed successfully or after failure to execute.
It does so by updating the command shadow with completionState and optionally the errorMessage attributes.

ParameterDescriptionFormat
completionStateThe command completion state.String
Possible values: COMPLETED/ ABORTED
errorMessageOptional failure message when completionState is set to ABORTEDString

Command Success

To stop a command successfully, send the following message to the topic:

$aws/things/<clientId>/shadow/name/<commandName>/update

{
  "state": {
    "reported": {
      "metadata": {
        "completionState": "COMPLETED"
      }
    }
  }
}

Command Failure

To stop a command after a failure, send the following message to the topic:

$aws/things/<clientId>/shadow/name/<commandName>/update

{
  "state": {
    "reported": {
      "metadata": {
        "completionState": "ABORTED",
        "errorMessage": "The device failed to execute the command"
      }
    }
  }
}

What’s Next