Start and monitor command executions

When you want to run the command, you must specify the target device that will receive the command and perform the instructions specified. The target device can either be an AWS IoT thing, or the client ID if the device has not been registered in the AWS IoT registry. After receiving the command payload, the device can start executing the command and perform the specified actions.

AWS IoT thing

The target device for the command can be an AWS IoT thing that you have registered in the AWS IoT thing registry. Things in AWS IoT make it easier to search and manage your devices.

You can register your device as a thing when you connect your device to AWS IoT from the Connect device page or using the CreateThing API. You can find an existing thing for which you want to run the command from the Thing Hub page of the AWS IoT console or using the DescribeThing API. For information about how to register your device as an AWS IoT thing, see Managing things with the registry.

Client ID

If your device hasn't been registered as a thing with AWS IoT, you can use the client ID instead.

The client ID is a unique identifier that you assign to your device or client. The client ID is defined in the MQTT protocol, and it can contain alphanumeric characters, underscores, or dashes. It must be unique to each device that connects to AWS IoT.

The client ID is typically the MQTT client ID that your devices can use when connecting to AWS IoT Core. This ID is used by AWS IoT to identify each specific device and manage connections and subscriptions.

The timeout indicates the duration in seconds within which your device can provide the result of the command execution.

After you create a command execution, a timer starts. If the device went offline or failed to report the execution result within the timeout duration, the command execution will time out, and the execution status will be reported as TIMED_OUT.

This field is optional and will default to 10 seconds if you don't specify any value. You can also configure the timeout to a maximum value of 12 hours.

Time out value and TIMED_OUT execution status

A time out can be reported by both the cloud and the device.

After the command is sent to the device, a timer starts. If there was no response received from the device within the specified time out duration, as described above. In this case, the cloud sets the command execution status as TIMED_OUT with reason code as $NO_RESPONSE_FROM_DEVICE.

This could happen in either of the following cases.

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 now 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 time out occurred when it was executing the command. In this case, the command execution status stays at TIMED_OUT but the statusReason object will be updated based on the information reported by the device. The command execution will now become terminal and no further updates will be 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 time out is configured to a value that exceeds this duration, command executions that run longer than 60 minutes can get rejected by the message broker and it can 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, then 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"
  ]
}

Obtain account-specific data plane endpoint

Before you run the API command, you must obtain the account-specific endpoint URL for the iot:Jobs endpoint. For example, if you run this command:

aws iot describe-endpoint --endpoint-type iot:Jobs

It will return the account-specfic endpoint URL as shown in the sample response below.

{
    "endpointAddress": "<account-specific-prefix>.jobs.iot.<region>.amazonaws.com"
}

Start a command execution example (AWS CLI)

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

In this example, replace:

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --executionTimeoutSeconds 900

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    }
  ]
}

Sample IAM policy for IoT thing

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    }
  ]
}

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:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-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.