[basicprofiles] Add inequality comparisons to State Filter profile

- Fix bug where undefined `mismatchState` passed `UNDEF` instead of ignoring state updates - Support multiline conditions - Support comparing against the input state from handler to filter out unwanted data Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>
openhab · Aug 25, 2024 · 4d382a7 · 4d382a7
1 parent ecdb30e
commit 4d382a7
Show file tree

Hide file tree

Showing 7 changed files with 628 additions and 152 deletions.
diff --git a/bundles/org.openhab.transform.basicprofiles/README.md b/bundles/org.openhab.transform.basicprofiles/README.md
@@ -7,14 +7,14 @@ This bundle provides a list of useful Profiles.
 This Profile can be used to send a Command towards the Item when one event of a specified event list is triggered.
 The given Command value is parsed either to `IncreaseDecreaseType`, `NextPreviousType`, `OnOffType`, `PlayPauseType`, `RewindFastforwardType`, `StopMoveType`, `UpDownType` or a `StringType` is used.
 
-### Configuration
+### Generic Command Profile Configuration
 
 | Configuration Parameter | Type | Description                                                                      |
 |-------------------------|------|----------------------------------------------------------------------------------|
 | `events`                | text | Comma separated list of events to which the profile should listen. **mandatory** |
 | `command`               | text | Command which should be sent if the event is triggered. **mandatory**            |
 
