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. If you want to access per-device data (e.g. configured speed limit) in the expression you may use device metadata for this.
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 inside specified geofences (or outside them if the invert option is on). A geofence can have one of the following types: a circle, a corridor of a certain width, or a polygon (up to 1024 points). Together with this selector, you may use the geofence counter to visualize the name of the triggered geofence.
inactive — create interval when gaps between messages or their reception latency is above the specified threshold. This selector also switches the assigned device to the "active" state if there are no messages from the device within the specified latency threshold. Usually is used to detect inactive devices in realtime or connectivity problems in historical messages.
calc - use another calculator to select intervals from messages. Can be used to detect the same intervals as in referenced calculator or reversed/opposite (e.g. parkings for trips). Special validate_interval filter can be used to reference only specific intervals. If intervals in referenced calculator are changed this calculator will automatically recalculate own intervals as well. When used in reverse mode it is desirable to match min_active value to max_inactive for both calculators to have maximum consistency in the behavior of both calculators.
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
}Use these options to fine-tune 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}/calculate REST API call.
merge_unknown — when true, if we have an active interval and the 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 the expression or in a geofence type selector when there are no coordinates in the message.
max_messages_time_diff — if non-zero, specifies a maximum timestamps difference between the two consecutive messages to include into the same interval and to apply logic described above with merge_xxx options.
Example: "max_messages_time_diff=60" would mean that messages closer than 60 seconds apart will be registered into the same interval; messages further than 60 seconds apart will be registered into different intervals.invert — when true, evaluation of interval state for the message should be inverted, e.g. ON will become OFF.
Example: if you have a geofence selector and want to detect when a device leaves this geofence (in contrast to detecting when a device gets into the geofence), you want to enable the "invert" property.validate_message — only messages passed this filter will be checked by the selector for markup. All intermediate messages will be ignored during selection phase but will be available for counters.
min_active — if non-zero, all intervals with duration in seconds less than specified will be skipped.
Example: "min_active=300" would mean that intervals shorter than 300 seconds will not be registered.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.
Example: "max_active=600" would mean that when the interval reaches the duration of 600 seconds it will be stopped and the new interval will be immediately started.max_inactive — if non-zero, inactive parts of intervals with duration shorter than the specified number of seconds will count towards the current interval and will be merged with the preceding and following active parts. Also, this property can timeout an active interval for the assigned device.
Example: If you want to detect trips and parkings but do not want to consider stops at traffic lights as parkings, you specify this property with the value greater than the maximum duration of stop at traffic lights. If you set "max_inactive=60", stops shorter than 60 seconds will count towards the current interval.min_duration — if non-zero, specifies the minimum combined interval duration.
Example: "min_duration=300" would mean that the minimum duration of the resulting interval after combining all parts accounting for the specified max_inactive value should be 300 seconds, otherwise such interval will be skipped.
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}, ...]
...
}