Merge pull request #679 from openhab/rotation-trait

Add support for rotation trait

Author: michikrug

docs/USAGE.md

@@ -27,6 +27,10 @@ If you have any issues, questions or an idea for additional features, please tak
 This documentation refers to release [v4.1.0](https://github.com/openhab/openhab-google-assistant/releases/tag/v4.1.0) of [openHAB Google Assistant](https://github.com/openhab/openhab-google-assistant) published on 2025-07-23
 :::
 
+### v4.2.0 (Upcoming)
+
+- Added [Rotation trait](https://developers.home.google.com/cloud-to-cloud/traits/rotation) support to Awning, Blinds, Curtain, Pergola and Shutter devices
+
 ### v4.1.0
 
 - Added `queryOnly=true` option to [`Switch`](#switch) devices indicating that the device can only be queried for state information and not be controlled
@@ -496,9 +500,9 @@ Dimmer humidifierFanSpeedItem  (humidifierGroup) { ga="humidifierFanSpeed" }
 | | |
 |---|---|
 | **Device Type** | [Awning](https://developers.home.google.com/cloud-to-cloud/guides/awning), [Blinds](https://developers.home.google.com/cloud-to-cloud/guides/blinds), [Curtain](https://developers.home.google.com/cloud-to-cloud/guides/curtain), [Door](https://developers.home.google.com/cloud-to-cloud/guides/door), [Garage](https://developers.home.google.com/cloud-to-cloud/guides/garage), [Gate](https://developers.home.google.com/cloud-to-cloud/guides/gate), [Pergola](https://developers.home.google.com/cloud-to-cloud/guides/pergola), [Shutter](https://developers.home.google.com/cloud-to-cloud/guides/shutter), [Window](https://developers.home.google.com/cloud-to-cloud/guides/window) |
-| **Supported Traits** | [OpenClose](https://developers.home.google.com/cloud-to-cloud/traits/openclose), [StartStop](https://developers.home.google.com/cloud-to-cloud/traits/startstop) |
-| **Supported Items** | Contact (no device control), Switch (no open percentage), Rollershutter |
-| **Configuration** | (optional) `discreteOnly=true/false`<br>(optional) `queryOnly=true/false`<br>(optional) `inverted=true/false`<br>(optional) `checkState=true/false` |
+| **Supported Traits** | [OpenClose](https://developers.home.google.com/cloud-to-cloud/traits/openclose), [StartStop](https://developers.home.google.com/cloud-to-cloud/traits/startstop), [Rotation](https://developers.home.google.com/cloud-to-cloud/traits/rotation) (awning, blinds, curtain, pergola, shutter - requires group configuration) |
+| **Supported Items** | Contact (no device control), Switch (no open percentage), Rollershutter, Group (for rotation support) |
+| **Configuration** | (optional) `discreteOnly=true/false`<br>(optional) `queryOnly=true/false`<br>(optional) `inverted=true/false`<br>(optional) `checkState=true/false`<br>**Rotation Support (Groups with shutterRotation only):**<br>(optional) `supportsDegrees=true/false` (default: true)<br>(optional) `supportsContinuousRotation=true/false` (default: false)<br>(optional) `rotationDegreesMin=degrees` (default: 0)<br>(optional) `rotationDegreesMax=degrees` (default: 90) |
 
 Blinds and similar devices should always use the `Rollershutter` item type for proper functionality.
 Since Google and openHAB use the opposite percentage value for "opened" and "closed", the action will translate this automatically.
@@ -507,7 +511,64 @@ If the values are still inverted in your case, you can state the `inverted=true`
 Since Google only tells the open percentage (and not the verb "close" or "down"), it can not be differentiated between saying "set blind to 100%" or "open blind".
 Therefore, it is not possible to "not invert" the verbs, if the user chooses to invert the numbers.
 
+#### Rotation Support for Awning, Blinds, Curtain, Pergola, and Shutter
+
+Awnings, blinds, curtains, pergolas, and shutters support the [Rotation trait](https://developers.home.google.com/cloud-to-cloud/traits/rotation), allowing control of slat tilt/rotation in addition to opening/closing. This feature is only available for group-based configurations with separate position and rotation controls.
+
+**Group Configuration for Rotation:**
+For devices with separate items for position and rotation control:
+
 ```shell
+Group blindsGroup { ga="Blinds" }
+  Rollershutter blindsPosition  { ga="shutterPosition" }
+  Number        blindsRotation  { ga="shutterRotation" }
+```
+
+**Voice Commands:**
+
+- "Open the shutters to 50%"
+- "Tilt the shutters to 30 degrees"
+- "Set the blinds to 75%"
+- "Rotate the blinds to 45 degrees"
+
+**Group Members:**
+
+- `shutterPosition`: Controls the opening/closing position (Rollershutter, Dimmer, Number)
+- `shutterRotation`: Controls the slat rotation/tilt (Rollershutter, Dimmer, Number)
+
+**Configuration Options:**
+The rotation trait supports the following optional configuration parameters:
+
+- `supportsDegrees=true/false` (default: true) - Enable degree-based control (percentage is always supported)
+  - Set to `false` if you only want percentage-based control without degree conversion
+- `supportsContinuousRotation=true/false` (default: false) - Enable continuous rotation beyond limits
+- `rotationDegreesMin=degrees` (default: 0) - Minimum rotation in degrees (only used when supportsDegrees is true)
+- `rotationDegreesMax=degrees` (default: 90) - Maximum rotation in degrees (only used when supportsDegrees is true)
+
+::: tip Note
+openHAB items always store rotation as percentages (0-100). When `supportsDegrees=true`, the percentage is converted to/from degrees using the configured range for Google Assistant commands and state responses.
+:::
+
+```shell
+Group shutterGroup { ga="Shutter" [ rotationDegreesMin=-45, rotationDegreesMax=45 ] }
+  Rollershutter shutterPosition  { ga="shutterPosition" }
+  Number        shutterRotation  { ga="shutterRotation" }
+
+# Example with continuous rotation support
+Group blindsGroup { ga="Blinds" [ supportsContinuousRotation=true, rotationDegreesMin=0, rotationDegreesMax=360 ] }
+  Rollershutter blindsCover     { ga="shutterPosition" }
+  Number        blindsRotation  { ga="shutterRotation" }
+
+# Example with percentage-only control (no degree conversion)
+Group awningGroup { ga="Awning" [ supportsDegrees=false ] }
+  Rollershutter awningPosition  { ga="shutterPosition" }
+  Dimmer        awningSlats     { ga="shutterRotation" }
+```
+
+**Basic Examples:**
+
+```shell
+# Simple devices (no rotation)
 Rollershutter { ga="Awning" }
 Rollershutter { ga="Blinds" [ inverted=true ] }
 Rollershutter { ga="Curtain" }
@@ -517,6 +578,15 @@ Contact       { ga="Gate" }
 Rollershutter { ga="Pergola" }
 Rollershutter { ga="Shutter" }
 Rollershutter { ga="Window" }
+
+# Advanced devices with rotation support
+Group shutterGroup { ga="Shutter" }
+  Rollershutter ShutterPosition  { ga="shutterPosition" }
+  Number        ShutterTilt      { ga="shutterRotation" }
+
+Group blindsGroup { ga="Blinds" [ rotationDegreesMin=0, rotationDegreesMax=180 ] }
+  Rollershutter blindsPosition  { ga="shutterPosition" }
+  Rollershutter blindsSlats     { ga="shutterRotation" }
 ```
 
 ### Charger

functions/commandRegistry.js

@@ -38,6 +38,7 @@ const COMMAND_REGISTRY = [
   require('./commands/mute.js'),
   require('./commands/onoff.js'),
   require('./commands/openclose.js'),
+  require('./commands/rotateabsolute.js'),
   require('./commands/selectchannel.js'),
   require('./commands/setfanspeed.js'),
   require('./commands/sethumidity.js'),

functions/commands/openclose.js

@@ -9,19 +9,40 @@ class OpenClose extends DefaultCommand {
     return 'openPercent' in params && typeof params.openPercent === 'number';
   }
 
+  static getItemName(device) {
+    const members = this.getMembers(device);
+    // If device is a group with shutterPosition member, use that
+    if ('shutterPosition' in members) {
+      return members.shutterPosition;
+    }
+    // Otherwise use the device itself (single item case)
+    return device.id;
+  }
+
   static convertParamsToValue(params, _, device) {
     const itemType = this.getItemType(device);
-    if (itemType === 'Contact') {
+    const members = this.getMembers(device);
+
+    // Determine the actual item type to work with
+    let actualItemType = itemType;
+    if (itemType === 'Group' && 'shutterPosition' in members) {
+      // For group shutters, use the stored shutterPosition item type from customData
+      actualItemType = device.customData?.shutterPositionItemType || 'Rollershutter';
+    }
+
+    if (actualItemType === 'Contact') {
       throw { statusCode: 400 };
     }
+
     let openPercent = params.openPercent;
     if (this.isInverted(device)) {
       openPercent = 100 - openPercent;
     }
-    if (itemType === 'Rollershutter') {
+
+    if (actualItemType === 'Rollershutter') {
       return openPercent === 0 ? 'DOWN' : openPercent === 100 ? 'UP' : (100 - openPercent).toString();
     }
-    if (itemType === 'Switch') {
+    if (actualItemType === 'Switch') {
       return openPercent === 0 ? 'OFF' : 'ON';
     }
     return openPercent.toString();

functions/commands/rotateabsolute.js

@@ -0,0 +1,73 @@
+const DefaultCommand = require('./default.js');
+
+class RotateAbsolute extends DefaultCommand {
+  static get type() {
+    return 'action.devices.commands.RotateAbsolute';
+  }
+
+  static validateParams(params) {
+    return (
+      ('rotationPercent' in params && typeof params.rotationPercent === 'number') ||
+      ('rotationDegrees' in params && typeof params.rotationDegrees === 'number')
+    );
+  }
+
+  static getItemName(device) {
+    const members = this.getMembers(device);
+    // If device is a group with rotation member, use that
+    if ('shutterRotation' in members) {
+      return members.shutterRotation;
+    }
+    // Otherwise use the device itself (simple shutter case)
+    return device.id;
+  }
+
+  static convertParamsToValue(params, _, device) {
+    let targetValue;
+
+    if ('rotationPercent' in params) {
+      targetValue = params.rotationPercent;
+    } else if ('rotationDegrees' in params) {
+      // Convert degrees to percentage based on stored configuration
+      const rotationConfig = (device.customData && device.customData.rotationConfig) || {};
+      const rotationDegreesMin = rotationConfig.rotationDegreesMin ?? 0;
+      const rotationDegreesMax = rotationConfig.rotationDegreesMax ?? 90;
+      const degreeRange = rotationDegreesMax - rotationDegreesMin;
+      const normalizedDegrees = Math.max(0, Math.min(degreeRange, params.rotationDegrees - rotationDegreesMin));
+      targetValue = Math.round((normalizedDegrees / degreeRange) * 100);
+    }
+
+    // Handle inversion if device is inverted
+    if (this.isInverted(device)) {
+      targetValue = 100 - targetValue;
+    }
+
+    return targetValue.toString();
+  }
+
+  static getResponseStates(params, _, device) {
+    const response = {};
+    const rotationConfig = device?.customData?.rotationConfig ?? {};
+    const supportsDegrees = rotationConfig.supportsDegrees !== false;
+    const rotationDegreesMin = rotationConfig.rotationDegreesMin ?? 0;
+    const rotationDegreesMax = rotationConfig.rotationDegreesMax ?? 90;
+    const degreeRange = rotationDegreesMax - rotationDegreesMin;
+
+    // Always include rotationPercent and optionally rotationDegrees in response
+    if ('rotationPercent' in params) {
+      response.rotationPercent = params.rotationPercent;
+      if (supportsDegrees) {
+        response.rotationDegrees = Math.round(rotationDegreesMin + (params.rotationPercent / 100) * degreeRange);
+      }
+    } else {
+      // rotationDegrees in params
+      const normalizedDegrees = Math.max(0, Math.min(degreeRange, params.rotationDegrees - rotationDegreesMin));
+      response.rotationPercent = Math.round((normalizedDegrees / degreeRange) * 100);
+      response.rotationDegrees = params.rotationDegrees;
+    }
+
+    return response;
+  }
+}
+
+module.exports = RotateAbsolute;

functions/deviceRegistry.js

@@ -43,6 +43,7 @@ const Scene = require('./devices/scene.js');
 const SecuritySystem = require('./devices/securitysystem.js');
 const SimpleSecuritySystem = require('./devices/simplesecuritysystem.js');
 const Sensor = require('./devices/sensor.js');
+const Shutter = require('./devices/shutter.js');
 const Speaker = require('./devices/speaker.js');
 const SpecialColorLight = require('./devices/specialcolorlight.js');
 const TemperatureSensor = require('./devices/temperaturesensor.js');
@@ -106,6 +107,7 @@ const DEVICE_REGISTRY = [
   SecuritySystem,
   SimpleSecuritySystem,
   Sensor,
+  Shutter,
   Speaker,
   SpecialColorLight,
   TemperatureSensor,
@@ -131,17 +133,20 @@ const DEVICE_REGISTRY = [
     { type: 'SPRINKLER', name: 'Sprinkler' }
   ]),
 
+  // Simple device type variants - Shutter-based devices (support rotation trait)
+  ...createDeviceVariants(Shutter, [
+    { type: 'AWNING', name: 'Awning' },
+    { type: 'BLINDS', name: 'Blinds' },
+    { type: 'CURTAIN', name: 'Curtain' },
+    { type: 'PERGOLA', name: 'Pergola' }
+  ]),
+
   // Simple device type variants - OpenCloseDevice-based devices
   ...createDeviceVariants(OpenCloseDevice, [
     { type: 'DOOR', name: 'Door' },
     { type: 'GATE', name: 'Gate' },
-    { type: 'AWNING', name: 'Awning' },
-    { type: 'PERGOLA', name: 'Pergola' },
     { type: 'GARAGE', name: 'Garage' },
-    { type: 'WINDOW', name: 'Window' },
-    { type: 'BLINDS', name: 'Blinds' },
-    { type: 'CURTAIN', name: 'Curtain' },
-    { type: 'SHUTTER', name: 'Shutter' }
+    { type: 'WINDOW', name: 'Window' }
   ]),
 
   // Simple device type variants - Switch-based devices

functions/devices/climatesensor.js

@@ -72,7 +72,7 @@ class ClimateSensor extends DefaultDevice {
     }
     if ('humidityAmbient' in members) {
       const config = this.getConfig(item);
-      const maxHumidity = (config.maxHumidity && parseInt(config.maxHumidity)) || 100;
+      const maxHumidity = parseInt(config.maxHumidity) || 100;
       const humidity = Math.round(parseFloat(members.humidityAmbient.state) * (100 / maxHumidity));
       state.humidityAmbientPercent = humidity;
       state.humiditySetpointPercent = humidity;

functions/devices/default.js

@@ -158,7 +158,8 @@ class DefaultDevice {
       if (matchedType) {
         members[matchedType.name] = {
           name: member.name,
-          state: member.state
+          state: member.state,
+          type: memberType
         };
       }
     });

functions/devices/humidifier.js

@@ -104,14 +104,14 @@ class Humidifier extends DefaultDevice {
 
       // Humidity setpoint
       if ('humidifierHumiditySetpoint' in members) {
-        const maxHumidity = (config.maxHumidity && parseInt(config.maxHumidity)) || 100;
+        const maxHumidity = parseInt(config.maxHumidity) || 100;
         const humidity = Math.round(parseFloat(members.humidifierHumiditySetpoint.state) * (100 / maxHumidity));
         state.humiditySetpointPercent = humidity;
       }
 
       // Ambient humidity (read-only)
       if ('humidifierHumidityAmbient' in members) {
-        const maxHumidity = (config.maxHumidity && parseInt(config.maxHumidity)) || 100;
+        const maxHumidity = parseInt(config.maxHumidity) || 100;
         const humidity = Math.round(parseFloat(members.humidifierHumidityAmbient.state) * (100 / maxHumidity));
         state.humidityAmbientPercent = humidity;
       }

functions/devices/humiditysensor.js

@@ -25,7 +25,7 @@ class HumiditySensor extends DefaultDevice {
 
   static getState(item) {
     const config = this.getConfig(item);
-    const maxHumidity = (config.maxHumidity && parseInt(config.maxHumidity)) || 100;
+    const maxHumidity = parseInt(config.maxHumidity) || 100;
     const state = Math.round(parseFloat(item.state) * (100 / maxHumidity));
     return {
       humidityAmbientPercent: state,

functions/devices/securitysystem.js

@@ -76,17 +76,17 @@ class SecuritySystem extends DefaultDevice {
     if (item.members && item.members.length) {
       item.members.forEach((member) => {
         if (member.metadata && member.metadata.ga) {
-          const memberType = supportedMembers.find((m) => {
-            const memberType = (member.groupType || member.type || '').split(':')[0];
-            return m.types.includes(memberType) && member.metadata.ga.value.toLowerCase() === m.name.toLowerCase();
-          });
-          if (memberType) {
+          const memberType = (member.groupType || member.type || '').split(':')[0];
+          const supportedMember = supportedMembers.find(
+            (m) => m.types.includes(memberType) && member.metadata.ga.value.toLowerCase() === m.name.toLowerCase()
+          );
+          if (supportedMember) {
             const memberDetails = { name: member.name, state: member.state, config: this.getConfig(member) };
-            if (memberType.name === memberZone) {
+            if (supportedMember.name === memberZone) {
               members.zones = members.zones || [];
               members.zones.push(memberDetails);
             } else {
-              members[memberType.name] = memberDetails;
+              members[supportedMember.name] = memberDetails;
             }
           }
         }