AWS IoT Events

(1)

AWS IoT Events

Developer Guide

(2)

AWS IoT Events: Developer Guide

Copyright © Amazon Web Services, Inc. and/or its aﬃliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is AWS IoT Events?

AWS IoT Events enables you to monitor your equipment or device ﬂeets for failures or changes in operation, and to trigger actions when such events occur. AWS IoT Events continuously watches IoT sensor data from devices, processes, applications, and other AWS services to identify signiﬁcant events so you can take action.

You can use AWS IoT Events to build complex event monitoring applications in the AWS Cloud that you can access through the AWS IoT Events console or APIs.

Beneﬁts and features

Accept Inputs from Multiple Sources

AWS IoT Events accepts inputs from many IoT telemetry data sources. These include sensor devices, management applications, and other AWS IoT services, such as AWS IoT Core and AWS IoT Analytics.

You can push any telemetry data input to AWS IoT Events by using a standard API interface (BatchPutMessage API).

Use Simple Logical Expressions to Recognize Complex Patterns of Events

AWS IoT Events can recognize patterns of events that involve multiple inputs from a single IoT device or application, or from diverse equipment and many independent sensors. This is especially useful because each sensor and application provides important information. But only by combining diverse sensor and application data can you get a complete picture of the performance and quality of operations. You can conﬁgure AWS IoT Events detectors to recognize these events using simple logical expressions instead of complex code.

Trigger Actions Based on Events

AWS IoT Events enables you to directly trigger actions in Amazon Simple Notiﬁcation Service (Amazon SNS), AWS IoT Core, Lambda, Amazon SQS and Amazon Kinesis Firehose. You can also

(7)

Use cases

Automatically Scale to Meet the Demands of Your Fleet

AWS IoT Events scales automatically when you are connecting homogeneous devices. You can deﬁne a detector once for a speciﬁc type of device, and the service will automatically scale and manage all instances of that device that connect to AWS IoT Events.

Use cases

Monitor and Maintain Remote Devices

You need to monitor a ﬂeet of remotely deployed machines. If one stops functioning, and you have no additional context for what's causing the failure, you might have to immediately replace the entire processing unit or machine. But this isn't sustainable. With AWS IoT Events you can receive messages from multiple sensors on each machine and diagnose the exact problem by using the error codes that are sent over time. Instead of replacing everything, you now have the information you need to send a technician with only the part that needs to be replaced. With millions of machines, savings can add up to millions of dollars, lowering your total cost of owning or maintaining each machine.

Manage Industrial Robots

You deploy robots inside your facilities to automate the movement of packages. To keep the cost of the robots to a minimum, the robots have simple, low-cost sensors that report information to the cloud. But your robots have dozens of sensors and hundreds of operating modes, making it diﬃcult to detect problems as they occur. Using AWS IoT Events, you can build an expert system that processes sensor data in the cloud, and creates alerts to automatically warn technical staﬀ if a failure is imminent.

Track Building Automation Systems

You operate a large number of data centers that must be monitored for high temperature and low humidity to prevent equipment failures that occur when these environmental thresholds are breached. The sensors you use are purchased from many manufacturers, and each type comes with its own management software. However, the management software from diﬀerent vendors isn't compatible, making it diﬃcult to detect problems. Using AWS IoT Events, you can set up alerts to notify your operations analysts of issues with your heating and cooling systems well in advance of failures. In this way, you can prevent an unscheduled data center shutdown that would cost thousands of dollars in equipment replacement and potential lost revenue.

(8)

Setting up permissions for AWS IoT Events

Setting up AWS IoT Events

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Setting up permissions for AWS IoT Events

This section describes the roles and permissions that are required to use some features of AWS IoT Events. You can use AWS CLI commands or the AWS Identity and Access Management (IAM) console to create roles and associated permission policies to access resources or perform certain functions in AWS IoT Events.

The IAM User Guide has more detailed information about securely controlling permissions to access AWS resources. For information speciﬁc to AWS IoT Events, see Actions, resources, and condition keys for AWS IoT Events.

Action permissions

AWS IoT Events enables you to trigger actions which use other AWS services. To do so, you must grant AWS IoT Events permission to perform these actions on your behalf. This section contains a list of the actions and an example policy which grants permission to perform all these actions on your resources.

Change the region and account-id references as required. When possible, you should also change the wildcards (*) to refer to speciﬁc resources that will be accessed. You can use the IAM console to grant permission to AWS IoT Events to send an Amazon SNS alert that you have deﬁned. For more information, see Using the IAM console to manage roles and permissions (p. 5).

AWS IoT Events supports the following actions that let you use a timer or set a variable:

• setTimer (p. 89) to create a timer.

• resetTimer (p. 90) to reset the timer.

• clearTimer (p. 90) to delete the timer.

• setVariable (p. 90) to create a variable.

AWS IoT Events supports the following actions that let you work with AWS services:

• iotTopicPublish (p. 91) to publish a message on an MQTT topic.

(9)

Securing input data

• firehose (p. 96) to send data to an Amazon Kinesis Data Firehose stream.

• lambda (p. 97) to invoke an AWS Lambda function.

• sns (p. 97) to send data as a push notiﬁcation.

• sqs (p. 98) to send data to an Amazon SQS queue.

Example Policy

