[pwm] Fix handling of "maxDutyCycle" parameter value (#12197)

* [pwm] Fix handling of "maxDutyCycle" parameter value

Signed-off-by: Andriy Yemets <cyborg.andy@gmail.com>

* [pwm] Clarify behavior of the parameters

Signed-off-by: Andriy Yemets <cyborg.andy@gmail.com>

* [pwm] Update README.md (#12196)

Fixed description for maxDutycycle parameter
Added two new parameters: equateMinToZero and equateMaxToHundred

Signed-off-by: Andriy Yemets <cyborg.andy@gmail.com>

* Update bundles/org.openhab.automation.pwm/src/main/java/org/openhab/automation/pwm/internal/handler/PWMTriggerHandler.java

Signed-off-by: Fabian Wolter <github@fabian-wolter.de>

* Update bundles/org.openhab.automation.pwm/src/main/java/org/openhab/automation/pwm/internal/handler/PWMTriggerHandler.java

Signed-off-by: Fabian Wolter <github@fabian-wolter.de>

Signed-off-by: Andriy Yemets <cyborg.andy@gmail.com>
Signed-off-by: Fabian Wolter <github@fabian-wolter.de>
Co-authored-by: Fabian Wolter <github@fabian-wolter.de>

bundles/org.openhab.automation.pwm/README.md

@@ -26,13 +26,15 @@ Select the Item you like to control in the "Item Action" and leave the command e
 
 ### Trigger
 
-| Name            | Type    | Description                                                                                  | Required |
+| Name                 | Type    | Description                                                                                  | Required |
-|-----------------|---------|----------------------------------------------------------------------------------------------|----------|
+|----------------------|---------|----------------------------------------------------------------------------------------------|----------|
-| `dutycycleItem` | Item    | The Item (PercentType) to read the duty cycle from                                           | Yes      |
+| `dutycycleItem`      | Item    | The Item (PercentType) to read the duty cycle from                                           | Yes      |
-| `interval`      | Decimal | The constant interval in which the output is switch ON and OFF again in sec.                 | Yes      |
+| `interval`           | Decimal | The constant interval in which the output is switch ON and OFF again in sec.                 | Yes      |
-| `minDutyCycle`  | Decimal | Any duty cycle below this value will be increased to this value                              | No       |
+| `minDutyCycle`       | Decimal | Any duty cycle below this value will be increased to this value                              | No       |
-| `maxDutycycle`  | Decimal | Any duty cycle above this value will be decreased to this value                              | No       |
+| `equateMinToZero`    | Boolean | True if the duty cycle below `minDutycycle` should be set to 0 (defaults to false)           | No       |
-| `deadManSwitch` | Decimal | The output will be switched off, when the duty cycle is not updated within this time (in ms) | No       |
+| `maxDutycycle`       | Decimal | Any duty cycle above this value will be increased to 100                                     | No       |
+| `equateMaxToHundred` | Boolean | True if the duty cycle above `maxDutyCycle` should be set to 100 (defaults to true)          | No       |
+| `deadManSwitch`      | Decimal | The output will be switched off, when the duty cycle is not updated within this time (in ms) | No       |
 
 The duty cycle can be limited via the parameters `minDutycycle` and `maxDutyCycle`.
 This is helpful if you need to maintain a minimum time between the switching of the output.

bundles/org.openhab.automation.pwm/src/main/java/org/openhab/automation/pwm/internal/PWMConstants.java

@@ -26,7 +26,9 @@ public class PWMConstants {
     public static final String CONFIG_DUTY_CYCLE_ITEM = "dutycycleItem";
     public static final String CONFIG_PERIOD = "interval";
     public static final String CONFIG_MIN_DUTYCYCLE = "minDutycycle";
+    public static final String CONFIG_EQUATE_MIN_TO_ZERO = "equateMinToZero";
     public static final String CONFIG_MAX_DUTYCYCLE = "maxDutycycle";
+    public static final String CONFIG_EQUATE_MAX_TO_HUNDRED = "equateMaxToHundred";
     public static final String CONFIG_COMMAND_ITEM = "command";
     public static final String CONFIG_DEAD_MAN_SWITCH = "deadManSwitch";
     public static final String CONFIG_OUTPUT_ITEM = "outputItem";

bundles/org.openhab.automation.pwm/src/main/java/org/openhab/automation/pwm/internal/handler/PWMTriggerHandler.java

@@ -62,6 +62,8 @@ public class PWMTriggerHandler extends BaseTriggerModuleHandler implements Event
     private final EventFilter eventFilter;
     private final Optional<Double> minDutyCycle;
     private final Optional<Double> maxDutyCycle;
+    private final boolean isEquateMinToZero;
+    private final boolean isEquateMaxToHundred;
     private final Optional<Double> deadManSwitchTimeoutMs;
     private final Item dutyCycleItem;
     private @Nullable ServiceRegistration<?> eventSubscriberRegistration;
@@ -78,7 +80,9 @@ public class PWMTriggerHandler extends BaseTriggerModuleHandler implements Event
                 "DutyCycle item is not set");
 
         minDutyCycle = getOptionalDoubleFromConfig(config, CONFIG_MIN_DUTYCYCLE);
+        isEquateMinToZero = getBooleanFromConfig(config, CONFIG_EQUATE_MIN_TO_ZERO);
         maxDutyCycle = getOptionalDoubleFromConfig(config, CONFIG_MAX_DUTYCYCLE);
+        isEquateMaxToHundred = getBooleanFromConfig(config, CONFIG_EQUATE_MAX_TO_HUNDRED);
         deadManSwitchTimeoutMs = getOptionalDoubleFromConfig(config, CONFIG_DEAD_MAN_SWITCH);
 
         try {
@@ -114,6 +118,10 @@ public class PWMTriggerHandler extends BaseTriggerModuleHandler implements Event
         return Optional.empty();
     }
 
+    private boolean getBooleanFromConfig(Configuration config, String key) {
+        return ((Boolean) config.get(key)).booleanValue();
+    }
+
     @Override
     public void receive(Event event) {
         if (!(event instanceof ItemStateEvent)) {
@@ -128,24 +136,28 @@ public class PWMTriggerHandler extends BaseTriggerModuleHandler implements Event
 
                 restartDeadManSwitchTimer();
 
+                // set duty cycle to 0% if it is 0% or it is smaller than min duty cycle and equateMinToZero is true
                 // set duty cycle to min duty cycle if it is smaller than min duty cycle
-                // set duty cycle to 0% if it is 0%, regardless of the min duty cycle
                 final double newDutyCycleFinal1 = newDutycycle;
                 newDutycycle = minDutyCycle.map(minDutycycle -> {
-                    if (Math.round(newDutyCycleFinal1) <= 0) {
+                    long dutycycleRounded1 = Math.round(newDutyCycleFinal1);
+                    if (dutycycleRounded1 <= 0 || (dutycycleRounded1 <= minDutycycle && isEquateMinToZero)) {
                         return 0d;
                     } else {
                         return Math.max(minDutycycle, newDutyCycleFinal1);
                     }
                 }).orElse(newDutycycle);
 
-                // set duty cycle to 100% if the current duty cycle is larger than the max duty cycle
+                // set duty cycle to 100% if it is 100% or it is larger then max duty cycle and equateMaxToHundred is
+                // true
+                // set duty cycle to max duty cycle if it is larger then max duty cycle
                 final double newDutyCycleFinal2 = newDutycycle;
                 newDutycycle = maxDutyCycle.map(maxDutycycle -> {
-                    if (Math.round(newDutyCycleFinal2) >= maxDutycycle) {
+                    long dutycycleRounded2 = Math.round(newDutyCycleFinal2);
+                    if (dutycycleRounded2 >= 100 || (dutycycleRounded2 >= maxDutycycle && isEquateMaxToHundred)) {
                         return 100d;
                     } else {
-                        return newDutyCycleFinal2;
+                        return Math.min(maxDutycycle, newDutyCycleFinal2);
                     }
                 }).orElse(newDutycycle);
 

bundles/org.openhab.automation.pwm/src/main/java/org/openhab/automation/pwm/internal/type/PWMTriggerType.java

@@ -62,7 +62,14 @@ public class PWMTriggerType extends TriggerType {
                 .withDefault("0") //
                 .withLabel("Min Dutycycle") //
                 .withUnit("%") //
-                .withDescription("The dutycycle will be min this value").build());
+                .withDescription("The dutycycle below this value will be increased to this value").build());
+        configDescriptions.add(ConfigDescriptionParameterBuilder.create(CONFIG_EQUATE_MIN_TO_ZERO, Type.BOOLEAN) //
+                .withRequired(false) //
+                .withMultiple(false) //
+                .withDefault("false") //
+                .withLabel("Equate Min Dutycycle to 0") //
+                .withDescription("True if the dutycycle below Min Dutycycle should be set to 0 (defaults to false)")
+                .build());
         configDescriptions.add(ConfigDescriptionParameterBuilder.create(CONFIG_MAX_DUTYCYCLE, Type.DECIMAL) //
                 .withRequired(false) //
                 .withMultiple(false) //
@@ -71,7 +78,14 @@ public class PWMTriggerType extends TriggerType {
                 .withDefault("100") //
                 .withUnit("%") //
                 .withLabel("Max Dutycycle") //
-                .withDescription("The dutycycle will be max this value").build());
+                .withDescription("The dutycycle above this value will be increased to 100").build());
+        configDescriptions.add(ConfigDescriptionParameterBuilder.create(CONFIG_EQUATE_MAX_TO_HUNDRED, Type.BOOLEAN) //
+                .withRequired(false) //
+                .withMultiple(false) //
+                .withDefault("true") //
+                .withLabel("Equate Max Dutycycle to 100") //
+                .withDescription("True if the dutycycle above Max Dutycycle should be set to 100 (defaults to true)")
+                .build());
         configDescriptions.add(ConfigDescriptionParameterBuilder.create(CONFIG_DEAD_MAN_SWITCH, Type.DECIMAL) //
                 .withRequired(false) //
                 .withMultiple(false) //