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.
This is a complete reimplementation of the Debounce rule template that works with OH 4.x using the JS Scripting add-on and the openhab-rules-tools library. It includes new OH 4 features so it is not backwards compatible. It also includes a few minor changes in behavior.
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 triggers the Debounce rule to run when the states of the raw Items change. The actual Group Item is chosen by the user when instantiating the rule. Do not include the proxy Items in this Group.
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 debounce only 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. The actual name of the namespace is chosen by the user when instantiating the rule. By default the namespace is debounce.
In .items files an example would look something like:
Switch RawSensor (Debounce) { debounce="ProxySensor"[timeout="PT2M", states="OFF", command="False"] }
Switch ProxySensor
or in the UI
value: ProxySensor
config:
states: OFF
timeout: PT2M
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 (where “debounce” is what ever you chose as the namespace property.
| 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. | Anything supported by time.toZDT() in the openhab-js libray (see JavaScript Scripting - Automation | openHAB) |
| 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.
When this rule is triggered by any event that is not an Item event (e.g. manually) it will validate your Item configs (i.e. make sure all Item with “debounce” metadata are members of the “Debounce” group and make sure that metadata is usable). Watch the logs for potential problems.
When the “Initial Proxies” option is toggled on, when triggered by a non-Item event, in addition to validating the Item’s debounce configs, the rule will initialize the proxy Items to the current state of the raw Item (if they are different). This can be used with a “system run level” trigger or manually triggered to synchronize the proxy and raw Items in cases where the event was missed (e.g. restoreOnStartup).
Language: JS Scripting
Dependencies:
- A “Debounce” Group created
- All the raw Items added to the Debounce Group
- All the raw Items have valid “debounce” Item metadata
- OH 4.0+
- openhab-js 4.5+
- openhab_rules_tools 2.0.3+
TODOs:
- determine if it’s feasible to expand this template to also be a threshold filter or if that’s best implemented as a separate template (this would only forward an update if it is different enough from the current state, smoothing out the events from chatty sensors)
Change Log
Version 0.4
- adjustments to changes in OHRT
- run on GroupItemStateChangedEvent
Version 0.3
- fixed bug caused by a change to the way the openhab-js API interacts with Item metadata
- fixed bug where any Group named other than “Debounce” would not be used in the script action
Version 0.2
- moved to new openhab-js metadata calls and access to items
- added check that thows an exception if the openhab-js or openhab_rules_tools versions installed are too old to work with the template
Version 0.1
- initial release
Sponsorship
If you want to send a tip my way or sponsor my work you can through Sponsor @rkoshak on GitHub or PayPal. It won’t change what I contribute to OH but it might keep me in coffee or let me buy hardware to test out new things.
I’ll have a new version posted shortly. Watch for the update to the original post.