How to create a listener

This tutorial will show how to create a listener in Carriots. We suppose you know the basics of working in Carriots. If you are a newcomer you might want to visit the Get started with Carriots tutorial and Carriots entities documentation page.

Introduction

A listener in Carriots can be associated to any hierarchy entity, from Project to Device. If you associate a listener to a project, all devices below the services of that project will be affected. If you associate a listener to service, all devices below the groups of that services will be affected. And so on.

For example, one listener may be assigned to the parking@carriots service so all devices below the groups floor1@carriots and floor2@carriots will be affected, supposing those groups belongs to the parking@carriots service.

A listener wait for an event to occur in the context of a device and then evaluate its content. For example you have a listener “listening” data_received events for all movement sensors of group ceiling@carriots.

Listener composition:

  • Name, for easy location
  • Associated entity
  • Event to listen
  • If expression: when the event occurs in the associated device context this expression is evaluated to determine which execution path it must take. This expression is a Groovy expression. You have the context of the event to work with.
  • Then expression is executed when “if expression” is evaluated to true.
  • Then rule (if any) is executed when “if expression” is evaluated to true.
  • Else expression is executed when “if expression” is evaluated to false.
  • Else rule (if any) is executed when “if expression” is evaluated to false.
  • Be sure to have your listener enabled if you want it to be executed

TOP

Example

In this tutorial we will follow a simple example:

Suppose we have a RFID card reader called rfidreader@carriots. Each read will send us a data stream with the RFID tag.

The data stream will contain the following information:

We want to send an email to support@carriots.com when the RFID tag read is not 12345 and send an open door signal otherwise.

For the purpose of this example, the open door signal is a simple request to the following URL http://control.entrance:9090/openDoor?token=123456789

To create a listener go to the control panel, then to “Rules” → “Listeners” and click on the new button. Select "Device" as "Entity type" and then locate rfidreader@carriots in the "Id" box.

The listener will "listen" "data_received" event.

When Carriots receives a data stream from that device it will fire the execution path beginning with "if_expression".

If expression:

Then expression:

Else expression:

Fill the fields and save the new listener.

  • Create a listener from device

Its time to test our new listener. Send a data stream to this device:

Payload (payload.txt):

Send the stream (check your apikey at your account page):

Check your email!

Change the payload:

TOP