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 significant 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.

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

• 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.

• Define 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 define one or more inputs. To do so, give each input a name and specify which fields 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.

Create a detector model

Define a detector model (a model of your equipment or process) using states. For each state, you 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.

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 field. In this case, a single detector (instance) is created when the first 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 first 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 first 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.

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 specified actions. When an operation exits its current state, and the condition is met, the onExit event performs the specified 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 reflect 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 effect, 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.