Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Commands concepts and status

Use Amazon IoT Commands to send instructions from the cloud to connected devices. To use this feature:

For more information about this workflow, see High-level commands workflow.

Commands key concepts

The following key concepts help you understand the Commands feature. Terms are used consistently throughout this documentation:

Parameter value conditions

When creating commands with payload templates, define value conditions to validate parameter values before execution. Value conditions ensure parameters meet requirements, preventing invalid executions.

Supported operators by CommandParameterValue type

Example: Temperature control command

{
  "commandId": "SetTemperature",
  "namespace": "AWS-IoT",
  "payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}",
  "parameters": [
    {
      "name": "temperature",
      "type": "INTEGER",
      "valueConditions": [
        {
          "comparisonOperator": "IN_RANGE",
          "operand": {
            "numberRange": {
              "min": "60",
              "max": "80"
            }
          }
        }
      ]
    }
  ]
}

In this example, the temperature parameter must be between 60 and 80 (inclusive). Execution requests with values outside this range fail validation.

Parameter value priority and evaluation

When starting command executions with payload templates, parameter values are resolved using the following priority:

Value conditions are evaluated on the final parameter value derived above on the priority and before execution creation. If validation fails, the execution request returns an error.

Example: SetTemperature command with defaultValue

{
  "parameters": [
    {
      "name": "temperature",
      "type": "INTEGER",
      "defaultValue": {"I": 72},
      "valueConditions": [
        {
          "comparisonOperator": "IN_RANGE",
          "operand": {"numberRange": {"min": "60", "max": "80"}}
        }
      ]
    }
  ]
}

When starting execution:

Command states

Commands in your Amazon Web Services account can be in one of three states: Available, Deprecated, or Pending deletion.

Command execution status

When you start an execution on a target device, it enters CREATED status and can transition to other statuses based on device reports. You can retrieve status information and track executions.

The following table shows execution statuses and their transitions based on execution progress.

Devices can publish status and result updates anytime using commands reserved MQTT topics. To provide additional context, devices can use reasonCode and reasonDescription fields in the statusReason object.

The following diagram shows execution status transitions.

The following sections describe terminal and non-terminal executions and their statuses.

Non-terminal command executions

An execution is non-terminal if it can accept updates from devices. Non-terminal executions are considered Active. The following statuses are non-terminal:

Terminal command executions

An execution becomes terminal when it no longer accepts updates from devices. The following statuses are terminal. Executions can transition to terminal statuses from any non-terminal status: CREATED, IN_PROGRESS, or TIMED_OUT.