Find runtime errors in AWS IoT Events detector models using type checking

Customers use AWS IoT Events detector models to describe equipment states and the events that affect these states. A detector model in AWS IoT Events contains expressions written in the AWS IoT Events expression language. An expression can have one of four primitive data types: integer, string, decimal, or Boolean. By checking your expressions for correct use of data types, you can be confident that your detector model will work as you expect. In this post, we describe the consequences of using wrong data types in your AWS IoT Events detector models. We show how the troubleshooting feature of AWS IoT Events detects these type errors before executing your 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 by creating a detector model. To learn more about detector models, see the Getting Started with the AWS IoT Events Console guide.

How type checking in AWS IoT Event expressions can help you

In this blog we will use the example of an industrial forklift. We will monitor it using an AWS IoT Events detector model, introduce a runtime error, and then show how to troubleshoot it.

When our example forklift picks up an item, it updates two attributes of an input in AWS IoT Events. One of them is weight, the weight of the item being lifted by the forklift. The second attribute is isWeightLb, which indicates whether the weight is in pounds or kilograms. Our developer uses these attributes in two ways. First, the receipt of a new value for isWeightLb is used as a heartbeat, in other words, an indicator that the forklift is active. If a value is not received at least once every five minutes, the forklift’s status is changed to offline and a notification is sent.

The monitoring of the forklift for a heartbeat is modeled using a detector model in AWS IoT Events shown in the following figure. The Offline state represents that the forklift has not sent a new value for isWeightLb in the last five minutes.

Setting up an ‘Alert if too heavy’ event

Our developer also uses the preceding detector model to trigger a notification when the forklift lifts too heavy an item. Our developer notifies a SNS topic whenever the forklift lifts an item that is heavier than 4500 lbs. This event is detected via the Alert if too heavy event shown in the following figure.

Setting up a ‘Publish to asset property’ event

Our developer makes one more addition to this detector model. They have already modeled the industrial forklift with an asset model in AWS IoT SiteWise. They wish to populate the isWeightLb asset property of their forklift assets in AWS IoT SiteWise using the isWeightLb input attribute to their AWS IoT Events detectors. Upon receiving a heartbeat, they make their detector model populate an asset property in a Forklift asset in AWS IoT SiteWise via the Publish to asset property AWS IoT SiteWise action shown in the following figure.

Introducing a runtime error

We will now introduce an error that is especially common when modeling complex systems. The HeartBeat input has two attributes isWeightLb (is the weight measured in pounds or kilograms?) and weight (the weight of the item lifted by the forklift). Our developer meant to pass the input attribute isWeightLb from their AWS IoT Events detector model to their asset property in AWS IoT SiteWise. But, they pass the weight attribute from the input to AWS IoT SiteWise as if the field is a Boolean.

Every time this action is executed, AWS IoT Events will attempt to send the value in the weight attribute of the HeartBeat input as a Boolean value to the forklifts/forklift1/isWeightLb asset property in AWS IoT SiteWise.

But, for the value to be correctly ingested into AWS IoT SiteWise, the value contained in the weight attribute of the HeartBeat input must be of Boolean type. If it is not, the action will fail to send the value contained in weight to the forklifts/forklift1/isWeightLb asset property in AWS IoT SiteWise. This failure will occur not just from this detector, but all detectors that contain this AWS IoT SiteWise action. Our developer may think this is happening because their detectors have stopped receiving a heartbeat message. Instead, the detectors are receiving the heartbeat message, but are unable to handle weight as a Boolean.

To find the root cause of this issue, our developer will:

1. Enable logging in AWS IoT Events and check the detector’s logs in Amazon CloudWatch for incoming heartbeat messages.
2. Verify that the declared data type of the forklifts/forklift1/isWeightLb asset property in AWS IoT SiteWise is Boolean.
3. Verify that the isWeightLb attribute in the HeartBeat input in AWS IoT Events contains a Boolean value at runtime.

However, none of these steps will reveal to our developer that their detector model mistakenly sends the weight input attribute as a Boolean value to AWS IoT SiteWise, instead of the isWeightLb input attribute.

To reduce such debugging pain, the troubleshooting feature of AWS IoT Events searches for inconsistencies between the expected and actual data types of input attributes in your detector model. For example, in this situation, the troubleshooting feature warns our developer that the inferred data type, integer, for $input.HeartBeat.weight does not match the expected data type, Boolean, in the AWS IoT SiteWise action.

Troubleshooting data type errors

The AWS IoT Events expression language allows you to have input attributes and variables which need to have one of four primitive data types: integer, decimal, string, and Boolean. You do not declare data types for your input attributes or variables used in your detector model. The troubleshooting feature of AWS IoT Events can infer data types for them by analyzing their use within expressions in your detector model.

For example, consider that the Alert if too heavy event in the preceding detector model has the following condition, $input.HeartBeat.weight > 4500. This expression compares an input attribute, weight, against an integer literal, 4500. Since the input attribute weight is being compared with a value of integer type, it is meant for storing a value of integer type and therefore must be of integer type.

AWS IoT Events infers data types for the input attributes and variables used in your detector model by leveraging the type rules of the AWS IoT Events expression language. These rules dictate the types of the operands that an operator or function in the language is allowed to operate over. For example, the type rule for the > operator in the AWS IoT Events expression language is:

if one operand of > is of type integer, the other operand must be of type integer

When analyzing your detector model, the troubleshooting feature of AWS IoT Events matches each expression against the type rule that applies to it. It infers data types for operands of operators and arguments of functions. Once a data type is inferred for an input attribute or variable, the troubleshooting feature uses this information to check your expressions in other actions for type correctness.

Example: Catching type errors with IotSitewiseActions

Consider the AWS IoT SiteWise action shown in the preceding figure. When you choose Run Analysis in the AWS IoT Events console shown in the following figure, the troubleshooting feature of AWS IoT Events will analyze all expressions in the detector model, including the comparison expression $input.HeartBeat.weight > 4500, to infer that $input.HeartBeat.weight must be of integer type.

Next, AWS IoT Events will examine the expressions in the AWS IoT SiteWise action of the detector model. It will find that the expression, $input.HeartBeat.weight, is to be sent as a Boolean value to the asset property forklifts/forklift1/isWeightlb in AWS IoT SiteWise. But, since the inferred data type, integer, for the expression, $input.HeartBeat.weight, does not match the data type Boolean declared in the AWS IoT SiteWise action, AWS IoT Events will report the warning shown in the following figure.

The warning message states, “The expression in the IotSitewiseAction field [$input.HeartBeat.weight] is defined as type Boolean and inferred as type Integer. The defined type and the inferred type must be the same.” This warning indicates that AWS IoT Events has inferred the expression $input.HeartBeat.weight to be of type integer. But, your AWS IoT SiteWise action assumes that the runtime value evaluated from this expression will be of Boolean type. The Location field in the warning tells us that the warning is reported in an AWS IoT SiteWise action in the Normal state’s onEnter event list in an event named Publish to asset property.

Example: Catching type errors with custom payload expressions

Similar to how your expression in your AWS IoT SiteWise action needs to have a specific declared data type, AWS IoT Events also expects your custom payload expressions to be of string type. For example, consider the action shown in the preceding figure, that showed the Alert if too heavy event, in which you use the custom payload expression "Last weight exceeded 4500, reported: " + $input.HeartBeat.weight.

Since $input.HeartBeat.weight is used as an integer in the event condition $input.HeartBeat.weight > 4500 of the Alert if too heavy event, it cannot be used as part of a string payload directly. The troubleshooting feature reports this issue with the following warning:

Conclusion

Customers have told us that creating AWS IoT Events detector models, which are a part of a complex system, can be challenging. In this post, we discussed the troubleshooting feature of AWS IoT Events. This feature simplifies the debugging experience for customers by finding type-correctness issues with the detector model without sending any data to it and without even publishing it.

You can learn more about the type-based warnings and errors reported by this feature by reading our documentation. You can use the troubleshooting feature to check if the inferred data types reported by it match your expectations. Now that you can find type-correctness issues with your detector model without publishing it, choose Run Analysis when editing your detector model in the AWS IoT Events console to be even more confident with using your detector model.