22 February, 2022

Creating event notifications: get to know when something happens

Using the new flespi analytics features to detect the start and end of target events.

From the very beginning, the analytics engine was intended primarily for reporting purposes — aggregating data points from hundreds of messages based on the custom criteria and calculating meaningful metrics for further analysis and decision-making.

On the other hand, since intervals generation is triggered by certain conditions being met, it’s tempting to use calculators to detect the beginning and end of specific events like crossing the geofence border, exceeding the speed limit, ignition on, activating an iButton by a driver, etc.

State vs Change of state

Until recently flespi analytics offered the flespi/state/gw/calcs/{id}/devices/+/active MQTT topic and the “active” counter to keep track of the interval state and find out if it’s ongoing or not. However, the mentioned topic reflected the state of the interval not the change of state. This made the mentioned approach not as straightforward as some of our users would prefer. And their wishes were heard.

Calculators got two additional MQTT topics associated with them:

flespi/interval/gw/calcs/{id}/devices/+/activated

and

flespi/interval/gw/calcs/{id}/devices/+/deactivated

These are dedicated events that trigger when the current state of the object's telemetry data changes.

Below is a detailed timeline explaining the difference between the active and activated/deactivated topics for better understanding:

"active" topic

"activated"/"deactivated" topics

  • Published with all last interval updates while the last interval is active.

  • When there is no last interval or the last interval is not active, N/A (null) is published once to the "active" topic.

  • Published once when the current calculated device state becomes active or inactive. 

  • Is not updated as the interval updates if no device state change happens.

  • Will not be published if the device state did not change between the intervals.

  • Two activated or deactivated events cannot go in a row — they should trigger in turns.

Note: the payload for these topics is the last known interval JSON.

These new topics will reflect the state of the device currently known to flespi. If you receive the activated event, it means the interval configured in the calculator's selector has started and is active right now. 

Important! If it was activated somewhere in the past (by uploading a blackbox for example) and currently the last interval is not active, you will not receive this event. In other words, activated/deactivated topics work only with real-time events and cannot be attributed to the intervals post factum.

Real-life example

Task: catch the moment when the person (we use the Wiatag software tracker for this test) exits the designated geofence.

Solution: 

  • create a calculator with the geofence selector around the desired area and configure it similar to what is shown on the screenshot below:

calculator geofence selector

  • create the counters necessary to extract the required data for the interval; here we catch the time of geofence exit, the location (latitude and longitude), ident of the device, geofence being crossed, and some other data:

calculator counters config

Result: 

We subscribed to the topics discussed above using MQTT Board in advance to see when they get updated. Here’s what we got:

mqtt board interval activated topic

and

mqtt board interval active topic

Note the “time-left-geofence” value — it indicates the time the device exited the specified geofence. The difference between active and activated is that activated is only published once (when the interval starts) and active is published with the first topic of the new interval and then the topic will publish N/A (null) with each new message that goes into the current interval. This makes the activated topic more convenient for catching the change of state events.

You can check the generated intervals by opening the target device -> Logs & Messages tab -> Intervals

device intervals logs and messages

If you need to catch these events in your solution, you can use the MQTT channel and forward it to your system with standard flespi streams.

More logs, more clarity

Another significant advancement in the flespi analytics module is the improved verbosity of the log records — calculators, intervals, and all related events are now much easier to debug. The Logs & Messages tab of the calculator now contains log entries about the following events:

  • synced/unsynced — recorded once the device assigned to the calculator changes its synced state. When the device is assigned to the calculator, the analytics engine should run a calculation job for it. If the state is unsynced, the calculation job is not completed yet. Once all initial calculations are made, the synced event is generated. This event reflects the state of the calculation system — whether it works fine with the device or is suspended for some reason.

  • created/updated/deleted — recorded once the respective interval event occurs. Can be used to assist you in debugging your listeners for MQTT events.

  • activated/deactivated — recorded when the current state of the object's telemetry data changes.

calculator logs

***

The MQTT coverage of the flespi analytics engine is becoming more elaborate and contributes to its wider applicability. With the new events, it became more intuitive to set up a notification system based on the change of specific parameter states while more detailed logging contributes greatly to quicker troubleshooting and a better understanding of the behind-the-scenes processes on the platform.