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.


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



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 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: