Calculators are the part of the flespi analytics engine used to describe custom logic to extract intervals from device messages. Their primary goal is to let flespi do all the calculations and aggregation of device information 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 via GET /gw/calcs/{selector}/devices/{selector}/intervals/{interval-selector} REST API call and even attach your own information to each interval using PUT REST API call.
Calculator configuration 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.
- "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_delay" specifies how many seconds a calculator should wait after the moment it received the new message to start recalculation. The default value is 10 seconds. For near real-time processing, you may specify a 1-second delay while for better notifications accuracy and lower number of interval events, you may set a 60-second delay or even more. Be aware that analytics may activate additional throttling for your interval detection events if the logic in selectors or counters is too heavy, intervals are too long or update_delay value is too low. This throttling system is activated automatically and maximum additional delay it can add is 2 minutes. That's why our recommendation for update_delay value is to keep it from 10 to 30 seconds.
- "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.
- "intervals_rotate" — if non-zero, specifies maximum storage size for calculated intervals per each assigned device. If newly detected intervals overflow specified size, earlier intervals will be removed automatically from the storage. This parameter may be used to limit the maximum storage size for the calculator.
- "update_period" specifies a valid interval update period from the current moment. During any recalculation, all intervals with end time outside this period will be ignored. Even if recalculation was triggered by the calculator parameters change. If set to standard value like 30-60 days, this parameter is a good way to ignore any outdated messages and retain all generated intervals as is until they are auto-deleted by intervals_ttl. The best usage is when update_period < messages_ttl(device) < intervals_ttl.
- "update_onchange" — controls the behavior of analytics system when calculator configuration is changed. With TRUE value (default) the system will synchronize all devices intervals according to a new calculator configuration within update_period (10 days by default). So if you change selectors, counters, or validation fields — you will almost immediately see the effect with intervals created, updated, deleted events. While FALSE value will prevent any automatic synchronization to currently existent intervals and will only use the new configuration for new device messages processing. This is convenient to set in production level calculators with thousands of devices assigned to prevent flooding of your handlers with intervals update events.
- "messages_source" allows specifying the data source for the interval calculation — it can be either raw messages from the device or 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 parameter names same as counters defined in another calculator.
Once you have configured the calculator the next step will be to assign devices to it.
The calculator can store up to 10 years of historical information per each assigned device. This is an efficient option to save your flespi storage costs because the size of information aggregated by calculator is just a fraction of the size used by device messages. However if you unassign the device from calculator or delete the calculator you will loose that information. And there is no possibility to move calculator between subaccounts but you can use grants to provide access to the calculator from another account. So if you are want to store in calculator aggregated device data for 10 years ahead the careful account structure design should be done in advance.