thresholding
Usage
>> thresholding [ enabled | state | channelindex | channellabel | condition | value | interval ]
Security
Unsafe.Description
Reports or sets the parameters which control threshold gated sampling. The <parameter>s currently supported are:- enabled [= <enabled>]
- true, enables the threshold gating feature.
- false, disables the threshold gating feature.
- state is a read-only parameter which shows whether logging is currently paused or running due to the thresholding configuration, or n/a because thresholding is not enabled or because logging has not yet been enabled.
- channelindex [= <index>] the index of the channel to use for the threshold check. This must be a channel that exists in the logger; the first channel has an <index> of 1. The channel must also have a valid calibration, because the comparison of data readings with the threshold value is made in calibrated units.
- channellabel [= <label> ] the label of the channel to use for the threshold check. This must be a channel that exists in the logger; the first channel has an <index> of 1. The channel must also have a valid calibration, because the comparison of data readings with the threshold value is made in calibrated units.
- condition [= <condition>]
- above, sampling will occur when the monitored parameter is above the specified threshold value.
- below, sampling will occur when the monitored parameter is above the specified threshold value.
- value [= <value>] specifies the threshold value in calibrated units, given as a number compatible with floating point formats.
- interval [= <milliseconds>] specifies the interval between threshold checks. The value is given and reported in milliseconds, but must correspond to a non-zero whole number of seconds, and not be greater than 24 hours (86400000ms).
The basic validity checks on parameters indicated above are performed immediately. Further checks may result in error messages at the time the logger is enabled; for example, setting a threshold check interval shorter than the logger can achieve in its programmed operating mode is not permitted.
Threshold-gated sampling is used to turn recording of data on or off, depending on the data value monitored from the selected channel.
When data recording is on, the logger is in the logging state. Readings from all channels are acquired, stored and otherwise processed according to the logger's programmed settings and schedule parameters. When data recording is off, the logger is in the gated state. Readings from only the selected channel are taken at the specified interval, and compared to the threshold value; they are not stored or otherwise processed.
When a logger is enabled with thresholding activated, it will initially assume the gated state if the start time has already passed. If the start time is in the future, the logger will initially be in the pending state, and move to the gated state when the start time is reached.
When in the gated state, if the reading from the selected channel satisfies the programmed condition (above or below) when compared to the threshold value, the logger will move to the logging state and begin to acquire and record data normally. In most situations normal sampling will begin immediately, but it is possible for there to be a delay. For example, if the thresholding interval were 15 seconds, the sampling period 10 seconds, and a transition occurred at a time hh:mm:15 , the next scheduled sample would not be due until hh:mm:20 , so there would be a 5 second delay.
When in the logging state, the reading from the thresholding channel is still monitored at every sample time. If it no longer satisfies the programmed condition, the logger will move back to the gated state. However, this does not happen immediately. The logger remains in the logging state for a guard time of 10 seconds after the thresholding condition first fails; only if readings from the thresholding channel fail to satisfy the condition for 10 seconds continuously does the logger actually move to the gated state. If at any point during the 10 second guard time the condition is once again satisfied, the logging state persists and the guard time is reset, awaiting another possible transition.
This behaviour prevents data acquisition being interrupted by short episodes during which the thresholding condition is not satisfied.
Examples
<< thresholding enabled = false, state = n/a, channelindex = 1, channellabel = temperature_01, condition = above, value = 20.0000, interval = 15000
Threshold gating is not enabled; if it were, the logger would check the value read from Channel 1 every 15 seconds, and start normal sampling if above 20.0.
<< thresholding value = 17.5000, interval = 10000
The gating parameters are changed so that the logger would check Channel 1 every 10 seconds, and start normal sampling if the value were above 17.5.
<< thresholding enabled = true
Threshold gated control of sampling is enabled.
Errors
Error E0109 feature not available
The logger is not configured to support threshold gated control of sampling.
Error E0105 command prohibited while logging
Settings may not be modified while logging is in progress; reading them is permitted.
Error E0108 invalid argument to command: '<invalid-argument>'
The command was given with an argument which is unrecognized or has an invalid value; for example "thresholding enabled = yes", or "thresholding interval = 10".
Error E0601 no calibration for channel '<channel-index>'
The channel selected for threshold checking is not calibrated.