Automatically translate this page?

Calculators — preconfigured algorithms for intervals extraction and calculation

Preconfigured algorithms storage for intervals extraction and calculating

Calculators are the part of the flespi analytics engine used to describe custom logic to extract intervals from devices messages. 

Once you have created and configured a calculator, it is possible to refer to its configuration from GET /gw/devices/{selector}/intervals REST API call instead of specifying selectors and counters in the API call parameters. Thus calculators simplify the usage of flespi analytics engine in manual mode

But the primary goal for using calculators is to let flespi do all the calculations automatically in the background. To do so, you need to assign devices to a calculator. Once the devices are assigned, their intervals calculation will start promptly. And once the calculation for the device is finished, the assigned device will get the synced=true attribute, and from that moment you can request intervals and even attach your own information to them via GET|PUT /gw/calcs/{selector}/devices/{selector}/intervals/{interval-selector} REST API calls.

Calculator configuration that you will need in both automatic and manual modes consists of:

  • interval selectors which task is to split all source messages into intervals, where each interval has begin time, end time, and duration. It is possible to have intervals consisting of one message only, i.e. with zero duration. 
  • "validate_message" contains a boolean expression that will check if a message is suitable for any kind of calculations for interval selector at all. You can use it to completely skip messages that do not contain a certain parameter for example.
  • counters that perform specific calculations with each interval (for all its messages) and generate a JSON field in the final interval with their name and calculated data, like "mileage" and "positions" in the sample above. Extra option "validate_interval" contains a boolean expression that will check generated interval JSON representation and may filter it out if validation fails.
  • "timezone" with which you may specify timezone to be used in all counters and selectors.

Additional calculator configuration for automatic mode consists of:

  • "update_interval" specifies how many seconds a calculator should wait from the moment it received the new message before it will start recalculation. The default value is 10 seconds and it may be not desirable in some systems, especially relying on interval detection for flespi. For near real-time processing, you may specify 1-second interval here and for the bigger delay and lower traffic, you may put 60 seconds or even more.
  • "intervals_ttl" contains the duration of history storage for calculated intervals. Intervals usually weigh much less than raw messages from devices (about 1% of it) and you may configure a calculator to store intervals for a few years while device messages can be stored for a few days or months only.
  • "messages_source" is the most interesting option as using it you may specify that source for the interval calculation will be not messages from the device but interval messages from another calculator. This is usually used to calculate statistics over a date range, e.g. you may have a calculator for each individual trip and have one calculator on top that will calculate daily stats for all trips - how many trips were done, what the total duration and mileage are, etc.

If a calculator is configured to take source messages not from a device but from another calculator, make sure that your counters are referencing different parameters. For example, you may have trips calculator with a mileage counter of type="expression" and expression="mileage()". To detect trips it will use selector of type="expression" with expression="mileage()>0.01" — e.g. detect any movement based on the GPS signal. Do not forget to specify other properties in interval selector to correctly filter false trips and merge all short trips into one like: max_inactive=120, max_messages_time_diff=600, min_duration=120, merge_messages_before=true. And also validate_interval="mileage>0.5" to filter trips with short final mileage.

After assigning devices to a calculator you will have information about their detailed trips. But now you may want to have monthly stats calculated by flespi. You can do so by creating an additional calculator with messages_source={"type":"calculator","calc_id":ID} and referencing the ID of the previously created calculator. The selector will be type="datetime" with split="month". Now you want totally different counters. For example, to calculate mileage you use the counter with type="expression", expression="mileage", method="summary" to summarize all trips' mileage into a single number. And to have the total quantity of trips within a month you may use the counter with name="trips_count", type="expression", expression="1", method="summary".

Once you have configured the calculator the next step will be to assign devices to it.

Analytics system is being in active development at the moment and all API calls described here are 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.
Handling events, accessing intervals, and attaching custom data to calculators