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 part of the configuration. 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 the last detected interval is currently active will have the same value as last, otherwise N/A (null). This topic can be used to track active intervals when they appear (triggered) and disappear (no 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 or active interval is timeouted due to max_inactive interval selector property.

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 is specified, only messages within the boundaries will trigger intervals calculations. All previously detected intervals outside the specified boundaries 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 the specific interval or when you need to attach custom data to it, use GET|PUT /gw/calcs/{calc_id}/devices/{device_id}/intervals/{interval_id} API call. Once custom data is attached to the interval, the updated event will be generated and if this is the last interval, then the last retained MQTT message will also be generated with all merged fields automatically calculated by counters and custom fields attached by user.

And on top of this, it is possible to manually calculate generalization intervals on top of precalculated ones. 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.


See also
Step-by-step instructions on how to connect a GPS tracker to flespi and access its messages.