Automatically translate this page?

Working with devices assigned to a calculator

Handling events, accessing intervals, and attaching custom data to calculators

After configuring a calculator that will extract and calculate intervals from device messages, you can finally activate automatic flespi analytics engine and enjoy its power and performance. The intended usage is to:

  • Get instant access to precalculated device data for reports.
  • Receive notifications about certain events happening to devices.
  • Store calculated device data for years in a compact format.
  • Rely on flespi for intervals detection, handle their create/update/delete notifications and apply custom logic to them.
  • Integrate data from the third-party system to flespi and inject additional information into detected intervals, e.g. fuel filled or consumed, goods deliveries occurred, customer information.

Calculator is only a configuration part. All automatic work starts only when devices are assigned to the calculator. Once this happens, they will soon synchronize the state and calculate intervals according to the calculator configuration. In MQTT API the most important topics for their state are:

  • flespi/state/gw/calcs/+/devices/+/synced — contains true or false for the current synchronization state of a given device calculator. You may rely on the calculated intervals only when this property becomes true.
  • flespi/state/gw/calcs/+/devices/+/last — contains the last detected interval. This is a convenient topic if you want to understand the current status of a device, e.g. its current geofence position, current trip or parking. Pay attention to the "timestamp" attribute of this message as it contains the time when the given state was updated. 
  • flespi/state/gw/calcs/+/devices/+/active — in case last detected interval is currently active will have same value as last otherwise N/A(null). Can be used to track active intervals when they appear(triggered) and disappear(n more actual).

Once the device sends a message (even from a black box or in reverse mode), the system will recalculate intervals and their counters and will merge these updated intervals with the previously calculated ones. It will also recalculate intervals if the calculator configuration changes. 

Each interval is represented as a JSON message with a set of fields, where "begin", "end", "duration", "id" and "timestamp" are always present and other fields appear only when a counter with such name is defined in the call:

"id": 100,
"timestamp": 1490348123,
  "begin": 1490347944,
  "end": 1490347948,
  "duration": 4,
"mileage": 190.2,
"work_hours": 0.12345,
"max_speed": 120,
"positions": [{"t":1490347944, "lat":53.0923, "lon":27.12}, {"t":1490347944, "lat":53.0923, "lon":27.12}, ...]

All automatic actions with intervals are reported to the topic flespi/interval/gw/calcs/{calc_id}/devices/{device_id}/{event_type} and payload is the full interval message with "id" attribute that can be used for unique interval identification.

To receive all interval updates from all devices, you may subscribe to flespi/interval/gw/calcs/+/devices/+/+ topic.

Once an interval is generated, the analytics engine will try to find intersections with existing intervals. If found, flespi will use the ID of the first existing interval, modify it, and generate the updated event. If no intersections are found, the newly generated interval will be assigned its own ID and flespi will generate the created event. All existing intervals that should not exist anymore will receive the deleted event and will be deleted from the intervals storage.

Anytime it is possible to enable and disable the device assigned to the calculator to activate or deactivate the automatic calculation engine. When disabled it will not react on any incoming messages from the device and will not modify intervals. But once enabled it will recalculate all intervals automatically and return back into the synced state.

For the assigned device, it is also possible to specify time boundaries for calculation. If time_begin or time_end specified, only messages within the boundaries will trigger intervals calculations. All previously detected intervals out of specified bounds will remain as is.

To access calculated intervals you can issue GET /gw/calcs/{calc_id}/devices/{device_id}/intervals/all API call. Each returned interval will contain automatically calculated fields plus any custom fields that you attached.

To access specific interval or when you need to attach custom data to it is, use GET|PUT /gw/calcs/{calc_id}/devices/{device_id}/intervals/{interval_id} API call. Once custom data attached to interval updated event will be also generated and if this is last interval, than last retain MQTT message will also be generated with merged fields from automatically calculated by counters and those custom fields attached by user.

And on top of this it is possible to manually calculate generalization intervals on top of precalculated. This can be done with POST /gw/calcs/{calc_id}/devices/{device_id}/calculate API call. In API call parameters you may use selectors and counters that will operate not with device messages, but with precalculated intervals messages.

Analytics system is being in active development at the moment and information here is a subject to change. If you intend to use this functionality for commercial projects, please let us know so we can make sure to notify you before applying incompatible API changes.

See also
The guide on how to set up a calculator to receive live customizable MQTT messages when device parameters change according to a complex condition.
Preconfigured algorithms storage for intervals extraction and calculating