{ "Version": "2012-10-17", "Statement": [

{

"Effect": "Allow", "Action": "iot:Publish",

"Resource": "arn:aws:iot:<region>:<account_id>:topic/*"

}, {

"Effect": "Allow",

"Action": "iotevents:BatchPutMessage",

"Resource": "arn:aws:iotevents:<region>:<account_id>:input/*"

}, {

"Effect": "Allow",

"Action": "iotsitewise:BatchPutAssetPropertyValue", "Resource": "*"

}, {

"Effect": "Allow",

"Action": "dynamodb:PutItem",

"Resource": "arn:aws:dynamodb:<region>:<account_id>:table/*"

}, {

"Effect": "Allow", "Action": [

"firehose:PutRecord", "firehose:PutRecordBatch"

],

"Resource": "arn:aws:firehose:<region>:<account_id>:deliverystream/*"

}, {

"Effect": "Allow",

"Action": "lambda:InvokeFunction",

"Resource": "arn:aws:lambda:<region>:<account_id>:function:*"

}, {

"Effect": "Allow", "Action": "sns:Publish",

"Resource": "arn:aws:sns:<region>:<account_id>:*"

}, {

"Effect": "Allow",

"Action": "sqs:SendMessage",

"Resource": "arn:aws:sqs:<region>:<account_id>:*"

} ] }

Securing input data

It's important to consider who can grant access to input data for use in a detector model.

If you have a user or entity whose overall permissions you want to restrict, but that is

(10)

Using the IAM console to manage roles and permissions

permitted to create or update a detector model, you must also grant permission for that user or entity to update input routing. This means that in addition to granting permission for

iotevents:CreateDetectorModel and iotevents:UpdateDetectorModel, you must also grant permission for iotevents:UpdateInputRouting.

Example

The following policy adds permission for iotevents:UpdateInputRouting.

{

"Sid": "updateRoutingPolicy", "Effect": "Allow",

"Action": [

"iotevents:UpdateInputRouting"

],

"Resource": "*"

} ] }

You can specify a list of input Amazon Resource Names (ARNs) instead of the wildcard "*" for the

"Resource" to limit this permission to speciﬁc inputs. This enables you to restrict access to the input data that is consumed by detector models created or updated by the user or entity.

Using the IAM console to manage roles and permissions

The following example shows how to use the IAM console to grant permission to AWS IoT Events to generate Amazon SNS alerts on your behalf. You can also attach the role to any entity (user or account owner) that you will use to deﬁne and publish an AWS IoT Events detector model that contains event actions that send Amazon SNS alerts.

To complete this example, you need the ARN of an existing Amazon SNS topic to use in AWS IoT Events.

To use the IAM console to manage roles and permissions

1. Sign in to the AWS Management Console and open the IAM console at https://

console.aws.amazon.com/iam/.

2. In the navigation pane, choose Dashboard, Roles.

(11)

3. Choose Create role.

4. On the Create role page, do the following.

a. For Select type of trusted entity, choose AWS service.

b. For Choose the service that will use this role, choose IoT.

c. For Select your use case, choose IoT and choose Next: Permissions.

(12)

5. On the Create role page, for Attached permissions, leave these permissions as they are for now and choose Next: Tags.

You add a new policy granting the required permissions in a later step.

(13)

6. On the Create role page, for Add tags (optional), don't add tags now and choose Next:Review.

7. On the Review page, enter a Role name, an optional Role description, and choose Create role.

(14)

8. On the Roles page, ﬁnd and select the name of the role that you created.

9. On the Summary page for your role, on the Permissions tab, choose Attach policies.

(15)

10. On the Attach Permissions page, choose Create policy.

11. On the Create Policy page, select the JSON tab. If a policy validation failure warning appears, choose the X icon to dismiss it.

(16)

12. On the JSON tab, do the following.

a. Replace the JSON in the editor with the following example.

b. Change the Resource value to the ARN of the Amazon SNS topic to use in AWS IoT Events.

c. Choose Review policy. You can also use wildcard characters in the Amazon SNS topic ARN to grant broader permissions, but be aware of the security issues this raises.

{

"Version": "2012-10-17", "Statement": [

{

"Action": [ "sns:*"

],

"Effect": "Allow",

"Resource": "arn:aws:sns:us-east-1:123456789012:testAction"

} ] }

Your policy should look like the following.

(17)

13. On the Review policy page, enter a Name for the policy, an optional Description, and choose Create policy.

14. On the Policies page, in the navigation pane, choose Roles.

(18)

16. On the Summary page for your role, on the Permissions tab, choose Attach policies.

(19)

17. On the Attach permissions page for your role, select the check box next to the policy that you created, and choose Attach policy.

(20)

19. On the Summary page for that role, on the Trust relationships tab, choose Edit trust relationship.

20. On the Edit Trust Relationship page, for Policy Document, replace the existing JSON with the following and choose Update Trust Policy.

{

"Sid": "",

"Effect": "Allow", "Principal": {

"Service": "iotevents.amazonaws.com"

},

"Action": "sts:AssumeRole"

}

(21)

Amazon CloudWatch logging role policy

You have now granted AWS IoT Events permission to send alerts to your Amazon SNS topic on your behalf. For enhanced security, remove the unused policies that were attached by default to the role that you created.

Amazon CloudWatch logging role policy

The following policy documents provide the role policy and trust policy that allow AWS IoT Events to submit logs to CloudWatch on your behalf.

Role policy:

{

"logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:PutMetricFilter", "logs:PutRetentionPolicy", "logs:GetLogEvents", "logs:DeleteLogStream"

],

"Resource": [

"arn:aws:logs:*:*:*"

] } ] }

(22)

Amazon SNS messaging role policy

Trust policy:

{

"Effect": "Allow", "Principal": { "Service": [

"iotevents.amazonaws.com"

] },

} ]}

You also need an IAM permissions policy attached to the IAM user that allows the user to pass roles, as follows. For more information, see Granting a user permissions to pass a role to an AWS service in the IAM User Guide.

{

"Sid": "",

"iam:GetRole", "iam:PassRole"

],

"Resource": "arn:aws:iam::<account-id>:role/Role_To_Pass"

} ]}

You can use the following command to put the resource policy for CloudWatch logs. This allows AWS IoT Events to put log events into CloudWatch streams.

aws logs put-resource-policy --policy-name ioteventsLoggingPolicy --policy-document

