SiteWise Machine-State Duration: Separate Window Occupancy from a Completed Run

“How long was the machine in state 1?” can request two different outputs: seconds occupied during each reporting window, or the length of a complete state episode when it ends. AWS IoT SiteWise’s statetime and a transform using the previous observation do not automatically answer the same question.

Begin with a single chronological stream containing good 0/1 observations. State 1 here means a fictitious laboratory operating mode. No alarm, equipment control or live SiteWise calculation was exercised.

Calculate window occupancy on one timeline

Use an original synthetic sequence:

t =   0 seconds: state = 0
t =  20 seconds: state = 1
t = 130 seconds: state = 0

The episode begins at t = 20 and ends at t = 130, so its complete duration is 110 seconds. With sixty-second reporting windows, however, occupancy is split across three results: 40 seconds in the first window, 60 in the second, and 10 in the third.

The SiteWise temporal-functions reference defines statetime(x) as seconds for which the input is positive during the metric interval. For the declared 0/1 stream, statetime(state) is therefore the window-occupancy quantity. The values 40, 60 and 10 sum to the completed episode’s 110 seconds, but no individual window result represents that complete episode.

Write the required output event beside the quantity. A periodic report asks for each window’s occupancy. An episode report asks for one result when a state transition closes the episode. A dashboard label that says only “duration” hides that distinction.

Add a same-state report without changing the episode

Now insert another good observation at t = 80 with state still equal to 1. The machine-state interpretation is unchanged: the same episode runs continuously from t = 20 to t = 130. Window occupancy remains 40, 60 and 10 seconds.

The previous observation at the closing transition is different, though. Immediately before the t = 130 observation, the preceding point is now t = 80 rather than t = 20. Subtracting those observation timestamps gives 50 seconds, not the whole 110-second episode.

That difference is the central acceptance test. A duration implementation that changes its reported episode length when a redundant same-state observation is inserted is measuring something other than the complete episode under this contract.

Understand what pretrigger supplies

The same temporal-functions page explicitly documents pretrigger() for transforms as retrieving a variable’s prior GOOD value relative to the update that triggered the calculation. It is a previous-observation facility, not an automatic record of the last state-entry transition.

For this one-input sequence, pretrigger(state) at t = 130 refers to the t = 80 observation. A formula subtracting its timestamp from the current timestamp obtains the 50-second interval just identified. If a formula emits whenever the previous value is 1, it can also emit at the repeated t = 80 report while the episode is still open.

Checking that the current state has become 0 can restrict emission to an exit transition. It does not restore the lost entry time when same-state reports have replaced the immediately previous observation. Both event selection and start-time retention must match the requested output.

The dedicated temporal-functions section is the precise source for this pretrigger transform exception. Do not infer that every temporal metric function is valid in a transform from this one supported function.

Preserve transition state when complete episodes are required

A proposed stateful episode tracker would preserve the entry timestamp until an exit, rather than updating it on every report:

on a known 0 -> 1 transition: remember the entry timestamp
on another 1 observation:    retain the same entry timestamp
on a known 1 -> 0 transition: emit exit time minus entry time

This is application pseudocode, not a SiteWise formula or a claim that pretrigger supplies persistent episode storage. The tracker could belong in a separately designed processing stage. Its storage, restart and error behavior need qualification before use.

Alternatively, a guaranteed transitions-only stream makes the previous observation at an exit coincide with the episode entry in this simple case. That guarantee must be explicit and tested at the actual ingestion boundary. A periodic source is not transitions-only merely because most successive values happen to differ during one demonstration.

Qualify unknown beginnings and interrupted evidence

Test the base sequence and its repeated-state variant. Require identical complete-episode results and identical per-window occupancy while preserving their different output schedules. Also start a fixture with state 1 but no known entry time: the tracker should expose an unknown beginning rather than inventing one at startup.

Declare how missing, bad or out-of-order observations affect episode validity. The chronological good-data example does not prove continuous physical state across an evidence gap or after a processing restart.

The useful result is an agreed quantity, emission event and observation contract. Keep window occupancy, time between reports and complete-episode duration separately named so that a plausible number cannot conceal the wrong measurement.