Start and monitor command executions

Specify the target device to receive and execute the Command. Use a Thing name for registered devices or Client ID for unregistered devices. After receiving the Payload, the device executes the Command and performs specified actions.

AWS IoT thing

Target devices can be Things registered in the AWS IoT registry. Things simplify device search and management.

Register devices as Things from the Connect device page or using CreateThing. Find existing Things from Thing Hub or using DescribeThing. See Managing things with the registry for registration details.

Client ID

For unregistered devices, use the Client ID.

The Client ID is a unique identifier you assign to devices. Defined in the MQTT protocol, it contains alphanumeric characters, underscores, or dashes. Each device connecting to AWS IoT needs a unique Client ID.

The Client ID is the MQTT client ID devices use when connecting to AWS IoT Core. AWS IoT uses this ID to identify devices and manage connections and subscriptions.

Timeout specifies the duration (in seconds) for devices to provide Execution results.

After creating an Execution, a timer starts. If the device goes offline or fails to report results within timeout, the Execution times out with status TIMED_OUT.

Default: 10 seconds. Maximum: 12 hours.

Time out value and TIMED_OUT execution status

Both cloud and device can report timeout.

After sending the Command, a timer starts. If no device response arrives within timeout, the cloud sets Execution status to TIMED_OUT with reason code $NO_RESPONSE_FROM_DEVICE.

This occurs when:

In this instance, when the execution status of TIMED_OUT is reported from the cloud, the command execution is non-terminal. Your device can publish a response that overrides the status to any of the terminal statuses: SUCCEEDED, FAILED, or REJECTED. The command execution then becomes terminal and doesn't accept any further updates.

Your device can also update a TIMED_OUT status initiated by the cloud by reporting that a timeout occurred when it was executing the command. In this case, the command execution status remains at TIMED_OUT, but the statusReason object is updated based on the information reported by the device. The command execution then becomes terminal, and no further updates are accepted.

Using MQTT persistent sessions

You can configure MQTT persistent sessions to use with the AWS IoT Device Management commands feature. This feature is especially useful in cases such as when your device goes offline and you want to make sure that the device still receives the command when it comes back online before the timeout duration, and performs the instructions specified.

By default, the MQTT persistent session expiry is set to 60 minutes. If your command execution timeout is configured to a value that exceeds this duration, command executions that run longer than 60 minutes can be rejected by the message broker and fail. To run commands that are longer than 60 minutes in duration, you can request an increase to the persistent session expiry time.

To start running the command from the console, go to the Command Hub page of the AWS IoT console and perform the following steps.

Use the StartCommandExecution HTTP data plane API operation to start a command execution. The API request and response are correlated by the command execution ID. After the device completes executing the command, it can report the status and execution result to the cloud by publishing a message to the commands response topic. For a custom response code, application codes that you own can process the response message and post the result to AWS IoT.

If your devices have subscribed to the commands request topic, the StartCommandExecution API will publish the payload message to the topic. The payload can use any format of your choice. For more information, see Command payload.

$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

If the payload format is not JSON or CBOR, the following shows the format of the commands request topic.

$aws/commands/<devices>/<DeviceID>/executions/+/request

Sample IAM policy

Before you use this API operation, make sure that your IAM policy authorizes you to perform this action on the device. The following example shows an IAM policy that allows the user permission to perform the StartCommandExecution action.

In this example, replace:

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

To see a list of condition keys supported for StartCommandExecution, see Condition Keys for AWS IoT in the IAM User Guide.

Obtain account-specific data plane endpoint

Before you run the API command, you must obtain the account-specific endpoint URL for the endpoint. If you're using dual-stack endpoints (IPv4 and IPv6), use the iot:Data-ATS. The iot:Jobs endpoint is for IPv4 only. For example, if you run this command:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

It returns the account-specific endpoint URL as shown in the sample response below.

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

Start a command execution example (AWS CLI)

