This tutorial will show how to create a listener in Altair SmartWorks. We suppose you know the basics of working in Altair SmartWorks. If you are a newcomer you might want to visit the Get started with Altair SmartWorks tutorial and Altair SmartWorks entities documentation page.
A listener in Altair SmartWorks 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@smartcore service so all devices below the groups floor1@smartcore and floor2@smartcore will be affected, supposing those groups belongs to the parking@smartcore service.
A listener "waits" 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@smartcore.
- Name & description: for easy location
- Associated entity
- Event to listen
- Listener enabled or not
- Listener logic: formerly the user implemented the logic of the listener by writing Groovy code. We have enhanced the listener creation process with our Flow Tool, a visual designer that allows the user to add predefined business logic nodes without the need to know the Groovy language (advanced users still have the possibility to add custom Groovy code). Please read the documentation of our new Flow Tool for a more in-depth look at the possibilities it offers.
In this tutorial we will follow a simple example:
Suppose we have a RFID card reader called rfidreader@smartcore. 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 firstname.lastname@example.org when the RFID tag read is not 12345 and send an open door signal otherwise.
For the purpose of this example, let's suppose 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. The listener creation is now divided in 2 steps:
Step 1: general data
Fill the fields with the following values and continue to the next step.
- Name: The name that you prefer
- Description: The description that you prefer
- Entity type: Device
- Entity id: The device id_developer that will send the stream (defaultDevice@example.example)
- Event to listen: "Event Data Received"
- Be sure to have your listener enabled if you want it to be executed
- Click on the "Next Step: design the code" button to visually design the listener functionality
- Listener creation: step 1
Step 2: designing the business logic with predefined nodes
In the Flow editor we'll need to add and configure the following nodes:
Switch node: Drag and drop in the editor workspace a "switch" node and Double-click it to configure it with the values:
Label: descriptive name of the node in the editor view. For example "If tag OK"
If condition: select "if" and fill in the following field with the code context.data.tag==12345
Else condition: click on the button "+ add" and select "else"
None of the following data are relevant for this simple example, but could be useful in a more complex scenario (Auth headers, Params for a POST payload...) Click on the button "Done" to apply the changes. As a result of these actions we will see in the editor workspace our newly created node with 2 output ports. From left to right, the ports correspond to the conditions added in the first step from top to bottom.
- Switch node
Basic http node: Drag and drop in the editor workspace a "basic http" node and Double-click it to configure it with the values:
Label: descriptive name of the node in the editor view. For example "Open Door"
Url: type the url http://control.entrance:9090/openDoor?token=123456789
Method: select the "GET" method
Click on the button "Done" to apply the changes. You can now connect the nodes as shown in the following image:
- Basic http node
Send email node: Drag and drop in the editor workspace a "send email" node and Double-click it to configure it with the values:
Label: descriptive name of the node in the editor view. For example "Send Alert Email"
To: type the email account email@example.com
Subject: Type for example Suspicious access attempt
Message: In the drop-down select "$ variable " as the type of this field and fill it with "RFID reader. Card read: "+context.data.tag
Please note the message is composed of a string concatenated with a variable. This is the reason why we must indicate that the field type is "$ variable". Otherwise, all the field's content would be treated as a string. Click on the button "Done" to apply the changes. You can now connect the nodes as shown in the following image:
- Send email node
- Save the listener: Click on the "Save" button and check the listener data in the "Show" screen. You can have a look at the generated source code and use it later for debugging purposes.
- Resulting listener + source code
Its time to test our new listener. Send a data stream to this device:
Payload (saved in the payload.txt file):
Send the stream (check your apikey at your account page):
Check that the door opens!
You could repeat the process changing the payload:
In this case... Check your email!