Automatically translate this page?

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 devices 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.

  • geofence — select intervals when message coordinates are in/out of specified geofences. Each geofence can be specified either as a polygon or as a circle.

Each interval selector has 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 that will evaluate to ON or ON_NEW. Then, 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_inactive — if non-zero, inactive parts of intervals with duration in seconds less than specified can be merged in one combined interval.

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

If multiple interval selectors are specified, they will be merged with AND logic, e.g. 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}, ...]
  ...
}

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
How to calculate vehicle engine hours on a daily basis
Instructions on how to use flespi analytics engine to extract trips from raw device messages