"{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Sid\": \"IoTEventsToCloudWatchLogs\", \"Effect\": \"Allow\", \"Principal\": { \"Service\": [ \"iotevents.amazonaws.com\" ] }, \"Action\":\"logs:PutLogEvents\", \"Resource\": \"*\" } ] }"

Use the following command to put logging options. Replace the roleArn with the logging role that you created.

aws iotevents put-logging-options --cli-input-json "{ \"loggingOptions\": {\"roleArn\":

\"arn:aws:iam::123456789012:role/testLoggingRole\", \"level\": \"INFO\", \"enabled\":

true } }"

(23)

Amazon SNS messaging role policy

Role policy:

{

"Action": [ "sns:*"

],

"Effect": "Allow",

"Resource": "arn:aws:sns:us-east-1:123456789012:testAction"

} ] }

Trust policy:

{

"Sid": "",

"Effect": "Allow", "Principal": { "Service": [

"iotevents.amazonaws.com"

] },

} ] }

(24)

Getting started with the AWS IoT Events console

This section shows you how to create an input and a detector model using the AWS IoT Events console.

You model two states of an engine: a normal state and an over-pressure condition. When the measured pressure in the engine exceeds a certain threshold, the model transitions from the normal state to the over-pressure state. Then it sends an Amazon SNS message to alert a technician about the condition.

When the pressure again drops below the threshold for three consecutive pressure readings, the model returns to the normal state and sends another Amazon SNS message as a conﬁrmation.

We check for three consecutive readings below the pressure threshold to eliminate possible stuttering of over-pressure/normal messages, in case of a nonlinear recovery phase or an anomalous pressure reading.

On the console you can also ﬁnd several pre-made detector model templates which you can customize.

You can also use the console to import detector models that others have written or export your detector models and use them in diﬀerent AWS Regions. If you import a detector model, make sure that you create the required inputs or recreate them for the new Region, and update any role ARNs used.

Use the AWS IoT Events console to learn about the following.

Deﬁne inputs

To monitor your devices and processes, they must have a way to get telemetry data into AWS IoT Events. This is done by sending messages as inputs to AWS IoT Events. You can do this in several ways:

• Use the BatchPutMessage operation.

• In AWS IoT Core write an AWS IoT Events action rule for the AWS IoT rules engine that forwards your message data into AWS IoT Events. You must identify the input by name.

• In AWS IoT Analytics, use the CreateDataset operation to create a data set with

contentDeliveryRules. These rules specify the AWS IoT Events input where data set contents are sent automatically.

Before your devices can send data in this way, you must deﬁne one or more inputs. To do so, give each input a name and specify which ﬁelds in the incoming message data that the input will monitor.

Create a detector model

Define a detector model (a model of your equipment or process) using states. For each state, define conditional (Boolean) logic that evaluates the incoming inputs to detect significant events. When an event is detected, it can change the state or trigger custom-built or predefined actions using other AWS services. You can define additional events that trigger actions when entering or exiting a state and, optionally, when a condition is met.

In this tutorial, you send an Amazon SNS message as the action when the model enters or exits a certain state.

(25)

Prerequisites

Each detector is an instance of the detector model. The new detector continues responding to inputs coming from that device until its detector model is updated or deleted.

If you monitor a single process (even if several devices or subprocesses are sending inputs), you don't specify a unique identifying key ﬁeld. In this case, a single detector (instance) is created when the ﬁrst input arrives.

Send messages as inputs to your detector model

There are several ways to send a message from a device or process as an input into an AWS IoT Events detector that don't require you to perform additional formatting on the message. In this tutorial, you use the AWS IoT console to write an AWS IoT Events action rule for the AWS IoT rules engine that forwards your message data into AWS IoT Events.

To do this, identify the input by name and continue to use the AWS IoT console to generate messages that are forwarded as inputs to AWS IoT Events.

Note

This tutorial uses the console to create the same input and detector model shown in the example at Tutorials (p. 53). You can use the this JSON example to help you follow the tutorial.

Topics

• Prerequisites (p. 20)

• Create an input (p. 21)

• Create a detector model (p. 26)

• Send inputs to test the detector model (p. 40)

Prerequisites

If you don't have an AWS account, create one.

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

3. Create two Amazon Simple Notiﬁcation Service (Amazon SNS) topics.

This tutorial (and the corresponding example) assume that you created two Amazon SNS topics. The ARNs of these topics are shown as: arn:aws:sns:us- east-1:123456789012:underPressureAction and arn:aws:sns:us-

east-1:123456789012:pressureClearedAction. Replace these values with the ARNs of Amazon SNS topics that you create. For more information, see the Amazon Simple Notiﬁcation Service Developer Guide.

As an alternative to publishing alerts to Amazon SNS topics, you can have the detectors send MQTT messages with a topic that you specify. With this option, you can verify that your detector model is creating instances and that those instances are sending alerts by using the AWS IoT Core console to subscribe to and monitor messages sent to those MQTT topics. You can also deﬁne the MQTT topic name dynamically at runtime by using an input or variable created in the detector model.

4. Choose an AWS Region that supports AWS IoT Events. For more information, see AWS IoT Events in the AWS General Reference. For help, see Working with the AWS Management Console in the Getting

(26)

Create an input

When you construct the inputs for your models, we recommend gathering files that contain sample message payloads that your devices or processes will send to report their health status. Having these files will help you define the inputs that are required.

You can create an input through multiple methods that are described in this section.

To get started, create a ﬁle named input.json on your local ﬁle system with the following contents:

{ "motorid": "Fulton-A32", "sensorData": {

"pressure": 23, "temperature": 47 }}

Now that you have this starter input.json ﬁle, you can create an input. Use one of the topics in this section for instructions about creating an input by using the navigation pane or by using the detector model.

Topics

• Create an input in the Navigation Pane (p. 21)

• Create an input in the Detector Model (p. 23)

Create an input in the Navigation Pane

This topic shows how to create an input, for an alarm model or a detector model, through the navigation pane.

1. Log into the AWS IoT Events console or select the option to Create a new AWS IoT Events account.

2. In the AWS IoT Events console, in the upper left corner, select and expand the navigation pane.

3. In the left navigation pane, select Inputs.

4. In the right corner of the console, choose Create input.

5. For the input, enter an InputName, an optional Description, and choose Upload ﬁle. In the dialog box that displays, select the input.json ﬁle that you created in the overview for create an input.

(27)

Create an input in the Navigation Pane

6. For Choose input attributes, select the attributes to use, and choose Create. In this example, we select motorid and sensorData.pressure.

(28)

Create an input in the Detector Model

This topic shows how to deﬁne an input for a detector model to receive telemetry data, or messages.

1. Open the AWS IoT Events console.

2. In the AWS IoT Events console, choose Create detector model.

(29)

3. Choose Create new.

4. Choose Create input.

(30)

5. For the input, enter an InputName, an optional Description, and choose Upload ﬁle. In the dialog box that displays, select the input.json ﬁle that you created in the overview for create an input.

6. For Choose input attributes, select the attributes to use, and choose Create. In this example, we select motorid and sensorData.pressure.

(31)

Create a detector model

In this topic, you deﬁne a detector model (a model of your equipment or process) using states.

For each state, you deﬁne conditional (Boolean) logic that evaluates the incoming inputs to detect a signiﬁcant event. When an event is detected, it changes the state and can trigger additional actions.

These events are known as transition events.

In your states, you also deﬁne events that can execute actions whenever the detector enters or exits that state or when an input is received (these are known as OnEnter, OnExit and OnInput events). The actions are executed only if the event's conditional logic evaluates to true.

To create a detector model

1. The ﬁrst detector state has been created for you. To modify it, select the circle with label State_1 in the main editing space.

(32)

2. In the State pane, enter the State name and OnEnter, choose Add event.

3. On the Add OnEnter event page, enter an Event name and the Event condition. In this example, enter true to indicate the event is always triggered when the state is entered.

4. Under Event actions, choose Add action.

(33)

5. Under Event actions, do the following:

a. Select Set variable

b. For Variable operation, choose Assign value.

c. For Variable name, enter the name of the variable to set.

d. For Variable value, enter the value 0 (zero).

(34)

6. Choose Save.

(35)

A variable, like the one you deﬁned, can be set (given a value) in any event in the detector model.

But its value can only be referenced (for example, in an event's conditional logic) after the detector has reached a state and executed an action where it is deﬁned or set.

7. In the State pane, choose the X next to State to return to the Detector model palette.

8. To create a second detector state, in the Detector model palette, choose State and drag it into the main editing space. This creates a state titled untitled_state_1.

(36)

9. Pause on the ﬁrst state (Normal). An arrow appears on the circumference of the state.

10. Click and drag the arrow from the ﬁrst state to the second state. A directed line from the ﬁrst state to the second state (labeled Untitled) appears.

11. Select the Untitled line. In the Transition event pane, enter an Event name and Event trigger logic.

12. In the Transition event pane, choose Add action.

(37)

13. On the Add transition event actions pane, choose Add action.

14. For Choose an action, choose Set variable.

a. For Variable operation, choose Assign value.

b. For Variable name, enter the name of the variable.

c. For Assign value, enter the value such as: $variable.pressureThresholdBreached + 3 d. Choose Save.

(38)

15. Select the second state untitled_state_1.

16. In the State pane, enter the State name and for On Enter, choose Add event.

17. On the Add OnEnter event page, enter the Event name, Event condition and, choose Add action.

(39)

18. For Choose an action, choose Send SNS message.

a. For SNS topic, enter the target ARN of your SNS topic.

b. Choose Save.

(40)

19. Continue to add the events in the example.

a. For OnInput, choose Add event, and enter and save the following event information.

Event name: Overpressurized

Event condition: $input.PressureInput.sensorData.pressure > 70 Event actions:

Set variable:

Variable operation: Assign value

Variable name: pressureThresholdBreached Assign value: 3

b. For OnInput, choose Add event, and enter and save the following event information.

Event name: Pressure Okay

Event condition: $input.PressureInput.sensorData.pressure <= 70 Event actions:

Set variable:

Variable operation: Decrement

(41)

Event name: Normal Pressure Restored Event condition: true

Event actions:

Send SNS message:

Target arn: arn:aws:sns:us-east-1:123456789012:pressureClearedAction 20. Pause on the second state (Dangerous). An arrow appears on the circumference of the state 21. Click and drag the arrow from the second state to the ﬁrst state. A directed line with label Untitled

appears.

22. Choose the Untitled line and in the Transition event pane, enter an Event name and Event trigger logic using the following information.

{ Event name: BackToNormal

Event trigger logic: $input.PressureInput.sensorData.pressure <= 70 &&

$variable.pressureThresholdBreached <= 0 }

For more information about why we test for the $input value and the $variable value in the trigger logic, see the entry for Availability of variable values in Detector model restrictions and limitations (p. 62).

23. Select the Start state. By default, this state was created when you created a detector model). In the Start pane, choose the Destination state (for example, Normal).

(42)

24. Next, conﬁgure your detector model to listen for inputs. In the upper-right corner, choose Publish.

25. On the Publish detector model page, do the following.

a. Enter a Detector model name, a Description, and the name of a Role. This role will be created for you.

b. Choose Create a detector for each unique key value. To create and use your own Role, follow the steps in Using the IAM console to manage roles and permissions (p. 5) and enter it as the Role here.

(43)

You can make a backup copy of your detector model deﬁnition (in JSON) recreate or update the detector model or use as a template to create another detector model.

