[boschshc] Add support for Door/Window Contact II Plus (openhab#18201)

Signed-off-by: David Pace <[email protected]>

Author: david-pace

bundles/org.openhab.binding.boschshc/DEVELOPERS.md

@@ -1,5 +1,22 @@
 # For Developers
 
+## Typical Workflow for Supporting new Devices / Services / Channels
+
+1. Define new thing types and channel types in `src/main/resources/OH-INF/thing/thing-types.xml`
+1. If `thing-types.xml` was modified, re-generate the i18n properties file by running Maven with the goal `i18n:generate-default-translations`
+1. Define constants for new thing/channel types in `BoschSHCBindingConstants`
+1. Create new packages for services that are not implemented yet and create service classes
+1. Create new DTO packages for new services and implement data transfer model classes / enums according to the JSON structure of the service requests
+1. Create a new handler or extend existing handlers to update channel states according to what was received, and/or to send new states to the Bosch Smart Home Controller in case of writable channels
+1. Register new handlers in `BoschSHCHandlerFactory`, if applicable
+1. Register new thing types in `ThingDiscoveryService`, if applicable
+1. Implement unit tests for new handlers / services / model classes
+
+1. If channels were added to existing devices/things, add a migration instruction set to `src/main/resources/update/binding.xml`
+1. Add documentation for new things/channels to `README.md`
+1. Apply automatic code formatting by running a Maven build with goal `spotless:apply`
+1. Build the binding by running a Maven build with goals `clean install`
+
 ## Build
 
 To only build the Bosch Smart Home binding code execute

bundles/org.openhab.binding.boschshc/README.md

@@ -121,7 +121,7 @@ Detects open windows and doors.
 
 Detects open windows and doors and features an additional button.
 
-**Thing Type ID**: `window-contact`
+**Thing Type ID**: `window-contact-2`
 
 | Channel Type ID | Item Type | Writable | Description                  |
 | ----------------| --------- | :------: | ---------------------------- |
@@ -131,6 +131,23 @@ Detects open windows and doors and features an additional button.
 | bypass          | Switch    | ☐  | Indicates whether the device is currently bypassed. Possible values are `ON`,`OFF` and `UNDEF` if the bypass state cannot be determined. |
 | signal-strength | Number    | ☐  | Communication quality between the device and the Smart Home Controller. Possible values range between 0 (unknown) and 4 (best signal strength). |
 
+### Door/Window Contact II Plus
+
+Detects open windows and doors, provides a configurable button and a vibration sensor.
+
+**Thing Type ID**: `window-contact-2-plus`
+
+| Channel Type ID              | Item Type | Writable | Description                                                                                                                                                                                                                 |
+| -----------------------------| --------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| contact                      | Contact   | ☐  | Contact state of the device.                                                                                                                                                                                                |
+| battery-level                | Number    | ☐  | Current battery level percentage as integer number. Bosch-specific battery levels are mapped to numbers as follows: `OK`: 100, `LOW_BATTERY`: 10, `CRITICAL_LOW`: 1, `CRITICALLY_LOW_BATTERY`: 1, `NOT_AVAILABLE`: `UNDEF`. |
+| low-battery                  | Switch    | ☐  | Indicates whether the battery is low (`ON`) or OK (`OFF`).                                                                                                                                                                  |
+| bypass                       | Switch    | ☐  | Indicates whether the device is currently bypassed. Possible values are `ON`,`OFF` and `UNDEF` if the bypass state cannot be determined.                                                                                    |
+| signal-strength              | Number    | ☐  | Communication quality between the device and the Smart Home Controller. Possible values range between 0 (unknown) and 4 (best signal strength).                                                                             |
+| vibration-sensor-enabled     | Switch    | ☑  | Channel to enable or disable the vibration sensor.                                                                                                                                                                          |
+| vibration-sensor-sensitivity | String    | ☑  | The sensitivity of the vibration sensor. Possible values are `VERY_HIGH`, `HIGH`, `MEDIUM`, `LOW` and `VERY_LOW`.                                                                                                           |
+| vibration-sensor-state       | String    | ☐  | Indicates whether vibrations were detected by the sensor. Possible values are `NO_VIBRATION`, `VIBRATION_DETECTED` and `UNKNOWN`.                                                                                           |
+
 ### Light Control II
 
 This thing type is used if Light/Shutter Control II devices are configured as light controls.

bundles/org.openhab.binding.boschshc/src/main/java/org/openhab/binding/boschshc/internal/console/BoschShcCommandExtension.java

@@ -85,8 +85,8 @@ List<String> getAllBoschShcServices() {
                 "childlock", "childprotection", "communicationquality", "hsbcoloractuator", "humiditylevel",
                 "illuminance", "impulseswitch", "intrusion", "keypad", "latestmotion", "multilevelswitch", "powermeter",
                 "powerswitch", "privacymode", "roomclimatecontrol", "shuttercontact", "shuttercontrol", "silentmode",
-                "smokedetectorcheck", "temperaturelevel", "userstate", "valvetappet", "waterleakagesensor",
-                "waterleakagesensorcheck", "waterleakagesensortilt");
+                "smokedetectorcheck", "temperaturelevel", "userstate", "valvetappet", "vibrationsensor",
+                "waterleakagesensor", "waterleakagesensorcheck", "waterleakagesensortilt");
     }
 
     @Override

bundles/org.openhab.binding.boschshc/src/main/java/org/openhab/binding/boschshc/internal/devices/BoschSHCBindingConstants.java

@@ -41,6 +41,8 @@ private BoschSHCBindingConstants() {
     public static final ThingTypeUID THING_TYPE_TWINGUARD = new ThingTypeUID(BINDING_ID, "twinguard");
     public static final ThingTypeUID THING_TYPE_WINDOW_CONTACT = new ThingTypeUID(BINDING_ID, "window-contact");
     public static final ThingTypeUID THING_TYPE_WINDOW_CONTACT_2 = new ThingTypeUID(BINDING_ID, "window-contact-2");
+    public static final ThingTypeUID THING_TYPE_WINDOW_CONTACT_2_PLUS = new ThingTypeUID(BINDING_ID,
+            "window-contact-2-plus");
     public static final ThingTypeUID THING_TYPE_MOTION_DETECTOR = new ThingTypeUID(BINDING_ID, "motion-detector");
     public static final ThingTypeUID THING_TYPE_SHUTTER_CONTROL = new ThingTypeUID(BINDING_ID, "shutter-control");
     public static final ThingTypeUID THING_TYPE_SHUTTER_CONTROL_2 = new ThingTypeUID(BINDING_ID, "shutter-control-2");
@@ -117,6 +119,9 @@ private BoschSHCBindingConstants() {
     public static final String CHANNEL_IMPULSE_LENGTH = "impulse-length";
     public static final String CHANNEL_INSTANT_OF_LAST_IMPULSE = "instant-of-last-impulse";
     public static final String CHANNEL_ALARM = "alarm";
+    public static final String CHANNEL_VIBRATION_SENSOR_ENABLED = "vibration-sensor-enabled";
+    public static final String CHANNEL_VIBRATION_SENSOR_SENSITIVITY = "vibration-sensor-sensitivity";
+    public static final String CHANNEL_VIBRATION_SENSOR_STATE = "vibration-sensor-state";
     // numbered channels
     // the rationale for introducing numbered channels was discussed in
     // https://github.com/openhab/openhab-addons/pull/16400

bundles/org.openhab.binding.boschshc/src/main/java/org/openhab/binding/boschshc/internal/devices/BoschSHCHandlerFactory.java

@@ -12,31 +12,7 @@
  */
 package org.openhab.binding.boschshc.internal.devices;
 
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_CAMERA_360;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_CAMERA_EYES;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_CLIMATE_CONTROL;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_DIMMER;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_INTRUSION_DETECTION_SYSTEM;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_INWALL_SWITCH;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_LIGHT_CONTROL_2;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_MOTION_DETECTOR;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_RELAY;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SHC;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SHUTTER_CONTROL;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SHUTTER_CONTROL_2;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SMART_BULB;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SMART_PLUG_COMPACT;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SMOKE_DETECTOR;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_SMOKE_DETECTOR_2;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_THERMOSTAT;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_TWINGUARD;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_UNIVERSAL_SWITCH;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_UNIVERSAL_SWITCH_2;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_USER_DEFINED_STATE;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_WALL_THERMOSTAT;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_WATER_DETECTOR;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_WINDOW_CONTACT;
-import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.THING_TYPE_WINDOW_CONTACT_2;
+import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.*;
 
 import java.util.Collection;
 import java.util.List;
@@ -67,6 +43,7 @@
 import org.openhab.binding.boschshc.internal.devices.wallthermostat.WallThermostatHandler;
 import org.openhab.binding.boschshc.internal.devices.waterleakage.WaterLeakageSensorHandler;
 import org.openhab.binding.boschshc.internal.devices.windowcontact.WindowContact2Handler;
+import org.openhab.binding.boschshc.internal.devices.windowcontact.WindowContact2PlusHandler;
 import org.openhab.binding.boschshc.internal.devices.windowcontact.WindowContactHandler;
 import org.openhab.core.thing.Bridge;
 import org.openhab.core.thing.Thing;
@@ -107,6 +84,7 @@ public ThingTypeHandlerMapping(ThingTypeUID thingTypeUID, Function<Thing, BaseTh
             new ThingTypeHandlerMapping(THING_TYPE_TWINGUARD, TwinguardHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_WINDOW_CONTACT, WindowContactHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_WINDOW_CONTACT_2, WindowContact2Handler::new),
+            new ThingTypeHandlerMapping(THING_TYPE_WINDOW_CONTACT_2_PLUS, WindowContact2PlusHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_MOTION_DETECTOR, MotionDetectorHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_SHUTTER_CONTROL, ShutterControlHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_SHUTTER_CONTROL_2, ShutterControl2Handler::new),
@@ -120,8 +98,8 @@ public ThingTypeHandlerMapping(ThingTypeUID thingTypeUID, Function<Thing, BaseTh
             new ThingTypeHandlerMapping(THING_TYPE_SMART_BULB, SmartBulbHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_SMOKE_DETECTOR, SmokeDetectorHandler::new),
             new ThingTypeHandlerMapping(THING_TYPE_USER_DEFINED_STATE, UserStateHandler::new),
-            new ThingTypeHandlerMapping(THING_TYPE_UNIVERSAL_SWITCH, thing -> new UniversalSwitchHandler(thing)),
-            new ThingTypeHandlerMapping(THING_TYPE_UNIVERSAL_SWITCH_2, thing -> new UniversalSwitch2Handler(thing)),
+            new ThingTypeHandlerMapping(THING_TYPE_UNIVERSAL_SWITCH, UniversalSwitchHandler::new),
+            new ThingTypeHandlerMapping(THING_TYPE_UNIVERSAL_SWITCH_2, UniversalSwitch2Handler::new),
             new ThingTypeHandlerMapping(THING_TYPE_SMOKE_DETECTOR_2, SmokeDetector2Handler::new),
             new ThingTypeHandlerMapping(THING_TYPE_LIGHT_CONTROL_2, LightControl2Handler::new),
             new ThingTypeHandlerMapping(THING_TYPE_DIMMER, DimmerHandler::new),

bundles/org.openhab.binding.boschshc/src/main/java/org/openhab/binding/boschshc/internal/devices/windowcontact/WindowContact2PlusHandler.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.boschshc.internal.devices.windowcontact;
+
+import static org.openhab.binding.boschshc.internal.devices.BoschSHCBindingConstants.*;
+
+import java.util.List;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.boschshc.internal.exceptions.BoschSHCException;
+import org.openhab.binding.boschshc.internal.services.vibrationsensor.VibrationSensorService;
+import org.openhab.binding.boschshc.internal.services.vibrationsensor.dto.VibrationSensorSensitivity;
+import org.openhab.binding.boschshc.internal.services.vibrationsensor.dto.VibrationSensorServiceState;
+import org.openhab.core.library.types.OnOffType;
+import org.openhab.core.library.types.StringType;
+import org.openhab.core.thing.ChannelUID;
+import org.openhab.core.thing.Thing;
+import org.openhab.core.types.Command;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Handler for Door/Window Contact II Plus.
+ * 
+ * @author David Pace - Initial contribution
+ *
+ */
+@NonNullByDefault
+public class WindowContact2PlusHandler extends WindowContact2Handler {
+
+    private final Logger logger = LoggerFactory.getLogger(WindowContact2PlusHandler.class);
+
+    private final VibrationSensorService vibrationSensorService;
+
+    @Nullable
+    private VibrationSensorServiceState currentVibrationSensorState;
+
+    public WindowContact2PlusHandler(Thing thing) {
+        super(thing);
+        this.vibrationSensorService = new VibrationSensorService();
+    }
+
+    @Override
+    protected void initializeServices() throws BoschSHCException {
+        super.initializeServices();
+
+        this.registerService(vibrationSensorService, this::updateChannels, List.of(CHANNEL_VIBRATION_SENSOR_ENABLED,
+                CHANNEL_VIBRATION_SENSOR_STATE, CHANNEL_VIBRATION_SENSOR_SENSITIVITY), true);
+    }
+
+    private void updateChannels(VibrationSensorServiceState state) {
+        this.currentVibrationSensorState = state;
+        updateState(CHANNEL_VIBRATION_SENSOR_ENABLED, OnOffType.from(state.enabled));
+        updateState(CHANNEL_VIBRATION_SENSOR_STATE, new StringType(state.value.toString()));
+        updateState(CHANNEL_VIBRATION_SENSOR_SENSITIVITY, new StringType(state.sensitivity.toString()));
+    }
+
+    @Override
+    public void handleCommand(ChannelUID channelUID, Command command) {
+        super.handleCommand(channelUID, command);
+
+        switch (channelUID.getId()) {
+            case CHANNEL_VIBRATION_SENSOR_ENABLED:
+                if (command instanceof OnOffType onOffCommand) {
+                    updateVibrationSensorEnabled(onOffCommand);
+                }
+                break;
+            case CHANNEL_VIBRATION_SENSOR_SENSITIVITY:
+                if (command instanceof StringType stringCommand) {
+                    updateVibrationSensorSensitivity(stringCommand.toFullString());
+                }
+                break;
+        }
+    }
+
+    private void updateVibrationSensorSensitivity(String sensitivityValue) {
+        VibrationSensorSensitivity newSensitivity = VibrationSensorSensitivity.from(sensitivityValue);
+
+        if (newSensitivity == null) {
+            logger.warn("Unsupported vibration sensor sensitivity value: {}", sensitivityValue);
+            return;
+        }
+
+        VibrationSensorServiceState copy = copyCurrentState();
+        if (copy == null) {
+            return;
+        }
+
+        copy.sensitivity = newSensitivity;
+
+        this.currentVibrationSensorState = copy;
+        updateServiceState(vibrationSensorService, copy);
+    }
+
+    private void updateVibrationSensorEnabled(OnOffType enabled) {
+        VibrationSensorServiceState copy = copyCurrentState();
+        if (copy == null) {
+            return;
+        }
+
+        copy.enabled = enabled == OnOffType.ON;
+
+        this.currentVibrationSensorState = copy;
+        updateServiceState(vibrationSensorService, copy);
+    }
+
+    @Nullable
+    private VibrationSensorServiceState copyCurrentState() {
+        if (currentVibrationSensorState != null) {
+            return currentVibrationSensorState.copy();
+        }
+
+        logger.warn("Could not obtain current vibration sensor service state, command will not be processed.");
+        return null;
+    }
+}

bundles/org.openhab.binding.boschshc/src/main/java/org/openhab/binding/boschshc/internal/discovery/ThingDiscoveryService.java

@@ -92,6 +92,7 @@ public class ThingDiscoveryService extends AbstractThingHandlerDiscoveryService<
             new AbstractMap.SimpleEntry<>("LEDVANCE_LIGHT", BoschSHCBindingConstants.THING_TYPE_SMART_BULB),
             new AbstractMap.SimpleEntry<>("SWD", BoschSHCBindingConstants.THING_TYPE_WINDOW_CONTACT),
             new AbstractMap.SimpleEntry<>("SWD2", BoschSHCBindingConstants.THING_TYPE_WINDOW_CONTACT_2),
+            new AbstractMap.SimpleEntry<>("SWD2_PLUS", BoschSHCBindingConstants.THING_TYPE_WINDOW_CONTACT_2_PLUS),
             new AbstractMap.SimpleEntry<>("TRV", BoschSHCBindingConstants.THING_TYPE_THERMOSTAT),
             new AbstractMap.SimpleEntry<>("WRC2", BoschSHCBindingConstants.THING_TYPE_UNIVERSAL_SWITCH),
             new AbstractMap.SimpleEntry<>("SWITCH2", BoschSHCBindingConstants.THING_TYPE_UNIVERSAL_SWITCH_2),

bundles/org.openhab.binding.boschshc/src/main/java/org/openhab/binding/boschshc/internal/services/vibrationsensor/VibrationSensorService.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.boschshc.internal.services.vibrationsensor;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.binding.boschshc.internal.services.BoschSHCService;
+import org.openhab.binding.boschshc.internal.services.vibrationsensor.dto.VibrationSensorServiceState;
+
+/**
+ * Service implementation for vibration sensors of door/window contacts.
+ * 
+ * @author David Pace - Initial contribution
+ *
+ */
+@NonNullByDefault
+public class VibrationSensorService extends BoschSHCService<VibrationSensorServiceState> {
+
+    public VibrationSensorService() {
+        super("VibrationSensor", VibrationSensorServiceState.class);
+    }
+}