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
      }
    }
  }
}

Parameter

Description

Format

context

A unique string representing the command.

String

state

Indicates if the command should start or stop.

String
Possible values: ACTIVE / IDLE

CustomConfigurationAttributes

Custom configuration attributes defined in the command template and sent to the device as part of the command initial execution

key: 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.

Parameter

Description

Format

completionState

The command completion state.

String
Possible values: COMPLETED/ ABORTED

errorMessage

Optional failure message when completionState is set to ABORTED

String

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"
      }
    }
  }
}

Did this page help you?