You can do this from the console or by using the following CLI command. If necessary, change the name of the detector model to match what you used when you published it in the previous step.

aws iotevents describe-detector-model --detector-model-name motorDetectorModel >

motorDetectorModel.json

This creates a ﬁle (motorDetectorModel.json) that has contents similar to the following.

{ "detectorModel": {

"detectorModelConfiguration": { "status": "ACTIVE",

"lastUpdateTime": 1552072424.212,

"roleArn": "arn:aws:iam::123456789012:role/IoTEventsRole", "creationTime": 1552072424.212,

"detectorModelArn": "arn:aws:iotevents:us-west-2:123456789012:detectorModel/

motorDetectorModel",

"key": "motorid",

"detectorModelName": "motorDetectorModel", "detectorModelVersion": "1"

},

"detectorModelDefinition": {

(44)

{

"onInput": {

"transitionEvents": [ {

"eventName": "Overpressurized", "actions": [

{

"setVariable": {

"variableName": "pressureThresholdBreached", "value": "$variable.pressureThresholdBreached + 3"

} } ],

"condition": "$input.PressureInput.sensorData.pressure >

70",

"nextState": "Dangerous"

} ],

"events": []

},

"stateName": "Normal", "onEnter": {

"events": [ {

"eventName": "init", "actions": [

{

"setVariable": {

"variableName": "pressureThresholdBreached", "value": "0"

} } ],

"condition": "true"

} ] },

"onExit": { "events": []

} }, {

"onInput": {

"eventName": "Back to Normal", "actions": [],

"condition": "$variable.pressureThresholdBreached <= 1 &&

$input.PressureInput.sensorData.pressure <= 70", "nextState": "Normal"

} ],

"events": [ {

"eventName": "Overpressurized", "actions": [

{

"setVariable": {

"variableName": "pressureThresholdBreached",

(45)

Send inputs to test the detector model

}, {

"eventName": "Pressure Okay", "actions": [

{

"setVariable": {

"variableName": "pressureThresholdBreached", "value": "$variable.pressureThresholdBreached - 1"

} } ],

"condition": "$input.PressureInput.sensorData.pressure <=

70"

} ] },

"stateName": "Dangerous", "onEnter": {

"events": [ {

"eventName": "Pressure Threshold Breached", "actions": [

{

"sns": {

"targetArn": "arn:aws:sns:us- west-2:123456789012:MyIoTButtonSNSTopic"

} } ],

"condition": "$variable.pressureThresholdBreached > 1"

} ] },

"onExit": { "events": [ {

"eventName": "Normal Pressure Restored", "actions": [

{

"sns": {

"targetArn": "arn:aws:sns:us- west-2:123456789012:IoTVirtualButtonTopic"

} } ],

"condition": "true"

} ] } } ],

"initialStateName": "Normal"

} } }

Send inputs to test the detector model

There are several ways to receive telemetry data in AWS IoT Events (see Supported actions (p. 89)).

This topic shows you how to create an AWS IoT rule in the AWS IoT console that forwards messages as inputs to your AWS IoT Events detector. You can use the AWS IoT console's MQTT client to send test

(46)

messages. You can use this method to get telemetry data into AWS IoT Events when your devices are able to send MQTT messages using the AWS IoT message broker.

To send inputs to test the detector model

1. Open the AWS IoT core console. In the navigation pane, choose Act.

2. On the Rules page, choose Create.

(47)

4. In the Rule query statement, enter the following.

SELECT *, topic(2) as motorid FROM 'motors/+/status'

5. In Set one or more actions, choose Add action.

6. On the Select an action page, select Send a message to an AWS IoT Events Input and choose Conﬁgure action.

(48)

7. On the Conﬁgure action page, do the following:

a. For Input name, enter the name that you created in the previous section.

b. For Role, choose Create Role and in the Create a new role window, enter a Name and choose Create role. This creates a role with permission to forward messages to AWS IoT Events.

c. Back on the Conﬁgure action page, choose Add action.

(49)

9. On the Rules page, in the navigation pane, choose Test.

10. On the MQTT client page, choose Publish to a topic.

(50)

11. In the Publish section, enter the topic, enter the following payload in the editor, and choose Publish.

{ "sensorData": { "pressure": 23, "temperature": 47 }}

(51)

12. For Publish, keep the topic the same, but change the "pressure" in the payload to a value greater than the threshold value that you speciﬁed in the detector model (for example, 85).

13. Choose Publish.

The detector instance that you created generates and sends you an SNS message. Continue to send messages with pressure readings above or below the pressure threshold (70 for this example) to see the detector in operation.

(52)

In this example, you must send three messages with pressure readings below the threshold to transition back to the Normal state and receive an SNS message that indicates the overpressure condition has cleared. Once back in the Normal state, one message with a pressure reading above the limit causes the detector to enter the Dangerous state and send an SNS message indicating that condition.

Now that you created a simple input and detector model, try the following.

• See more detector model examples (templates) on the console.

• Follow the steps in Simple step-by-step example (p. 55) to create an input and detector model using the AWS CLI

• Learn details of the Expressions (p. 100) used in events.

• Learn about Supported actions (p. 89).

• If something isn't working, see Troubleshooting AWS IoT Events (p. 196).

(53)

Enable Amazon CloudWatch logging when developing AWS IoT Events detector models

Best practices for AWS IoT Events

Follow these best practices to get the maximum beneﬁt from AWS IoT Events.

Topics

• Enable Amazon CloudWatch logging when developing AWS IoT Events detector models (p. 48)

• Publish regularly to save your detector model when working in the AWS IoT Events console (p. 51)

• Store your AWS IoT Events data to avoid possible data loss due to a long period of inactivity (p. 52)

Enable Amazon CloudWatch logging when developing AWS IoT Events detector models