-### Full Example
+### Generic Command Profile Example
 
 ```java
 Switch lightsStatus {
@@ -27,13 +27,13 @@ Switch lightsStatus {
 
 The Generic Toggle Switch Profile is a specialization of the Generic Command Profile and toggles the State of a Switch Item whenever one of the specified events is triggered.
 
-### Configuration
+### Generic Toggle Switch Profile Configuration
 
 | Configuration Parameter | Type | Description                                                                      |
 |-------------------------|------|----------------------------------------------------------------------------------|
 | `events`                | text | Comma separated list of events to which the profile should listen. **mandatory** |
 
-### Full Example
+### Generic Toggle Switch Profile Example
 
 ```java
 Switch lightsStatus {
@@ -47,13 +47,13 @@ Switch lightsStatus {
 This Profile counts and skips a user-defined number of State changes before it sends an update to the Item.
 It can be used to debounce Item States.
 
-### Configuration
+### Debounce (Counting) Profile Configuration
 
 | Configuration Parameter | Type    | Description                                   |
 |-------------------------|---------|-----------------------------------------------|
 | `numberOfChanges`       | integer | Number of changes before updating Item State. |
 
-### Full Example
+### Debounce (Counting) Profile Example
 
 ```java
 Switch debouncedSwitch { channel="xxx" [profile="basic-profiles:debounce-counting", numberOfChanges=2] }
@@ -66,15 +66,15 @@ In `FIRST` mode this profile discards values for the configured time after a val
 
 It can be used to debounce Item States/Commands or prevent excessive load on networks.
 
-### Configuration
+### Debounce (Time) Profile Configuration
 
 | Configuration Parameter | Type    | Description                                   |
 |-------------------------|---------|-----------------------------------------------|
 | `toItemDelay`           | integer | Timespan in ms before a received value is send to the item. |
 | `toHandlerDelay`        | integer | Timespan in ms before a received command is passed to the handler. |
 | `mode`                  | text    | `FIRST` (sends the first value received and discards later values), `LAST` (sends the last value received, discarding earlier values). |
 
-### Full Example
+### Debounce (Time) Profile Example
 
 ```java
 Number:Temperature debouncedSetpoint { channel="xxx" [profile="basic-profiles:debounce-time", toHandlerDelay=1000] }
@@ -87,7 +87,7 @@ It requires no specific configuration.
 
 The values of `QuantityType`, `PercentType` and `DecimalTypes` are negated (multiplied by `-1`).
 Otherwise the following mapping is used:
- 
+
 `IncreaseDecreaseType`: `INCREASE` <-> `DECREASE`
 `NextPreviousType`: `NEXT` <-> `PREVIOUS`
 `OnOffType`: `ON` <-> `OFF`
@@ -97,7 +97,7 @@ Otherwise the following mapping is used:
 `StopMoveType`: `MOVE` <-> `STOP`
 `UpDownType`: `UP` <-> `DOWN`
 
-### Full Example
+### Invert / Negate Profile Example
 
 ```java
 Switch invertedSwitch { channel="xxx" [profile="basic-profiles:invert"] }
@@ -109,14 +109,14 @@ The Round Profile scales the State to a specific number of decimal places based
 Optionally the [Rounding mode](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/math/RoundingMode.html) can be set.
 Source Channels should accept Item Type `Number`.
 
-### Configuration
+### Round Profile Configuration
 
 | Configuration Parameter | Type    | Description                                                                                                     |
 |-------------------------|---------|-----------------------------------------------------------------------------------------------------------------|
 | `scale`                 | integer | Scale to indicate the resulting number of decimal places (min: -16, max: 16, STEP: 1) **mandatory**.            |
 | `mode`                  | text    | Rounding mode to be used (e.g. "UP", "DOWN", "CEILING", "FLOOR", "HALF_UP" or "HALF_DOWN" (default: "HALF_UP"). |
 
-### Full Example
+### Round Profile Example
 
 ```java
 Number roundedNumber { channel="xxx" [profile="basic-profiles:round", scale=0] }
@@ -133,13 +133,13 @@ Source Channels should accept Item Type `Dimmer` or `Number`.
 This profile is a shortcut for the System Hysteresis Profile.
 :::
 
-### Configuration
+### Threshold Profile Configuration
 
 | Configuration Parameter | Type    | Description                                                                                         |
 |-------------------------|---------|-----------------------------------------------------------------------------------------------------|
 | `threshold`             | integer | Triggers `ON` if value is below the given threshold, otherwise OFF (default: 10, min: 0, max: 100). |
 
-### Full Example
+### Threshold Profile Example
 
 ```java
 Switch thresholdItem { channel="xxx" [profile="basic-profiles:threshold", threshold=15] }
@@ -152,7 +152,7 @@ The value of the percent type can be different between a specific time of the da
 A possible use-case is switching lights (using a presence detector) with different intensities at day and at night.
 Be aware: a range beyond midnight (e.g. start="23:00", end="01:00") is not yet supported.
 
-### Configuration
+### Time Range Profile Configuration
 
 | Configuration Parameter | Type    | Description                                                                                                                                       |
 |-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -169,7 +169,7 @@ Possible values for parameter `restoreValue`:
 - `PREVIOUS` - Return to previous value
 - `0` - `100` - Set a user-defined percent value
 
-### Full Example
+### Time Range Profile Example
 
 ```java
 Switch motionSensorFirstFloor {
@@ -180,31 +180,66 @@ Switch motionSensorFirstFloor {
 
 ## State Filter Profile
 
-This filter passes on state updates from a (binding) handler to the item if and only if all listed item state conditions
-are met (conditions are ANDed together).
-Option to instead pass different state update in case the conditions are not met.
-State values may be quoted to treat as `StringType`.
+This filter passes on state updates from the (binding) handler to the item if and only if all listed conditions are met (conditions are ANDed together).
+In case the conditions are not met, a fixed predefined state can be passed to the item instead of ignoring the update.
+
+Use cases:
+
+- Ignore values from the binding unless some other item(s) have a specific state.
+- Filter out invalid values from the binding.
+
+### State Filter Configuration
+
+| Configuration Parameter | Type | Description                                                                                                                                                              |
+| ----------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `conditions`            | text | A list of conditions to check before posting an update from the binding to the item. When all the conditions are met, the update from the binding is passed to the item. |
+| `mismatchState`         | text | What to pass to the item when `conditions` aren't met. Use single quotes to treat as `StringType`. When undefined (the default), updates from the binding are ignored.   |
+| `separator`             | text | Optional separator string to separate multiple expressions. Defaults to `,`.                                                                                             |
+
+#### State Filter Conditions
+
+The conditions are defined in the format `[ITEM_NAME] OPERATOR VALUE`, e.g. `MyItem EQ OFF`.
+Multiple conditions can be entered on separate lines in the UI, or in a single line separated with the `separator` character/string.
+
+When `ITEM_NAME` is omitted, e.g. `> 10, < 100`, the comparison is applied against the input data from the binding.
+This can be used to filter out unwanted data, e.g. to ensure that incoming data are within a reasonable range.
 
-Use case: Ignore values from a binding unless some other item(s) have a specific state.
+Some tips:
 
-### Configuration
+- When dealing with QuantityType data, the unit must be included in the comparison value, e.g.: `PowerItem > 1 kW`.
+- Use single quotes around the `VALUE` to perform a string comparison, e.g. `'UNDEF'` is not equal to `UnDefType.UNDEF`.
+- When comparing against StringType data (e.g. a `StringItem`), the value does not need to be single-quoted.
 
-| Configuration Parameter | Type | Description                                                                                                                                                                                       |
-|-------------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `conditions`            | text | Comma separated list of expressions on the format `ITEM_NAME OPERATOR ITEM_STATE`, ie `MyItem EQ OFF`. Use quotes around `ITEM_STATE` to treat value as string ie `'OFF'` and not `OnOffType.OFF` |
-| `mismatchState`         | text | Optional state to pass instead if conditions are NOT met. Use single quotes to treat as `StringType`. Defaults to `UNDEF`                                                                         |
-| `separator`             | text | Optional separator string to separate expressions when using multiple. Defaults to `,`                                                                                                            |
+##### State Filter Operators
 
-Possible values for token `OPERATOR` in `conditions`:
 
-- `EQ` - Equals
-- `NEQ` - Not equals
+| Name  | Symbol |                           |
+| :---: | :----: | ------------------------- |
+| `EQ`  |  `==`  | Equals                    |
+| `NEQ` |  `!=`  | Not equals                |
+| `GT`  |  `>`   | Greater than              |
+| `GTE` |  `>=`  | Greater than or equals to |
+| `LT`  |  `<`   | Less than                 |
+| `LTE` |  `<=`  | Less than or equals to    |
 
+Notes:
 
-### Full Example
+- The operator names must be surrounded by spaces, i.e.: `Item EQ 10`
+- The operator symbols do not need to be surrounded by spaces, e.g.: `Item==10` and `Item == 10` are both fine.
+- Only symbolic operators can be used when comparing against the incoming state, e.g. `> 10`. Using operator names isn't supported, i.e. this is not supported: ~~`GT 10`~~.
 
-```Java
-Number:Temperature airconTemperature{
-        channel="mybinding:mything:mychannel"[profile="basic-profiles:state-filter",conditions="airconPower_item EQ ON",mismatchState="UNDEF"]
+### State Filter Example
+
+```java
+Number:Temperature airconTemperature {
+        channel="mybinding:mything:mychannel" [ profile="basic-profiles:state-filter", conditions="airconPower_item EQ ON", mismatchState="UNDEF" ]
+}
+```
+
+With multiple conditions, make sure incoming data is between 0 kW and 20 kW, discarding values outside this range:
+
+```java
+Number:Power PowerUsage {
+        channel="mybinding:mything:mychannel" [ profile="basic-profiles:state-filter", conditions=">= 0 kW", "< 20 kW" ]
 }
 ```
diff --git a/...in/java/org/openhab/transform/basicprofiles/internal/config/StateFilterProfileConfig.java b/...in/java/org/openhab/transform/basicprofiles/internal/config/StateFilterProfileConfig.java
@@ -12,8 +12,10 @@
  */
 package org.openhab.transform.basicprofiles.internal.config;
 
+import java.util.List;
+
 import org.eclipse.jdt.annotation.NonNullByDefault;
-import org.openhab.core.types.UnDefType;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.transform.basicprofiles.internal.profiles.StateFilterProfile;
 
 /**
@@ -24,9 +26,9 @@
 @NonNullByDefault
 public class StateFilterProfileConfig {
 
-    public String conditions = "";
+    public List<String> conditions = List.of();
 
-    public String mismatchState = UnDefType.UNDEF.toString();
+    public @Nullable String mismatchState;
 
     public String separator = ",";
 }
diff --git a/.../main/java/org/openhab/transform/basicprofiles/internal/factory/BasicProfilesFactory.java b/.../main/java/org/openhab/transform/basicprofiles/internal/factory/BasicProfilesFactory.java
@@ -106,7 +106,7 @@ public class BasicProfilesFactory implements ProfileFactory, ProfileTypeProvider
             .withSupportedChannelTypeUIDs(DefaultSystemChannelTypeProvider.SYSTEM_CHANNEL_TYPE_UID_MOTION) //
             .build();
     private static final ProfileType PROFILE_STATE_FILTER = ProfileTypeBuilder
-            .newState(STATE_FILTER_UID, "Filter handler state updates based on any item state").build();
+            .newState(STATE_FILTER_UID, "State Filter").build();
 
     private static final Set<ProfileTypeUID> SUPPORTED_PROFILE_TYPE_UIDS = Set.of(GENERIC_COMMAND_UID,
             GENERIC_TOGGLE_SWITCH_UID, DEBOUNCE_COUNTING_UID, DEBOUNCE_TIME_UID, INVERT_UID, ROUND_UID, THRESHOLD_UID,