Appearance
History aggregates and energy (kWh)
Nexus can reduce a tag's history to a few numbers on the gateway, so a screen or script asks for "kWh today" and gets one value back instead of every sample. This page says what each aggregate means and how to get energy from a power tag.
The aggregates
| Mode | What you get for each bucket |
|---|---|
avg | The plain average of the samples stored in the bucket. |
min, max | The lowest and highest sample. |
first, last | The oldest and newest sample in the bucket. |
range | Min and max together. The trend charts use this. |
timeWeightedAvg | The average value over time, with each value weighted by how long it was held. |
integral | The value times hours, added up over the bucket. For a kW tag the unit is kWh. |
Every mode uses good-quality numeric samples only. A bucket with samples but none of good quality comes back empty, never as zero.
Why avg is not enough for energy
A tag that stores a row only when it changes, or that has a deadband, is stored in uneven bursts. Say a heater runs at 12 kW for 50 minutes and then shuts off, and Nexus stores one row for the start and five rows while it is off. The plain average of those six rows is 2 kW. The heater really averaged 10 kW over the hour, and used 10 kWh. timeWeightedAvg and integral give those figures because they count time, not rows.
How the time-weighted modes work
- Each good sample is held until the next sample. The next sample can be of any quality. A Bad, Stale or Uncertain sample (and a text sample) ends the hold before it, and counts for nothing until the next good sample.
- A value that did not change still counts. The bucket starts with the last sample stored before it. A tag that read 10 kW all morning and stored nothing still integrates to 10 kW times the hours in the bucket.
- A sample holds for at most an hour by default (
maxHoldSeconds). A tag that stores a row only when it changes keeps its last value while the gateway is down. Say a circuit read 10 kW, then the gateway was off for six hours. With the default, those six hours count as one hour of 10 kW and five hours of gap, andcoveredFractionshows the gap, instead of six hours of energy nobody measured. SetmaxHoldSecondsto0for no limit, or to a longer time if the tag really is stored that rarely. Tags that store a periodic row (a heartbeat) never reach the cap. - Time that has not happened yet is not counted. The newest sample holds up to now and no further, so "today" is the energy used so far today.
timeWeightedAvgdivides by the time that had good data, not by the whole bucket, so a gap in the data does not pull the average toward zero. Each bucket also reportscoveredSecondsandcoveredFraction. AcoveredFractionbelow 1 means part of the bucket had no good data, and theintegralis the energy for the covered part only.
Energy from a power tag
Historize the kW tag, then ask for its integral. The tag does not need a totalizer, and this works on history that is already recorded.
10 kW held for 90 minutes is 10 × 1.5 = 15 kWh.
In a Label, with no script
- Select the Label and click the binding button next to its Text property.
- On the History tab, choose the kW tag.
- Set Range to Today (since midnight). Use Last N Hours for a sliding window.
- Set Aggregate to Integral (value x hours, e.g. kWh).
- Leave Buckets at 1, so the Label gets one number.
- Set a Poll rate (for example 30 s). Leave it at 0 and the value is read once when the screen loads and never updates. Then click Apply.
- Leave Max hold at 3600 s unless the tag is stored less often than that (see above).
Today is the gateway's day: midnight in the time zone of the machine Nexus runs on, correct on the 23-hour and 25-hour days when the clocks change. A browser or Studio in another time zone shows the same number.
Type --- in the Label's own text. It shows until the first value arrives, and whenever the range has no good data. Format the number with a Format transform on the same binding.
With one bucket, a Format or Expression transform on the binding receives that number (not a list of points). With more than one bucket it receives the list of { timestamp, value } points, for a bar chart of hourly energy.
In a script
python
import time
now = int(time.time())
t = time.localtime(now)
midnight = int(time.mktime((t.tm_year, t.tm_mon, t.tm_mday, 0, 0, 0, 0, 0, -1)))
rows = raylux.query_history_aggregate(
"[DEFAULT]HeatTrace/Circuit1/kW", midnight, now, "integral",
buckets=1, connection="default") # add max_hold_seconds=0 for no limit
kwh = rows[0]["value"] if rows else 0.0raylux.query_history_aggregate(path, from_ts, to_ts, mode, buckets=1, connection="") takes Unix seconds (plus max_hold_seconds=3600) and returns one dict per bucket that has data. value is the figure the mode asked for; the dict also carries every other figure, plus covered_seconds and covered_fraction. An unknown mode raises ValueError.
Over the REST API
GET /api/history?path=<tag>&from=<ms>&to=<ms>&buckets=1&mode=integral
Add &maxHoldSeconds=<n> to change the hold cap, or use range=today in place of from and to for the gateway's day so far.
Each record holds integral, timeWeightedAvg, coveredSeconds and coveredFraction. An unknown mode is answered with 400.
Limits
- The history must be on for the tag. See Record the level's history.
- Very large ranges are refused, not guessed. The time-weighted modes read the rows in pages and stop after 5,000,000 rows (set
RAYLUX_HISTORIAN_MAX_SCAN_ROWSto change the limit). Past it, REST answers422, a script raisesValueError, and a binding keeps its static text and writes a line to the browser console. Narrow the range or ask for a coarser window. A day of one-second data is about 86,000 rows. - Rows are stored at one-second resolution. Several rows in the same second: the one stored last wins.
- If a tag's provider name was recorded in two spellings over time, a time-weighted query reads both and orders their rows together.