Amazon CloudWatch monitors your AWS resources and the applications that you run on AWS in real time. With CloudWatch, you gain system-wide visibility into resource use, application performance, and operational health. When you develop or debug an AWS IoT Events detector model, CloudWatch helps you know what AWS IoT Events is doing, and any errors that it encounters.

To enable CloudWatch

1. If you haven't already, follow the steps in Setting up permissions for AWS IoT Events (p. 3) to create a role with an attached policy that grants permission to create and manage CloudWatch logs for AWS IoT Events.

2. In the AWS IoT Events console, choose the menu icon in the upper-left corner to open the navigation pane.

(54)

If you're on the Getting started page, choose the X in the upper right to close that page and go to the Detector model palette. Choose the menu icon in the upper-left corner.

3. In the navigation pane, choose Settings.

4. On the Settings page, choose Edit.

(55)

5. On the Edit logging options page, do the following:

a. Choose the Level of verbosity.

b. For Select role, select a role with suﬃcient permissions to perform the logging actions that you chose.

c. If you chose Debug for the Level of verbosity, you can also choose Add Model Option and add a Detector Model Name and (optional) KeyValue to specify the detector models and speciﬁc detectors (instances) to log.

d. Choose Update.

(56)

Publish regularly to save your detector model when working in the AWS IoT Events console

Your logging options are successfully updated.

Publish regularly to save your detector model when working in the AWS IoT Events console

When you use the AWS IoT Events console, your work in progress is saved locally in your browser.

However, you must choose Publish to save your detector model to AWS IoT Events. After you publish a detector model, your published work will become available in any browser that you use to access your account.

Note

If you don't publish your work, it will not be saved. After you publish a detector model, you can't

(57)

Store your AWS IoT Events data to avoid possible data loss due to a long period of inactivity

If you don't use AWS IoT Events for a signiﬁcant period of time, your data, including your detector models, might be deleted automatically. A signiﬁcant period of time could mean, for example, you don't incur charges and don't create detector models. However, we won't delete data or detector models without providing you with at least a 30 day notice prior. If you need to store data for an extended period of time, consider using AWS storage services.

(58)

Using AWS IoT Events to monitor your IoT devices

Tutorials

This chapter shows you how to:

• Get help to decide which states to include in your detector model, and determine whether you need one detector instance or several.

• Follow an example that uses the AWS CLI.

• Create an input to receive telemetry data from a device and a detector model to monitor and report on the state of the device that sends that data.

• Review restrictions and limitations on inputs, detector models, and the AWS IoT Events service.

• See a more complex example of a detector model, with comments included.

Topics

• Using AWS IoT Events to monitor your IoT devices (p. 53)

• Simple step-by-step example (p. 55)

• Detector model restrictions and limitations (p. 62)

• A commented example: HVAC temperature control (p. 64)

Using AWS IoT Events to monitor your IoT devices

You can use AWS IoT Events to monitor your devices or processes, and take action based on signiﬁcant events. To do so, follow these basic steps:

Create inputs

You must have a way for your devices and processes to get telemetry data into AWS IoT Events. You do this by sending messages as inputs to AWS IoT Events. You can send messages as inputs in several ways:

• Use the BatchPutMessage operation.

• Deﬁne an iotEvents rule‐action for the AWS IoT Core rules engine. The rule‐action forwards message data from your input into AWS IoT Events.

contentDeliveryRules. These rules specify the AWS IoT Events input where data set contents are sent automatically.

• Deﬁne an iotEvents action in an AWS IoT Events detector model's onInput, onExit or transitionEvents event. Information about the detector model instance and the event that initiated the action are fed back into the system as an input with the name that you specify.

Before your devices start sending data in this way, you must deﬁne one or more inputs. To do so, give each input a name and specify which ﬁelds in the incoming message data the input monitors.

AWS IoT Events receives its input, in the form of JSON payload, from many sources. Each input can be acted on by itself, or combined with other inputs to detect more complex events.

(59)

How do you know which states you need in a detector model?

using other AWS services. You can deﬁne additional events that initiate actions when entering or exiting a state and, optionally, when a condition is met.

In this tutorial, you send an Amazon SNS message as the action when the model enters or exits a certain state.

Monitor a device or process

If you're monitoring several devices or processes, you specify a field in each input that identifies the particular device or process the input comes from. (See the key field in CreateDetectorModel.) When a new device is identified (a new value is seen in the input field identified by the key), a detector is created. (Each detector is an instance of the detector model.) Then the new detector continues responding to inputs coming from that device until its detector model is updated or deleted.

If you're monitoring a single process (even if several devices or subprocesses are sending inputs), you don't specify a unique identifying key ﬁeld. In this case, a single detector (instance) is created when the ﬁrst input arrives.

Send messages as inputs to your detector model

There are several ways to send a message from a device or process as an input into an AWS IoT Events detector that don't require you to perform additional formatting on the message. In this tutorial, you use the AWS IoT console to write an AWS IoT Events action rule for the AWS IoT Core rules engine that forwards your message data into AWS IoT Events. To do this, you identify the input by name. Then you continue to use the AWS IoT console to generate some messages that are forwarded as inputs to AWS IoT Events.

How do you know which states you need in a detector model?

To determine what states your detector model should have, first decide what actions you can take. For example, if your automobile runs on gasoline, you look at the fuel gauge when you start a trip to see if you need to refuel. Here you have one action: tell the driver to "go get gas". Your detector model needs two states: "car doesn't need fuel", and "car does need fuel". In general, you want to define one state for each possible action, plus one more for when no action is required. This works even if the action itself is more complicated. For example, you might want to look up and include information on where to find the closest gas station, or the cheapest price, but you do this when you send the message to "go get gas".

