Working with devices assigned to a calculator

After configuring a calculator that will extract and calculate intervals from device messages, you can finally activate the 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 fill-ups or consumption, 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).

Two more topics without retained messages are important if you want to build a notification system on top of flespi analytics. The payload for these topics is the last known interval JSON:

• flespi/interval/gw/calcs/+/devices/+/activated — the event fires when the device assigned to the calculator becomes active according to calculator configuration. For example, if the selector is ON when the device is inside a defined geofence, this topic will be published when the device enters the geofence for the first time.
• flespi/interval/gw/calcs/+/devices/+/deactivated — the event fires when the device assigned to the calculator becomes inactive according to calculator configuration. For example, if the selector is ON when the device is inside a defined geofence, this topic will be published when the device exits the geofence after being inside.

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 the active interval ends due to the 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 (calc_id's are unique within one device). You can use field "report_reason" to understand the reason of the event (new message from device, initial calculation, etc). Full list of actual reason codes is available in the table below. Same "reason_code" is available in all MQTT interval event messages as user property.

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 to 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 the 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.

Interval event reason codes

By using reason_code field from interval event you can understand what was the reason of interval calculation. We define next reasons: