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.

📘

Device Shadow

BioT uses the device's IoT shadow to send commands. To learn how to communicate with the shadow first, click here.

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

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.

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