To decide which state to enter next, you look at inputs. Inputs contain the information that you need to decide what state you should be in. To create an input, you select one or more fields in a message sent by your device or process that help you decide. In this example, you need one input that tells you the current fuel level ("percent full"). Maybe your car is sending you several different messages, each with several different fields. To create this input, you must select the message and the field that reports the current gas gauge level. The length of the trip you are about to take ("distance to destination") can be hardcoded to keep things simple; you can use your average trip length. You'll do some calculations based on the input (how many gallons does that percent full translate to? is the average trip length greater than the miles you can travel, given the gallons you have and your average "miles per gallon").

You perform these calculations and send messages in events.

So far you have two states and one input. You need an event in the ﬁrst state that performs the

calculations based on the input and decides whether to go to the second state. That is a transition event.

(transitionEvents are in a state's onInput event list. On receiving an input in this ﬁrst state, the event performs a transition to the second state, if the event's condition is met.) When you reach the second state, you send the message as soon as you enter the state. (You use an onEnter event. On entering the second state, this event sends the message. No need to wait for another input to arrive.) There are other types of events, but that's all you need for a simple example.

(60)

How do you know if you need one instance of a detector or several?

The other types of events are onExit and onInput. As soon as an input is received, and the condition is met, an onInput event performs the speciﬁed actions. When an operation exits its current state, and the condition is met, the onExit event performs the speciﬁed actions.

Are you missing anything? Yes, how do you get back to the first "car doesn't need fuel" state? After you fill your gas tank, the input shows a full tank. In your second state you need a transition event back to the first state that happens when the input is received (in the second state's onInput: events). It should transition back to the first state if its calculations show you now have enough gas to get you where you want to go.

That's the basics. Some detector models get more complex by adding states that reﬂect important inputs, not just possible actions. For example, you might have three states in a detector model that keeps track of the temperature: a "normal" state, a "too hot" state, and a "potential problem" state.

You transition to the potential problem state when the temperature rises above a certain level, but hasn't become too hot yet. You don't want to send an alarm unless it stays at this temperature for more than 15 minutes. If the temperature returns to normal before then, the detector transitions back to the normal state. If the timer expires, the detector transitions to the too hot state and sends an alarm, just to be cautious. You could do the same thing using variables and a more complex set of event conditions.

But often it is easier to use another state to, in eﬀect, store the results of your calculations.

How do you know if you need one instance of a detector or several?

To decide how many instances you need, ask yourself "What are you interested in knowing?" Let's say you want to know what the weather is like today. Is it raining (state)? Do you need to take an umbrella (action)? You can have a sensor that reports the temperature, another that reports the humidity, and others that report the barometric pressure, wind speed and direction, and precipitation. But you must monitor all these sensors together to determine the state of the weather (rain, snow, overcast, sunny) and the appropriate action to take (grab an umbrella or apply sunscreen). In spite of the number of sensors, you want one detector instance to monitor the state of the weather and inform you which action to take.

But if you're the weather forecaster for your region, you might have multiple instances of such sensor arrays, situated at different locations throughout the region. People at each location need to know what the weather is like in that location. In this case, you need multiple instances of your detector. The data reported by each sensor in each location must include a field that you have designated as the key field. This field enables AWS IoT Events to create a detector instance for the area, and then to continue to route this information to that detector instance as it continues to arrive. No more ruined hair or sunburned noses!

Essentially, you need one detector instance if you have one situation (one process or one location) to monitor. If you have many situations (locations, processes) to monitor, you need multiple detector instances.

Simple step-by-step example

In this example, we call the AWS IoT Events APIs using AWS CLI commands to create a detector that models two states of an engine: a normal state and an over-pressure condition.

(61)

Simple step-by-step example

threshold to eliminate possible stuttering of over-pressure/normal messages in case of a nonlinear recovery phase or a one-oﬀ anomalous recovery reading.

The following is an overview of the steps to create the detector.

Create inputs.

To monitor your devices and processes, they must have a way to get telemetry data into AWS IoT Events. This is done by sending messages as inputs to AWS IoT Events. You can do this in several ways:

• Use the BatchPutMessage operation. This method is easy but requires that your devices or processes are able to access the AWS IoT Events API through an SDK or the AWS CLI.

• In AWS IoT Core, write an AWS IoT Events action rule for the AWS IoT Core rules engine that forwards your message data into AWS IoT Events. This identiﬁes the input by name. Use this method if your devices or processes can, or already are, sending messages through AWS IoT Core.

This method generally requires less computing power from a device.

contentDeliveryRules that specify the AWS IoT Events input, where data set contents are sent automatically. Use this method if you want to control your devices or processes based on data aggregated or analyzed in AWS IoT Analytics.

Before your devices can send data in this way, you must deﬁne one or more inputs. To do so, give each input a name and specify which ﬁelds in the incoming message data that the input monitors.

Create a detector model

Create a detector model (a model of your equipment or process) using states. For each state, define conditional (Boolean) logic that evaluates the incoming inputs to detect significant events. When an event is detected, it can change the state or initiate custom-built or predefined actions using other AWS services. You can define additional events that initiate actions when entering or exiting a state and, optionally, when a condition is met.

Monitor several devices or processes

If you're monitoring several devices or processes and you want to keep track of each of them separately, specify a field in each input that identifies the particular device or process the input comes from. See the key field in CreateDetectorModel. When a new device is identified (a new value is seen in the input field identified by the key), a detector instance is created. The new detector instance continues to respond to inputs coming from that particular device until its detector model is updated or deleted. You have as many unique detectors (instances) as there are unique values in input key fields.

Monitor a single device or process

If you're monitoring a single process (even if several devices or subprocesses are sending inputs), you don't specify a unique identifying key ﬁeld. In this case, a single detector (instance) is created when the ﬁrst input arrives. For example, you might have temperature sensors in each room of a house, but only one HVAC unit to heat or cool the entire house. So you can only control this as a single process, even if each room occupant wants their vote (input) to prevail.

Send messages from your devices or processes as inputs to your detector model

We described the several ways to send a message from a device or process as an input into an AWS IoT Events detector in inputs. After you created the inputs and build the detector model, you're ready to start sending data.

Note

When you create a detector model, or update an existing one, it takes several minutes before the new or updated detector model begins receiving messages and creating

detectors (instances). If the detector model is updated, during this time you might continue to see behavior based on the previous version.

(62)

Create an input to capture device data

Topics

• Create an input to capture device data (p. 57)

• Create a detector model to represent device states (p. 57)

• Send messages as inputs to a detector (p. 60)

Create an input to capture device data

As an example, suppose your devices send messages with the following format.

{

"motorid": "Fulton-A32", "sensorData": {

"pressure": 23, "temperature": 47 }

}

You can create an input to capture the pressure data and the motorid (that identiﬁes the speciﬁc device that sent the message) using the following AWS CLI command.

aws iotevents create-input --cli-input-json file://pressureInput.json

The ﬁle pressureInput.json contains the following.

{

"inputName": "PressureInput",

"inputDescription": "Pressure readings from a motor", "inputDefinition": {

"attributes": [

{ "jsonPath": "sensorData.pressure" }, { "jsonPath": "motorid" }

] }}

When you create your own inputs, remember to ﬁrst collect example messages as JSON ﬁles from your devices or processes. You can use them to create an input from the console or the CLI.

Create a detector model to represent device states

In Create an input to capture device data (p. 57), you created an input based on a message that reports pressure data from a motor. To continue with the example, here is a detector model that responds to an over-pressure event in a motor.

You create two states: "Normal", and "Dangerous". Each detector (instance) enters the "Normal" state when it's created. The instance is created when an input with a unique value for the key "motorid"

arrives.

If the detector instance receives a pressure reading of 70 or greater, it enters the "Dangerous" state and

(63)

Create a detector model to represent device states

east-1:123456789012:underPressureAction" and "targetArn": "arn:aws:sns:us- east-1:123456789012:pressureClearedAction".

For more information, see the Amazon Simple Notification Service Developer Guide and, more specifically, the documentation of the CreateTopic operation in the Amazon Simple Notification Service API Reference.

This example also assumes you have created an AWS Identity and Access Management (IAM) role with appropriate permissions. The ARN of this role is shown in the detector model deﬁnition as "roleArn":

"arn:aws:iam::123456789012:role/IoTEventsRole". Follow the steps in Setting up permissions for AWS IoT Events (p. 3) to create this role and copy the ARN of the role in the appropriate place in the detector model deﬁnition.

You can create the detector model using the following AWS CLI command.

aws iotevents create-detector-model --cli-input-json file://motorDetectorModel.json

The ﬁle "motorDetectorModel.json" contains the following.

{

"detectorModelName": "motorDetectorModel", "detectorModelDefinition": {

"states": [ {

"stateName": "Normal", "onEnter": {

"events": [ {

"eventName": "init", "condition": "true", "actions": [

{

"setVariable": {

} } ] } ] },

"onInput": {

"eventName": "Overpressurized",

"condition": "$input.PressureInput.sensorData.pressure > 70", "actions": [

{

"setVariable": {

"variableName": "pressureThresholdBreached", "value": "$variable.pressureThresholdBreached + 3"

} } ],

"nextState": "Dangerous"

} ] } }, {

"stateName": "Dangerous",

(64)

Create a detector model to represent device states

"events": [ {

"eventName": "Pressure Threshold Breached",

"condition": "$variable.pressureThresholdBreached > 1", "actions": [

{

"sns": {

"targetArn": "arn:aws:sns:us-east-1:123456789012:underPressureAction"

} } ] } ] },

"onInput": { "events": [ {

"eventName": "Overpressurized",

"condition": "$input.PressureInput.sensorData.pressure > 70", "actions": [

{

"setVariable": {

} } ] }, {

"eventName": "Pressure Okay",

"condition": "$input.PressureInput.sensorData.pressure <= 70", "actions": [

{

"setVariable": {

"variableName": "pressureThresholdBreached", "value": "$variable.pressureThresholdBreached - 1"

} } ] } ],

"eventName": "BackToNormal",

"condition": "$input.PressureInput.sensorData.pressure <= 70 &&

$variable.pressureThresholdBreached <= 1", "nextState": "Normal"

} ] },

