Debounce [4.0.0,)

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 reimplementation of the Debounce rule template that works with OH 3.x using JS Scripting and the openhab-rules-tools library and new OH 4 features. 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 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. 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="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. 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.

Language: JS Scripting

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 toggles on, 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).

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.x+

Change Log

Version 0.1

  • initial release

Resources

https://raw.githubusercontent.com/rkoshak/openhab-rules-tools/main/rule-templates/debounce/debounce2.yaml

3 Likes