Note, in the first half of 2023 this rule template will be rewritten to only support JS Scripting and depend on the openhab_rules_tools.
Debouncing is a technical term for the following behavior. After an initial event, ignore subsequent event for a certain amount of time to give it time to settle. For example, in electronics, pressing a button may result in an initial press event but after releasing the button it may physically bounce a little sending several pressed and released events until it settles.
In openHAB there are a number of use cases where this overall approach can be applied in a larger context. For example, when detecting presence one may want to only count a person as away if they have been away for five minutes to prevent the home from going into away mode when the person simply walks to the mailbox and back. Sometimes a network can be a little flakey and a service may appear offline for a minute when it’s actually running so we want to wait for a couple minutes before alerting that it’s gone offline. There are many more use cases of course.
While there are several Debounce Profiles posted here and there on the forum and elsewhere and an issue with a PR to implement it as part of OH itself, a Profile only applies to a Link between a Channel and an Item. It cannot be used with Items alone and therefore its use is limited.
How it works:
Each Item to be debounced needs to have two Items, a “raw” Item and a “proxy” Item. The “raw” Item has the value that is to be debounced. The “proxy” Item is the Item that receives the debounced value and is the Item that represents the sensor in openHAB (e.g. put on the UI, used in a rule, etc.).
All of the “raw” Items must be added to a “Debounce” Group. This Group is what triggers the Debounce rule to run when the states of the “raw” Items change.
Each “raw” Item must also have debounce Item metadata. This tells the rule the name of the corresponding “proxy” Item and some configuration properties that tell the rule how long to debounce the state, an optional list of those states to debounce (e.g. one can only debounce the OFF state but immediately process the ON state), and whether the debounced state should be sent to the proxy Item as an update or a command.
In .items files an example would look something like:
Switch RawSensor (Debounce) { debounce="ProxySensor"[timeout="2m", states="OFF", command="False"] }
Switch ProxySensor
or in the UI
value: ProxySensor
config:
states: OFF
timeout: 2m
command: "True"
In the UI, navigate to the “raw” Item, click on “Add Metadata”, click “Enter Custom Namespace…” (under “Custom namespaces” section) and enter “debounce” as the namespace.
| Property | Purpose | Allowed values |
|---|---|---|
| value | Name of the proxy Item | Valid Item name, should not be the same as the Item with the metadata. |
| states | List of states that are to be debounced. Leaving this option out or setting it to empty string will debounce all Item states. | Comma separated list of Item states or empty string. |
| timeout | How long to debounce the value for. | A duration string using xHxMxS type format where D=days, H=hours, M=minutes, S=seconds, Z=msec. Case doesn’t matter and any one or more units can be used. For example “4h5s”. |
| command | An optional boolean indicating whether the proxy should be commanded or updated. | “true” or “false”, defaults to “false”. |
See Generic Presence Detection for an example using this for debouncing presence detection.
Language: Nashorn JavaScript or JSScripting
Dependencies:
- A Debounce Group created
- All the “raw” Items added to the Debounce Group
- All the “raw” Items have valid “debounce” Item metadata
- On OH 4 the Nashorn add-on needs to be separately installed or change the script type to
application/javascript;version=ECMAScript-2021
Changelog
Version 0.3
- adjusted for breaking change, will no longer work for versions of OH prior to December 15th
Version 0.2
- Made compatible with both Nashorn and JSScripting
NOTE: Sometime after OH 3.2 I will remove support for Nashorn so I can use the helper library.
Version 0.1
- initial release
. I should have re-read the presence detection topic …