"onExit": { "events": [ {

"eventName": "Normal Pressure Restored", "condition": "true",

"actions": [ {

"sns": {

"targetArn": "arn:aws:sns:us-east-1:123456789012:pressureClearedAction"

}

AWS IoT Events

AWS IoT Events

Developer Guide

AWS IoT Events: Developer Guide

Copyright © Amazon Web Services, Inc. and/or its aﬃliates. All rights reserved.

Table of Contents

What is AWS IoT Events?

Beneﬁts and features

Use cases

Setting up AWS IoT Events

To sign up for an AWS account

Setting up permissions for AWS IoT Events

Action permissions

Example Policy

Securing input data

Example

Using the IAM console to manage roles and permissions

To use the IAM console to manage roles and permissions

Amazon CloudWatch logging role policy

Getting started with the AWS IoT Events console

Note

Prerequisites

Create an input

Create an input in the Navigation Pane

Create an input in the Detector Model

Create a detector model

To create a detector model

Send inputs to test the detector model

To send inputs to test the detector model

Best practices for AWS IoT Events

Enable Amazon CloudWatch logging when developing AWS IoT Events detector models

To enable CloudWatch

Publish regularly to save your detector model when working in the AWS IoT Events console

Note

Store your AWS IoT Events data to avoid possible data loss due to a long period of inactivity

Tutorials

Using AWS IoT Events to monitor your IoT devices

How do you know which states you need in a detector model?

How do you know if you need one instance of a detector or several?

Simple step-by-step example

Note

Create an input to capture device data

Create a detector model to represent device states