Intervals selectors — build intervals from messages

Intervals selectors are used to split devices messages into intervals based on custom logic

Intervals selectors are used by the analytics engine to split device messages into intervals based on user-defined criteria. Resulting intervals will have begin, end times, and duration. It is possible to have intervals that consist of one message only, i.e. with zero duration.

The following types of interval selectors can be used in flespi:

  • expression — allows specifying an interval state based on expression evaluating message parameters. Two methods are allowed for the expression selector: “boolean” (default) — meaning the expression will be evaluated as a boolean and “change” — meaning the new interval will start when the expression result changes.

  • datetime — allows beginning/ending an interval when the current time equals a specified hour/day/week/month/year in a specified timezone. If the timezone is not specified in the selector configuration, the default timezone should be defined in the request parameters.

  • geofence — select intervals when message coordinates are in/out of specified geofences. A geofence can have one of the following types: a circle, a corridor of a certain width, or a polygon. Together with this selector, you may use the geofence counter to visualize the name of the triggered geofence.

Each interval selector has its own internal logic described above, determines the state of each analyzed message sequentially, and assigns each message one of the following:

  • ON — interval can continue

  • ON_NEW — interval should restart

  • OFF — interval should stop

  • UNKNOWN — unable to calculate

So, to detect one interval it is enough to have at least one message marked ON or ON_NEW. On top of this, there are some standard parameters for the detection algorithm that can be specified almost for each type of interval selector:

"merge_message_before": boolean,
"merge_message_after": boolean,
"merge_unknown": boolean,
"max_messages_time_diff": uint32,
"invert": boolean,

"min_active": uint32,
"max_inactive": unt32,
"min_duration": uint32

They are used to set up precise interval selection:

  • merge_message_after/merge_message_before — when true, the interval will be automatically extended by one message with OFF/UNKNOWN state in each direction. Usually used together with extend=true in GET /gw/devices/{selectors}/intervals REST API call.

  • merge_unknown — when true, if we have an active interval and current message state is unknown, it will be appended to the active interval. The unknown state can appear in an expression type selector when a message does not contain a parameter specified in expression or in a geofence type selector when there are no coordinates in the message.

  • max_messages_time_diff — if non-zero, specifies maximum timestamps difference between previous and next message to include it into the interval and to apply logic described above with merge_xxx options.

  • invert — when true, evaluation of interval state for the message should be inverted, .e.g. ON will become OFF.

  • min_active — if non-zero, all intervals with duration in seconds less than specified will be skipped.

  • max_active — if non-zero, during sequential interval detection when the duration of a currently detected interval exceeds the specified value in seconds, the new interval will be started.

  • max_inactive — if non-zero, inactive parts of intervals with duration less than the specified number of seconds can be merged in one combined interval. Also, this property can timeout an active interval for the assigned device.

  • min_duration — if non-zero, specifies the minimum combined interval duration.

If multiple interval selectors are specified, they will be merged with AND logic, i.e. only ranges where all specified interval selectors are active will be present in the final intervals. 

Once the analytics engine determines the final intervals, it will separately calculate counters for each interval. 

Finally, the interval will be represented as a JSON message with a set of fields where "begin", "end", and "duration" (also "id" for automated 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}, ...]

See also
A comprehensive guide on the key concepts and principles of the flespi analytics engine.