Add extended vacuum device

Signed-off-by: Michael Krug <michi.krug@gmail.com>

Author: michikrug

docs/USAGE.md

@@ -237,6 +237,24 @@ Switch { ga="Washer" [ inverted=false ] }
 Switch { ga="Dishwasher" [ inverted=false ] }
 ```
 
+### Vacuum as Group with advanced functionality
+
+| | |
+|---|---|
+| **Device Type** | [Vacuum](https://developers.home.google.com/cloud-to-cloud/guides/vacuum) |
+| **Supported Traits** | [StartStop](https://developers.home.google.com/cloud-to-cloud/traits/startstop), [Dock](https://developers.home.google.com/cloud-to-cloud/traits/dock), [Locator](https://developers.home.google.com/cloud-to-cloud/traits/locator), [RunCycle](https://developers.home.google.com/cloud-to-cloud/traits/runcycle), [EnergyStorage](https://developers.home.google.com/cloud-to-cloud/traits/energystorage) |
+| **Supported Items** | Group as `Vacuum` with the following members:<br>(required) Switch as `vacuumPower`<br>(optional) Switch as `vacuumDock`<br>(optional) Switch as `vacuumLocate`<br>(optional) Number or Dimmer as `vacuumBattery`<br>(optional) String as `vacuumCurrentCycle` |
+| **Configuration** | (optional) `inverted=true/false`<br>(optional) `checkState=true/false` |
+
+```shell
+Group  vacuumRobot { ga="Vacuum" [ checkState=true ] }
+Switch vacuumPowerItem     (vacuumRobot) { ga="vacuumPower" }
+Switch vacuumDockItem      (vacuumRobot) { ga="vacuumDock" }
+Switch vacuumLocateItem    (vacuumRobot) { ga="vacuumLocate" }
+Number vacuumBatteryItem   (vacuumRobot) { ga="vacuumBattery" }
+String vacuumCycleItem     (vacuumRobot) { ga="vacuumCurrentCycle" }
+```
+
 ### Lock
 
 | | |

functions/commands/dock.js

@@ -0,0 +1,42 @@
+const DefaultCommand = require('./default.js');
+
+class Dock extends DefaultCommand {
+  static get type() {
+    return 'action.devices.commands.Dock';
+  }
+
+  static validateParams() {
+    return true; // No required parameters for dock command
+  }
+
+  static getItemName(device) {
+    if (this.getDeviceType(device) === 'Vacuum') {
+      const members = this.getMembers(device);
+      if ('vacuumDock' in members) {
+        return members.vacuumDock;
+      }
+      throw { statusCode: 400 };
+    }
+    return device.id;
+  }
+
+  static convertParamsToValue() {
+    return 'ON'; // Dock command always sends ON to dock the vacuum
+  }
+
+  static getResponseStates() {
+    return {
+      isDocked: true,
+      isRunning: false,
+      isPaused: false
+    };
+  }
+
+  static checkCurrentState(target, state) {
+    if (target === state) {
+      throw { errorCode: 'alreadyDocked' };
+    }
+  }
+}
+
+module.exports = Dock;

functions/commands/locate.js

@@ -0,0 +1,32 @@
+const DefaultCommand = require('./default.js');
+
+class Locate extends DefaultCommand {
+  static get type() {
+    return 'action.devices.commands.Locate';
+  }
+
+  static validateParams() {
+    return true; // No required parameters for locate command
+  }
+
+  static getItemName(device) {
+    if (this.getDeviceType(device) === 'Vacuum') {
+      const members = this.getMembers(device);
+      if ('vacuumLocate' in members) {
+        return members.vacuumLocate;
+      }
+      throw { statusCode: 400 };
+    }
+    return device.id;
+  }
+
+  static convertParamsToValue() {
+    return 'ON'; // Locate command sends ON to trigger the locate function
+  }
+
+  static checkCurrentState() {
+    return;
+  }
+}
+
+module.exports = Locate;

functions/commands/startstop.js

@@ -20,6 +20,17 @@ class StartStop extends DefaultCommand {
     return params.start ? 'ON' : 'OFF';
   }
 
+  static getItemName(device) {
+    if (this.getDeviceType(device) === 'Vacuum') {
+      const members = this.getMembers(device);
+      if ('vacuumPower' in members) {
+        return members.vacuumPower;
+      }
+      throw { statusCode: 400 };
+    }
+    return device.id;
+  }
+
   static getResponseStates(params) {
     return {
       isRunning: params.start,

functions/devices/default.js

@@ -136,24 +136,36 @@ class DefaultDevice {
   }
 
   /**
-   * @returns {object}
+   * Gets supported members from an openHAB group item
+   * @param {object} item - The openHAB item with potential members
+   * @returns {object} Mapped members with their names and states
    */
   static getMembers(item) {
     const supportedMembers = this.supportedMembers;
     const members = {};
-    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) {
-            members[memberType.name] = { name: member.name, state: member.state };
-          }
-        }
-      });
+    // Early return if no members or supportedMembers
+    if (!item.members?.length || !supportedMembers.length) {
+      return members;
     }
+    item.members.forEach((member) => {
+      // Skip members without Google Assistant metadata
+      if (!member.metadata?.ga?.value) {
+        return;
+      }
+      const memberType = (member.groupType || member.type || '').split(':')[0];
+      const gaValue = member.metadata.ga.value.toLowerCase();
+      // Find matching supported member by type and name
+      const matchedType = supportedMembers.find(
+        (supportedMember) =>
+          supportedMember.types.includes(memberType) && supportedMember.name.toLowerCase() === gaValue
+      );
+      if (matchedType) {
+        members[matchedType.name] = {
+          name: member.name,
+          state: member.state
+        };
+      }
+    });
     return members;
   }
 }

functions/devices/simplevacuum.js

@@ -0,0 +1,9 @@
+const StartStopSwitch = require('./startstopswitch.js');
+
+class SimpleVacuum extends StartStopSwitch {
+  static get type() {
+    return 'action.devices.types.VACUUM';
+  }
+}
+
+module.exports = SimpleVacuum;

functions/devices/vacuum.js

@@ -1,9 +1,101 @@
-const StartStopSwitch = require('./startstopswitch.js');
+const DefaultDevice = require('./default.js');
 
-class Vacuum extends StartStopSwitch {
+class Vacuum extends DefaultDevice {
   static get type() {
     return 'action.devices.types.VACUUM';
   }
+
+  static getTraits(item) {
+    const members = this.getMembers(item);
+    const traits = ['action.devices.traits.StartStop'];
+    if ('vacuumDock' in members) traits.push('action.devices.traits.Dock');
+    if ('vacuumLocate' in members) traits.push('action.devices.traits.Locator');
+    if ('vacuumCurrentCycle' in members) traits.push('action.devices.traits.RunCycle');
+    if ('vacuumBattery' in members) traits.push('action.devices.traits.EnergyStorage');
+    return traits;
+  }
+
+  static get requiredItemTypes() {
+    return ['Group'];
+  }
+
+  static matchesDeviceType(item) {
+    return super.matchesDeviceType(item) && Object.keys(this.getMembers(item)).length > 0;
+  }
+
+  static get supportedMembers() {
+    return [
+      { name: 'vacuumPower', types: ['Switch'] },
+      { name: 'vacuumDock', types: ['Switch'] },
+      { name: 'vacuumBattery', types: ['Number', 'Dimmer'] },
+      { name: 'vacuumLocate', types: ['Switch'] },
+      { name: 'vacuumCurrentCycle', types: ['String'] }
+    ];
+  }
+
+  static getAttributes(item) {
+    const attributes = {
+      pausable: false
+    };
+
+    const members = this.getMembers(item);
+    if ('vacuumBattery' in members) {
+      attributes.queryOnlyEnergyStorage = true;
+    }
+
+    return attributes;
+  }
+
+  static getState(item) {
+    const state = {
+      isRunning: false,
+      isPaused: false
+    };
+    const config = this.getConfig(item);
+    const members = this.getMembers(item);
+
+    for (const member in members) {
+      switch (member) {
+        case 'vacuumPower': {
+          let isRunning = members[member].state === 'ON';
+          if (config.inverted === true) {
+            isRunning = !isRunning;
+          }
+          state.isRunning = isRunning;
+          state.isPaused = false; // Default to not paused when running/stopped
+          break;
+        }
+
+        case 'vacuumDock':
+          state.isDocked = members[member].state === 'ON';
+          break;
+
+        case 'vacuumBattery': {
+          const batteryLevel = parseInt(members[member].state) || 0;
+          state.descriptiveCapacityRemaining = 'FULL';
+          state.capacityRemaining = [{ unit: 'PERCENTAGE', rawValue: batteryLevel }];
+          if (batteryLevel <= 15) {
+            state.descriptiveCapacityRemaining = 'CRITICALLY_LOW';
+          } else if (batteryLevel <= 25) {
+            state.descriptiveCapacityRemaining = 'LOW';
+          } else if (batteryLevel <= 75) {
+            state.descriptiveCapacityRemaining = 'MEDIUM';
+          }
+          break;
+        }
+
+        case 'vacuumCurrentCycle':
+          state.currentRunCycle = [
+            {
+              currentCycle: members[member].state || 'unknown',
+              lang: 'en'
+            }
+          ];
+          break;
+      }
+    }
+    return state;
+  }
 }
 
 module.exports = Vacuum;

tests/commands/dock.test.js

@@ -0,0 +1,59 @@
+const Command = require('../../functions/commands/dock.js');
+
+describe('Dock Command', () => {
+  test('validateParams', () => {
+    expect(Command.validateParams()).toBe(true);
+    expect(Command.validateParams({})).toBe(true);
+    expect(Command.validateParams({ anyParam: 'value' })).toBe(true);
+  });
+
+  describe('getItemName', () => {
+    test('getItemName - Group with vacuumDock member', () => {
+      const device = {
+        id: 'VacuumGroup',
+        customData: {
+          deviceType: 'Vacuum',
+          members: {
+            vacuumDock: 'VacuumDockSwitch'
+          }
+        }
+      };
+      expect(Command.getItemName(device)).toBe('VacuumDockSwitch');
+    });
+
+    test('getItemName - simple Switch item', () => {
+      const device = {
+        id: 'VacuumSwitch',
+        customData: {
+          itemType: 'Switch'
+        }
+      };
+      expect(Command.getItemName(device)).toBe('VacuumSwitch');
+    });
+  });
+
+  test('convertParamsToValue', () => {
+    expect(Command.convertParamsToValue()).toBe('ON');
+    expect(Command.convertParamsToValue({})).toBe('ON');
+    expect(Command.convertParamsToValue({ anyParam: 'value' })).toBe('ON');
+  });
+
+  test('getResponseStates', () => {
+    expect(Command.getResponseStates()).toStrictEqual({
+      isDocked: true,
+      isRunning: false,
+      isPaused: false
+    });
+  });
+
+  test('checkCurrentState', () => {
+    expect(Command.checkCurrentState('OFF', 'ON')).toBeUndefined();
+
+    expect.assertions(2);
+    try {
+      Command.checkCurrentState('ON', 'ON');
+    } catch (e) {
+      expect(e.errorCode).toBe('alreadyDocked');
+    }
+  });
+});

tests/commands/locate.test.js

@@ -0,0 +1,47 @@
+const Command = require('../../functions/commands/locate.js');
+
+describe('Locate Command', () => {
+  test('validateParams', () => {
+    expect(Command.validateParams()).toBe(true);
+    expect(Command.validateParams({})).toBe(true);
+    expect(Command.validateParams({ anyParam: 'value' })).toBe(true);
+  });
+
+  describe('getItemName', () => {
+    test('getItemName - Group with vacuumLocate member', () => {
+      const device = {
+        id: 'VacuumGroup',
+        customData: {
+          deviceType: 'Vacuum',
+          members: {
+            vacuumLocate: 'VacuumLocateSwitch'
+          }
+        }
+      };
+      expect(Command.getItemName(device)).toBe('VacuumLocateSwitch');
+    });
+
+    test('getItemName - simple Switch item', () => {
+      const device = {
+        id: 'VacuumSwitch',
+        customData: {
+          itemType: 'Switch'
+        }
+      };
+      expect(Command.getItemName(device)).toBe('VacuumSwitch');
+    });
+  });
+
+  test('convertParamsToValue', () => {
+    expect(Command.convertParamsToValue()).toBe('ON');
+    expect(Command.convertParamsToValue({})).toBe('ON');
+    expect(Command.convertParamsToValue({ anyParam: 'value' })).toBe('ON');
+  });
+
+  test('checkCurrentState', () => {
+    // Locate command can always be executed
+    expect(Command.checkCurrentState('ON', 'ON')).toBeUndefined();
+    expect(Command.checkCurrentState('OFF', 'ON')).toBeUndefined();
+    expect(Command.checkCurrentState('ON', 'OFF')).toBeUndefined();
+  });
+});