Automatically translate this page?

Interval counters — calculate interval messages

Interval counters are used to calculate specific parameters for each interval

Once the analytics engine has split device messages into intervals based on custom logic, it's time to calculate all messages within each interval and extract valuable information. This can be done with counters

A standard interval message is represented as a JSON object with a set of fields, where "begin", "end", and "duration" (also "id" for automated analytics mode) are always present and other fields appear only when a counter with such name is defined during the call:

{
  "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}, ...]
  ...
}

Here "mileage", "work_hours", "max_speed", and "positions" fields are defined by counters. Each counter configuration contains the "name" field specifying the name under which the counter will be placed into the interval's JSON.

flespi defines the following types of counters:

  • expression — the value of a counter is the result of expression evaluation for each message in the interval. Special "method" field defines how these results will be combined into one number: 
    • first — take value from the first countable message;
    • last — take value from the last countable message;
    • average — take an average value;
    • minimum — take a minimum countable value;
    • maximum — take a maximum countable value;
    • summary — add all countable values;
    • difference — take a sum of all differences between neighbor messages;
    • duration — evaluate the expression as boolean and count duration for all non-zero results;
  • dataset — the value of a counter (like "positions" in the sample above) is an array of objects which field names and values are defined by the schema. The values for the fields are also evaluated as an expression. Dataset counter is used when you need to access each message fields and present them in an interval usually in a compressed form, for example, to draw a movement track on the map or display certain inputs on a state chart.
  • route — dump "position.latitude" and "position.longitude" parameters for each message within the interval into Google-encoded polyline algorithm format. This is a compressed string-based coordinates format with plenty of libraries to decode it into latitude/longitude pairs.
  • datetime — print the user-formatted begin or end time according to specified timezone into the interval. If timezone is not specified in counter configuration default timezone should be defined in the request parameters.
  • parameter — copy (usually textual) parameter value from the message into the interval. "method" defines which encountered valid message to use for the parameter source — either first, last or each. When each method specified the result of the counter will be an array of parameter values.
  • interval — evaluate the result of the expression that references already calculated interval parameters and attach it to the interval. This is useful when you want to calculate the average value, for example, an average speed which can be represented with the expression "mileage/duration", if mileage is already calculated for this interval using some special formula.
  • active — set counter value to true/false reflecting current unfinished state of interval. Applicable only for automatic intervals calculation or in manual mode when "to" border in request is unset. Will always write false for all intervals except for the last one. For the last interval if it is not yet finished - e.g. is running will write true value. Once interval will become inactive based on selectors criteria counter will write false. Can be used to run events that should by fired when something will be finished - e.g. go out of geofence or trip finished, etc.
  • geofence - store into the interval field the name of triggered geofence, if available. Usefull only with corresponding geofence selector.

All counter types except datetime and interval are dealing with device messages calculating each message according to the interval selector one by one. Datetime and interval counters use generated interval message and run on top of it. Note: When using interval type, pay attention to the order of counters — pre-calculated values used in the interval expression should all go above it.

Each counter also contains a "validate_message" extra option, which may check whether message suitable for the counter and skip some messages. This can be used for example to skip all messages with high HDOP or low quantity of locked satellites.

If you need more counter types, please contact us.

Analytics system is being in active development at the moment and all REST 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