# Device commands Device commands When you are building an IoT application, you need the ability to interact with your device through commands remotely. For example: + In the industrial vertical, remote commands are used to request specific data from a piece of equipment. + In the smart home vertical, remote commands are used to schedule an alarm system remotely. With AWS IoT Core, you can use the bi-directional MQTT protocol to implement command and control of devices. The device subscribes to a specific command MQTT topic. When the device receives a command message, it should verify that the message arrived in the correct order by implementing a sequential ID. The device should then perform the action, and publish a message to the cloud with the results of the command. This makes sure that commands are acted upon in order, and the device's current state is consistently known and maintained in the cloud. ![\[Using a message broker to send commands to a device.\]](http://docs.aws.amazon.com/wellarchitected/latest/iot-lens/images/image3.png) # AWS IoT Device Management Commands AWS IoT Device Management Commands AWS IoT Device Management Commands feature enables customers to send remote commands to IoT devices at scale, facilitating remote monitoring, control and diagnostics. Devices subscribe to MQTT topics to receive user-defined payload from the cloud. The commands feature support delivering messages to reserved MQTT topics and for added flexibility, the target resource can be either a ThingName or a ClientID (for devices not registered in the IoT registry). Each command is a reusable AWS resource that supports granular permissions controls — you can authorize users to send specific commands targeting individual devices. If a command execution needs to be initiated within a specific time frame, you can configure them to expire after a defined timeout period. You have full visibility into command execution through status tracking, and you can optionally configure notifications to be alerted when the command state changes. Command is well suited for remotely sending specific instructions, triggering actions or modifying device configurations on-demand. Common use cases include retrieving device logs, initiating changes to device states, and allowing end users to remotely control devices through web application or a companion app, such as turning lights on and off or starting the air conditioner or fan. To send commands using Commands feature, see the following diagram: ![\[Sending commands to devices using AWS IoT Device Management Commands feature\]](http://docs.aws.amazon.com/wellarchitected/latest/iot-lens/images/image4.png) 1. A device subscribes to the commands topic ` $aws/commands/things//executions/#/request ` or ` $aws/commands/clients//executions/#/request ` upon which IoT commands payload will be delivered. 1. Create pre-defined commands and store them in AWS IoT Device Management Commands for reusability. 1. A user initiates a commands execution through user application, which publishes command payload to the request topic. 1. The device performs the actions specified by the commands execution. 1. The device publishes command execution progress and updates status through ` $aws/commands/things//executions//response ` or ` $aws/commands/clients//executions//response ` topic. 1. Commands publish update notifications through `$aws/events/commandExecutions//#`. The user can configure AWS IoT rules to receive notifications optionally. # AWS IoT Device Shadow service Service AWS IoT Device Shadow service Service AWS provides a feature called AWS IoT Device Shadow services to implement command and control over MQTT using these best practices. The Device Shadow has several benefits over using standard MQTT topics, such as a clientToken, to track the origin of a request, version numbers for managing conflict resolution, and the ability to store commands in the cloud in the event that a device is offline and unable to receive the command when it is issued. The device's shadow is commonly used in cases where a command needs to be persisted in the cloud even if the device is currently not online. When the device is back online, the device requests the latest shadow information and executes the command. IoT solutions that use the Device Shadow service in AWS IoT Core manage command requests in a reliable, scalable, and straightforward fashion. The Device Shadow service follows a prescriptive approach to both the management of device-related state and how the state changes are communicated. This approach describes how the Device Shadows service uses a JSON document to store a device's current state, desired future state, and the difference between current and desired states. ![\[Using Device Shadow with devices\]](http://docs.aws.amazon.com/wellarchitected/latest/iot-lens/images/image5.png) 1. The device should check its desired state as soon as it comes online by subscribing to the \$1aws/things/<>/shadow/name/<>/get topic. A device reports initial device state by publishing that state as a message to the update topic \$1aws/things/<>/shadow/name/<>/update. 1. The Device Shadow reads the message from the topic and records the device state in a persistent data store. 1. A device subscribes to the delta messaging topic \$1aws/things/<>/shadow/name/<>/update/delta upon which device-related state change messages will arrive. 1. A component of the solution publishes a desired state message to the topic \$1aws/things/<>/shadow/name/<>/update and the Device Shadow tracking this device records the desired device state in a persistent data store. 1. The Device Shadow publishes a delta message to the topic \$1aws/things/<>/shadow/name/<>/update/delta, and the Message Broker sends the message to the device. 1. A device receives the delta message and performs the desired state changes. 1. A device publishes an acknowledgment message reflecting the new state to the update topic \$1aws/things/<>/shadow/name/<>/update and the Device Shadow tracking this device records the new state in a persistent data store. 1. The Device Shadow publishes a message to the \$1aws/things/<>/shadow/name/<>/update/accepted topic. 1. A component of the solution can now request the updated state from the Device Shadow. **AWS IoT Device Management Jobs for device commands** In addition to the features described above for device commands, customers can also use AWS IoT Jobs to create a command pipeline, where the device infers the command from the payload of the MQTT message, as opposed to the topic. This enables customers to perform new kinds of remote operations with minimal device-side code changes. You can control the rate of roll-outs using Jobs, and provide abort / retry / timeout criteria to further customize the behavior of the job. AWS IoT Jobs integrates with Fleet Indexing and Thing Groups, which allows you to search your fleet and target devices in your fleet that meet specific criteria. With Job Templates, you can pre-define device-commands and create a library of reusable commands with just a few clicks on the target of your choice. # Firmware updates Firmware updates Supporting firmware upgrades without human intervention is critical for security, scalability, and delivering new capabilities. AWS IoT Device Management provides a secure and straightforward way for you to manage IoT deployments including executing and tracking the status of firmware updates. AWS IoT Device Management uses the MQTT protocol with AWS IoT message broker and AWS IoT Jobs to send firmware update commands to devices, as well as to receive the status of those firmware updates over time. AWS IoT Jobs also integrates with AWS Code Signer to provide additional security to help prevent unauthorized firmware updates and man in the middle attacks. Firmware images can be signed with a private key in the cloud using the code signing feature, and the device verifies the integrity of that firmware image with the corresponding public key. To implement firmware updates using AWS IoT Device Management and AWS IoT Jobs, see the following diagram. ![\[Updating firmware on devices\]](http://docs.aws.amazon.com/wellarchitected/latest/iot-lens/images/image6.png) 1. A device subscribes to the IoT job notification topic \$1aws/things/<>/jobs/notify-next upon which IoT job notification messages will arrive. 1. A device publishes a message to \$1aws/things/<>/jobs/start-next to start the next job and get the next job, its job document, and other details including states saved in statusDetails. 1. The AWS IoT Jobs service retrieves the next job document for the specific device and sends this document on the subscribed topic \$1aws/things/<>/jobs/start-next/accepted. 1. A device performs the actions specified by the job document using the \$1aws/things/<>/jobs/jobId/update MQTT topic to report on the progress of the job. 1. During the upgrade process, a device downloads firmware using a pre-signed URL for Amazon S3. Use code-signing to sign the firmware when uploading to Amazon S3. By code-signing your firmware the end-device can verify the authenticity of the firmware before installing. FreeRTOS devices can download the firmware image directly over MQTT to alleviate the need for a separate HTTPS connection. 1. The device publishes an update status message to the job topic \$1aws/things/<>/jobs/jobId/update reporting success or failure. 1. Because this job's execution status has changed to final state, the next IoT job available for execution (if any) will change.