Statistics and value info

Besides the plain value of a device, a script variable can hold a statistic of the device, or information about a value: when it last changed, its previous value and the values of finished periods. Both are picked in the device value picker of the script editor.

Statistics#

Besides the plain device values, the device value picker offers the statistics of the device (section Statistics): the statistics the user enabled on the device or that the device provides itself, for example the minimum, maximum, average, count or sum of a value over a period. A variable picked this way holds the value of that statistic:

• A Current period statistic, for example the average of the current hour, is calculated from the start of the running period — the hour, day or month — up to now.
• A Period to now statistic, for example the average of the last 24 hours, is calculated over a sliding window of the given length that ends now.

# Se was picked as the 1-hour average of Temperature (current period)
IF Se > 25
    RETURN(1);
END
0;

Values of finished periods are not part of the statistic itself; read them from the Value info of the statistic.

Value info#

Input variables of the Equation, Formula and Script smart rules, of the Formula limiting condition and of notification texts can also be picked as Value info; the picker lists it as Value info of name of the value, both for a plain device value and for a Current period statistic. Such a variable does not hold a number but information about the value:

Value info does not contain the value itself. To work with the value and its information together, add the device value to the script twice: once as the value (for example Se) and once as Value info (for example SeInfo).

Available — Core 2026.1 on TapHome Next, build 36599 or newer (not yet in the official release).

Current and previous value#

Current describes the last change of the value:

Current is Null until the value changes for the first time — check it with ISNULL before reading its properties.

Example — a window open for more than 10 minutes

# Wi = window contact (1 = open), WiInfo = Value info of the window contact
IF ISNULL(WiInfo.Current)
    RETURN(0);
END
IF Wi = 1 AND WiInfo.Current.CurrentValueTime < DATETIMEADD(NOW(), 0, 0, 0, 0, -10)
    RETURN(1);
END
0;

Example — is the value rising or falling

# Se = Temperature, SeInfo = Value info of Temperature
IF ISNULL(SeInfo.Current) OR ISNULL(SeInfo.Current.LastKnownValue)
    RETURN(0);
END
VAR change := Se - SeInfo.Current.LastKnownValue;
IF change > 0
    RETURN(1);
ELSEIF change < 0
    RETURN(-1);
END
0;

History of a statistic#

For a Current period statistic, History holds the values of the periods that already finished:

How many periods are kept depends on the period of the statistic and on whether history recording is enabled for it — the history switch of the statistic on the Statistics page of the device:

For any other period (1, 2, 3 and 30 minutes, 12 hours, 2 and 3 days, 1 week, 1 quarter) and for a Period to now statistic, History is Null. Values can be shorter than the number of kept periods, for example shortly after the statistic was enabled — check LENGTH before reading an index that may not exist.

Example — today’s consumption so far compared with the whole of yesterday

# En = daily sum of Energy (current period), EnInfo = Value info of the same statistic
VAR yesterday := GETAT(EnInfo.History.Values, 0);
IF ISNULL(yesterday)
    RETURN(NaN);
END
En - yesterday;

Example — average daily consumption of the last 7 days

# EnInfo = Value info of the daily sum of Energy (current period)
AVG(COPY(EnInfo.History.Values, 0, MIN(7, LENGTH(EnInfo.History.Values))));

COPY takes the first 7 days — MIN covers a history shorter than 7 days, because COPY beyond the end of the collection is an error — and AVG skips the days without data. MIN, MAX and AVG skip Null, so a whole history can also be used directly:

# SeInfo = Value info of the 1-hour maximum of Temperature (current period)
MAX(SeInfo.History.Values);
# Result: the highest temperature of the kept hours

See also — Variables and constants, MIN, MAX and AVG, COPY.