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. Additional user property active contain values true or false, depending on the currently active state of the interval - is it running at the moment or not. Important notice: active or inactive state is based only on accumulated device messages and may not reflect current device status if it does not send telemetry information to the flespi gateway.

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.

When created and updated events are generated for the latest known interval additional user property active is attached to the MQTT message with values true or false depending on the state of last interval. This is convenient method to catch information about modified latest interval or its state.

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.

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