The following example displays how to start executing a command using the start-command-execution AWS CLI command.

In this example, replace:

Running this command returns a command execution ID. You can use this ID to query the command execution status, details, and command execution history.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

Before you use this API operation, make sure that your IAM policy authorizes your device to perform these actions. Following shows an example policy that authorizes your device to perform the action. For additional sample IAM policies that allow the user permission to perform the UpdateCommandExecution MQTT action, see Connect and publish policy examples.

In this example, replace:

Sample IAM policy for MQTT client ID

The following code shows a sample device policy when using MQTT client ID.

Sample IAM policy for IoT thing

The following code shows a sample device policy when using an AWS IoT thing.

After the command execution is received at the request topic, the device processes the command. It then uses the UpdateCommandExecution API to update the status and result of the command execution to the following response topic.

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

In this example, <DeviceID> is the unique identifier of your target device, and <execution-id> is the identifier of the command execution on the target device. The <PayloadFormat> can be JSON or CBOR.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

Device reported updates to execution status

Your devices can use the API to report any of the following status updates to the command execution. For more information about these statuses, see Command execution status.

For more information about the TIMED_OUT status, see Time out value and TIMED_OUT execution status.

Considerations when using the UpdateCommandExecution API

The following are some important considerations when using the UpdateCommandExecution API.

UpdateCommandExecution API example

The following code shows an example of how your device can use the UpdateCommandExecution API to report the execution status, the statusReason field to provide additional information about the status, and the result field to provide information about the result of the execution, such as the car battery percentage in this case.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

You can retrieve a command execution from the console using either of the following methods.

Use the GetCommandExecution AWS IoT Core control plane HTTP API operation to retrieve information about a command execution. You must have already executed this command using the StartCommandExecution API operation.

Sample IAM policy

Before you use this API operation, make sure that your IAM policy authorizes you to perform this action on the device. The following example shows an IAM policy that allows the user permission to perform the GetCommandExecution action.

In this example, replace:

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Retrieve a command execution example

The following example shows you how to retrieve information about a command that was executed using the start-command-execution AWS CLI command. The following example shows how you can retrieve information about a command that was executed to turn off the steering wheel mode.

In this example, replace:

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

Running this command generates a response that contains information about the ARN of the command execution, the execution status, and the time when it started executing, and when it completed. It also provides a statusReason object that contains additional information about the status. For more information about the different statuses and status reason, see Command execution status.

The following code shows a sample response from the API request.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
        "reasonDescription": "SUCCESS"
    },
    "result": {
        "sn": { "s": "ABC-001" },
        "digital": { "b": true }        
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00"    
}

You can see all the command executions from the console using either of the following methods.

Use the ListCommandExecutions AWS IoT Core control plane HTTP API operation to list all command executions in your account.

Sample IAM policy

Before you use this API operation, make sure that your IAM policy authorizes you to perform this action on the device. The following example shows an IAM policy that allows the user permission to perform the ListCommandExecutions action.

In this example, replace:

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

List command executions example

The following example shows you how to list command executions in your AWS account.

When running the command, you must specify whether to filter the list to display only command executions that were created for a particular device using the targetArn, or executions for a particular command specified using the commandArn.

In this example, replace:

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

Running this command generates a response that contains a list of command executions that you created, and the time when the executions started executing, and when it completed. It also provides status information, and the statusReason object that contains additional information about the status.

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

For more information about the different statuses and status reason, see Command execution status.

Before you use this API operation, make sure that your IAM policy authorizes your device to perform these actions. Following shows an example policy that authorizes your device to perform the action.

In this example, replace:

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

The following example shows you how to delete a command using the delete-command AWS CLI command. Depending on your application, replace <execution-id> with the identifier for the command execution that you're deleting, and the <target-arn> with the ARN of your target device.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

If the API request is successful, then the command execution generates a status code of 200. You can use the GetCommandExecution API to verify that the command execution no longer exists in your account.