Commands concepts and status

Commands are instructions that are sent from the cloud to your IoT devices. These instructions (command payload) are sent to the devices as MQTT messages. After the devices receive the command payload, they can process the instructions to take the corresponding action. Examples of such actions include modifying device configuration settings, transmitting sensor readings, or uploading logs. The devices can then run the command and return the result to the cloud. This enables you to remotely monitor and control connected devices.

When you use the commands feature, you can specify the namespace for the command. When you want to create a command in AWS IoT Device Management, you must use the default AWS-IoT namespace. When you use this namespace, you must provide a payload when creating the command. The payload will be used when you run the command on your target device. If you want to create a command for AWS IoT FleetWise instead, you must use the AWS-IoT-FleetWise namespace instead. For more information, see Remote commands in the AWS IoT FleetWise developer guide for commands.

When you create the command, you must provide a payload that defines the actions the device must perform. The payload can use any format of your choice. To make sure that the device can correctly read and understand the information that you're sending, we recommend that you specify the payload format type in the command. If your devices use MQTT5, they can follow the MQTT standard to identify the payload format. A format indicator for JSON or CBOR will be available in the commands request topic.

When you want to run the command, you must specify a target device that will receive the command and perform actions. If your device has been registered as a thing with AWS IoT, you can use the thing name. If your device hasn't been registered, you can use the MQTT client ID instead. The client ID is a unique identifier for your device or client defined in the MQTT protocol. It can be used to connect your device to AWS IoT.

A command execution is an instance of a command that runs on the target device. When you start the execution, the command (payload) is delivered to the target device. A unique command execution ID is now generated for the target. The device can then execute the command and report its progress to AWS IoT. The device-side logic determines how the command will be executed and how the status gets published to the reserved topics.

Before you run the command, your device must have subscribed to the commands request topic. When you send the request to the cloud to execute the command, the payload will be sent to the device on the commands request topic. After the device executes the command, it can publish the result and status of the execution to the commands response topic. For more information, see Commands topics.

After you've successfully created a command resource, it will be in an available state. The command can now be used to send a command execution to the device.

If you no longer intend to use a command, you can mark it for deprecation. In this state, you cannot send any new executions of the command to your devices. Any pending executions that had already started will continue running on the device to completion. To send new executions, you must restore the command so that it becomes available.

When you mark a command for deletion, if the command has been deprecated for a duration that's longer than the maximum timeout, the command will be deleted automatically. This action is permanent and can't be undone. By default, the maximum timeout duration is 12 hours. If the command isn't deprecated, or has been deprecated for a duration shorter than the maximum timeout, the command will be in a pending deletion state. The command will be removed automatically from your account after the maximum timeout duration.