When making scripts, time [t] is a very important aspect. The following points should be taken into consideration:
The timestore
- When referencing back to previous values (e.g. IN[t-1] for sensor IN), the script gets these values from a sensor's timestore, which lists recent sensor values, sorted by their timestamp. When a script asks for a value, it sends a timestamp at which to check the value. The timestore will move through its values from oldest to latest and find the last known value at the queried timestamp.
- This timestore does not necessarily contain all the sensor's past values. When referencing physical and virtual sensors, with a sensor frequency of 1 per second to 1 per minute, the timestore covers the equivalent of the last 65 mins. If the physical or virtual sensor has a different frequency the timestore holds previous sensor values for the equivalent of 65 x the sensor frequency. So, for example, a sensor with a frequency of 1 per hour, would have a timestore of 65 hours.
- When referencing manual and time-based sensors the timestore's capacity always covers the equivalent of the last 65 seconds.
- The timestore only expires values in response to new ones, so if no new values come in, the old values will remain. This means that if a sensor is yet to output new data after a time of being idle, any scripts using that sensor will still resolve, based on the last known value(s).
Waiting for input sensors
- Scripts are executed at fixed intervals, defined by the output sensor's frequency. When a script executes it files a request for the input sensor's value at a certain time as defined in the script's body (for instance, 'IN[t]' resolves to the current time while 'IN[t-1]' resolves to a time in the past). On the first attempt, the input sensor will try to find the value that was valid at that time and return it in most cases. However, the scripting system takes potential input delays for sensor values reaching our servers into account and can decide to wait for new values to arrive if certain conditions aren't met. This means that your script can delay its execution by 5 seconds. Whereas most scripts will make only 2 attempts if a delay is necessary, scripts executing every second will make up to 5 attempts, with 1 second intervals between them. Although these high-frequency scripts can also experience delays of up to 5 seconds, the extra attempts give them a chance at resolving sooner. Whenever a script is delayed, its next planned execution will not be lost. In other words, a delay will never result in data loss.
Missing value strategy
Each sensor is configured with a so-called 'missing-value-strategy' (MVS), found in the 'advanced' section of the sensor's page in the Admin app. This setting can affect how your scripts behave when the input sensor's timestore is unable to return a requested value.
- The MVS is only applied if, even after waiting (as described above), the timestore cannot return a last known value, either because:
- It is entirely empty.
- It doesn't (yet) have a value for a past timestamp at which the script queries.
- The script queries at a timestamp beyond the timestore's limits.
- The MVS has two possible settings. By default, it is set to 'do nothing'. If new data is not found, the script will go into a 'suspended' mode. It will stop executing at its configured frequency and will instead sit and wait until one of its input sensors produces a new value. When that happens, the script goes back to its 'initial' state and waits for its next execution cycle to be triggered (i.e. at the configured frequency).
- When the second setting ('use 0 as value') is selected, the input sensor will return the value '0' if no actual value at or before the requested time can be found. This allows the script to resolve. Use this setting if you wish to jump start a script with input sensors that have not yet produced the necessary amount of data (for instance because they are new) and a returned '0' value is sufficient. We recommend changing this back to the default setting once the sensor has produced the data necessary to get the script running.
- Note that a single input sensor doesn't necessarily determine the script's response, namely if a single input sensor fails to return a value (i.e. it has the 'do nothing' strategy configured & its timestore didn't contain a last known value for the queried timestamp) the script will do nothing, regardless of the strategies of its other input sensors, because the script can only resolve if all of its input sensors return a value (be it an actual last known value, or the default of 0).
Typical Scenarios
- If the script references data values before those values have been generated, then the script will first wait up to 5 seconds and try again. If there are still no values at or before the referenced time, then the script will fall back to its missing-value-strategy, the default setting of which is to go into 'suspended' mode. This applies not only when referencing sensors but also to values generated within the same script. When referencing a sensor which at that moment has no previous data in its timestore, there are three options:
- Wait until all input sensors have produced the data required, before activating the script.
- If the script requires past data from an output sensor, a separate script can provide that sensor with some initial datapoint(s).
- The missing-value-strategy (found in the 'advanced' section of the sensor's page in the Admin app) is configured to 'Use 0 as value'. We recommend changing this back to the default setting once the sensor has produced enough data to get the script running.
Example 1:
Script A refers to the data value produced by Sensor X, 30 mins ago. Thus, Sensor X needs to produce data for at least 30 mins before Script A is activated.
Example 2:
Script B refers to the data value produced by the script at an earlier point. This means that a script output sensor is also used as an input sensor. Either a second script should be configured that provides the sensor in question with values for the required duration or the missing value strategy could be changed temporarily.