How to troubleshoot an AWS IoT Events detector model

AWS IoT Events recently launched a new troubleshooting feature that automatically analyzes your detector model for potential syntax errors, structural issues, and runtime errors without needing to publish the detector model first. In this post, you will learn how to use this new feature with your AWS IoT Events detector model.

AWS IoT Events is a fully managed service that makes it easy to detect and respond to events from IoT sensors and applications. The detector model in AWS IoT Events lets you monitor your equipment or device fleets for failures or changes in operation and trigger actions when such events occur. To learn more about detector models, see the Getting Started with the AWS IoT Events Console guide.

Prior to the launch of this new feature, to check if a detector model works as expected, customers would first send sample data to the detector model. Next, they would execute the DescribeDetector API to check if the detector state changed as expected. In the case where the detector’s state did not have the expected change, they would then identify the root cause, publish an updated version of the detector model, and then send the sample data again to the detector model. They would keep repeating this debugging cycle until their detector model achieved their desired functionality (or they ran out of time). Such debugging can be time consuming, especially for a complex detector model.

Here is an example of how debugging can be time consuming. Our detector model continuously monitors the temperature of a room and turns on the heating or cooling mode for the HVAC system as needed to maintain temperature between 68-72 degrees Fahrenheit. The detector computes and stores the average temperature in a variable named averageTemperature.

After sending sample data to this example detector model, we observe that the average temperature is not recomputed. Checking the logs in Amazon CloudWatch for the detector model reveals no information as to why the average temperature is not recomputed. We check the following condition of the detector model that needs to be satisfied in order to recompute the average temperature.

($variable.resetMe == true) && ($input.temperatureInput.sensorData.temperature < 80 && $input.temperatureInput.sensorData.temperature > 60)

We have set the variable resetMe to "true", a value of String data type, when the detector enters the start state. After several attempts, we realize that the value, "true" (note the quotation marks) can never equal true, a Boolean value. This causes the condition ($variable.resetMe == true) to always evaluate to false.

This new troubleshooting feature of AWS IoT Events catches this mismatch of data types much earlier by flagging a warning for the resetMe variable. Without the feature, debugging a much bigger detector model with 20 states and 50 variables, as an example, can be a time-consuming exercise. This new feature performs seven different analyses on your detector model for potential syntax errors (e.g. bad expressions or payloads), structural issues (e.g. missing states or input triggers) and runtime errors (e.g. data type mismatch, missing data, potential to hit service limits, etc.) before publishing the model.

To get started with troubleshooting your detector model

This step-by-step walkthrough consists of the following sections to debug the previous example detector model:

1. Prerequisites
2. Creating an input
3. Creating a detector model
4. Troubleshooting issues with the detector model

Prerequisites

For this use case, make sure that you have an AWS account in the same AWS Region where AWS IoT Events is available. This use case uses the US East (N. Virginia) Region. However, you can choose another AWS Region where AWS IoT Events is available.

To create an input for the detector model

Create an input named temperatureInput by following the steps:

1. Save the following JSON in a file on your computer.

   {
     "sensorId": 1,
     "areaId": 1,
     "sensorData" : {
       "temperature": 70
     }
   }

2. Navigate to the AWS IoT Events console, then choose Inputs, Create input.
3. For Input name, enter “temperatureInput”.
4. Choose Upload a JSON file.
5. In the dialog box, choose the JSON file that you created in step 1.
6. Choose Create to create the input.
7. Once the input is created successfully, you will be redirected to the AWS IoT Events inputs console page with the following message.

To create a detector model

Create a draft detector model named areaDetectorModel by following these steps:

1. Download the JSON file.
2. Navigate to the AWS IoT Events console, then choose Detector models.
3. Choose Create detector model to navigate to Create your detector model console page.
4. Choose Import detector model from the left pane and then choose Import to select the JSON file for the detector model that you downloaded in step 1.
5. Once the detector model is created successfully, you will be redirected to the canvas:

To troubleshoot issues with the detector model

Troubleshoot the detector model by following these steps:

1. Choose Run analysis.
2. Wait until the analysis completes and results are displayed in the Detector model analysis panel. Choose Warning to see the details for the incompatible data types:

3. To fix this warning, choose Start state in the imported detector model.
4. In the State pane, choose prepare event under onEnter.
5. On the Add OnEnter event page, expand the first Set variable action.
6. Change the Assign value of resetMe variable from the String value of “true” to the Boolean value of true.

7. Scroll down the list of all the actions and choose Save.
8. Choose Rerun analysis.

9. Wait until the analysis completes and results are displayed in the Detector model analysis panel with no errors and no warnings.

10. You can also scroll down the list in the Detector model analysis panel to validate that the resetMe variable now has the Boolean data type as shown:

Now your detector model is ready to be published!

Conclusion

In this post, we demonstrated how to use the recently launched new troubleshooting feature for AWS IoT Events that automatically analyzes your detector model for potential syntax errors, structural issues, and runtime errors without needing to publishing the detector model first.

Now that detector models can be analyzed for errors before publishing, explore using them for the following use cases:

• Monitor IoT device geolocation
• Enable conditions monitoring and send notifications or alerts in near real-time for industrial data at scale 
• Predict and respond to potential failures before they impact your business

About the authors

	Vaibhav Sharma is an Applied Scientist in the Automated Reasoning Group. He works on applying automated reasoning to solve customer problems in the IoT domain.
	Andrew Apicelli is a Software Development Engineer at Amazon Web Services IoT. He focuses on developing AWS IoT cloud services that help customers across many industries achieve positive business outcomes.