Applications on AWS - Designing MQTT Topics for AWS IoT Core

Applications on AWS

The following sections provide use cases for implementing MQTT topic best practices using AWS IoT.

AWS IoT Shadow Example

In this example, an administrator is sending a command to a wind turbine to change the current angle of the turbine blade to accommodate an approaching wind change. To do so, the administrator first leverages the AWS IoT Shadow as the primary mechanism for issuing commands to a device and as a storage location for essential device readings related to the device.

This scenario assumes the following details:

  • The wind turbine as a thing name of turbine8000

  • The administrator is leveraging an internal application which he is authorized to use with temporary IAM permissions scoped to turbine8000

  • The administrator has a session identifier of session-admin100

Command Request to Wind Turbine Device Shadow

The administrator publishes a message to the IoT Shadow using the reserved MQTT Shadow topic for turbine8000. The command payload includes setting the desired state of the shadow. For tracking purposes, the administrator also embeds a session identifier as the clientToken in the IoT Shadow request.

Command request to wind turbine device shadow

Figure 5: Command request to wind turbine device shadow

Command Processing On Wind Turbine

When using the shadow, the end device is responsible for subscribing to several different MQTT topics to receive the appropriate notifications from the AWS IoT Shadow Service. At a minimum, make sure devices subscribe to the update/delta, update/rejected, get/accepted, and get/rejected reserved Shadow Topics to receive successful and unsuccessful shadow requests.

Figure 6: Command processing on wind turbine

In the example, the wind turbine receives a message on update/delta that the reported state is different than the desired state. Before processing the command, the wind turbine checks the clientToken field to determine the sender of the request. Then, it inspects the timestamp field in the metadata. (For some use cases, commands should only be deemed valid for a given period of time.) Once confirmed, the wind turbine adjusts its blade angle and publishes a response with a new reported state using the update topic.

Command Response Delivered to Administrator

For the administrator to receive updates on reported state changes, the administrative UI subscribes to the update/accepted and update/rejected topics. Once the turbine has published its updated state to the IoT Shadow, the administrator receives an acknowledgment of the updated messages on the update/accepted topic.

Figure 7: Wind turbine publishes update to device shadow

MQTT Command Topics Example

For a smart door lock application, a user must be able to submit a command to the lock that triggers a temporary key to be issued for an approved visitor. The temporary key consists of a TTL, code, and information about the authorized user. The ability to create a temporary key allows another individual to open the lock for a specified period. This use case would apply in scenarios such as visiting family member arriving at the home while the primary owner is at work.

This scenario assumes the following details:

  • The homeowner has a mobile device ID of mobile-1

  • The approved visitor has a mobile device ID of mobile-2

  • The smart lock is installed as part of a group of other locks in the home. The set of locks has a context for groupId where groupId equals group-3

  • The smart lock for the front door has a lockId of lock-1

  • The smart lock hardware has a series number of series100. The series is a unique identifier for this product version.

Command Request to Generate a Smart Lock Code

The primary owner first publishes a command to the lock to request a temporary access code created for an approved visitor. The command payload includes the identification of the homeowner’s mobile device, a randomly generated session identifier for tracking the current request, an action field that contains the type of command, and a topic field. The smart lock uses the topic in the topic field for publishing its response back to the homeowner.

Figure 8: Mobile user requests temporary credentials for the front door

Augment MQTT messages using any internal standards for requests, responses, and telemetry. For example, by adding in the requestor of the command in the payload, applications can specify different response topics based on the use case. If the homeowner requests a temporary lock but needs the response to reach all door locks in the home, the topic field could be changed to send to a group of devices.

Command Processing on the Smart Lock

The smart lock receives the command message from the MQTT topic. By leveraging a consistent naming schema for commands in this application, the smart lock can ensure that it only receives commands on its specific command topic. This topic design also makes it possible for the lock to subscribe using a single level MQTT wildcard after its identifier. The single level wildcard command is backward compatible as the IoT application adds new command types.

Figure 9: Command sent from the AWS IoT Device Gateway to the smart lock

After receiving the MQTT payload, the smart lock parses the command request to determine what type of action it runs. In this case, the command is related to credentials. The device also extracts the client ID, the session ID, and the response topic from the command payload. Because a home can have multiple authorized homeowners, the client ID determines which homeowner has requested this change. In this example, the action field includes the type of credentials request, generate-password, and the associated user for the temporary key. Last, the device obtains the response topic field in the MQTT message and uses this information to publish its response.

Figure 10: Smart lock response published to AWS IoT Core

Command Response Delivered to the Mobile Client

The homeowner's mobile client subscribes to command responses for any smart locks in the group. Whenever the mobile client receives a successful command response, the temporary code along with any additional authorization permissions can be processed on the device and simultaneously stored in the AWS cloud. At a later time, the authorized visitor can use the temporary code along with additional security credentials, such as exchanging for OAuth credentials, proving local presence to the door, and so on, to apply the temporary code to the smart lock.

In this workflow, the application used a command topic for a single device. However, a similar workflow may be used to request commands for multiple devices in a group, such as locking all of the doors in the home.

Figure 11: Command response sent from AWS IoT Core to mobile client

MQTT Telemetry Topics Example

This section is an example of aggregating telemetry from a set of occupancy sensors that are placed throughout a building to monitor room usage. The occupancy sensors communicate to a local gateway that is running AWS IoT Greengrass . AWS IoT Greengrass then delivers all sensor metrics on an MQTT topic to AWS IoT Core. Because this use case is focused on telemetry, a response topic is not needed between AWS IoT Greengrass and AWS IoT Core, either locally or upstream.

This scenario assumes the following details:

  • The occupancy sensors have ids of occupancy-1 and occupancy-2

  • The building is called building-fresco

  • Each sensor is placed on a specific floor and room name in building-fresco.

  • The AWS IoT Greengrass local gateway has a unique identifier of gateway-1

  • The current building automation system correlates to an internal project called acme

Local Telemetry from Occupancy Sensor to AWS IoT Greengrass

Each occupancy sensor publishes an occupancy reading once per minute and whenever a person enters or leaves the room. Because the occupancy sensors do not correlate precisely to the state of the device and instead refer to the state of the room, the sensor publishes the room status on a telemetry topic. The payload includes a timestamp, occupancy count, and any efficiency countdown for turning off lights if a room is vacant. The occupancy sensor uses an MQTT topic that includes the contextual information about the position of the sensor within the building and its associated project. AWS IoT Greengrass core receives all occupancy sensor data locally.

Figure 12: Local occupancy sensor publishes sensor reading to AWS IoT Greengrass

AWS IoT Greengrass Telemetry from Edge to Cloud

In this example, the primary role of AWS IoT Greengrass is to aggregate the data from multiple occupancy sensors then send the data to AWS IoT Core. Because AWS IoT Greengrass is the local bridge to the cloud, AWS IoT Greengrass adds metadata to each sensor reading. AWS IoT Greengrass adds building information to each message to show the overall usage of the building in 5 minute increments. AWS IoT Greengrass also augments the MQTT topic by including the appropriate application identifier, acme.

Figure 13: AWS IoT Greengrass aggregates and augments telemetry then forwards messages to AWS IoT Core