0.3.0

.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish Package to npmjs
+on:
+  release:
+    types: [created]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '16.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.npmignore

@@ -1,6 +1,9 @@
 # Ignore source code
 src
 
+# IDEA files
+.idea
+
 # ------------- Defaults ------------- #
 
 # gitHub actions

README.md

@@ -41,7 +41,9 @@ The configuration allows the user to add multiple **Multi-Tap-Switches**. The fo
 | `devices[].resetAfterSwitchOff`    | false          |                                        | Reset the switch (like after timeout), when it is turned ```OFF```.                       |
 | `devices[].logging`                | false          |                                        | Logging of switch/trigger actions.                                                        |
 
-The parameter ```triggerTimeout``` can be changed in the configuration during runtime. So, this is just the initial value.
+The parameter ```triggerTimeout``` can be changed in the configuration during runtime. So, this is just the initial value.<br>
+> **NOTE:** If the value is out of sync from the configured value (i.e. updated via Home-App), it will not be updated on later configuration changes.
+> It must be set back to the configured value first! 
 
 The parameter ```numberConfiguredScenes``` just defines how many **programmable** switches are available. The number of
 really **used** switches can configured during runtime, between 0 and the configured number.

config.schema.json

@@ -10,14 +10,9 @@
         "title": "Platform Name",
         "type": "string",
         "required": true,
+        "minLength": 3,
         "default": "MultiTapSwitch"
       },
-      "enabled": {
-        "title": "Enable",
-        "type": "boolean",
-        "required": true,
-        "default": true
-      },
       "devices": {
         "type": "array",
         "items": {
@@ -53,7 +48,7 @@
             "resetAfterSwitchOff": {
               "title": "Reset when switch turned `Off`",
               "type": "boolean",
-              "description": "Reset the switch and trigger index, when the trigger switch is turned `Off` (independent from timeout)",
+              "description": "Reset the switch and trigger index, when the trigger switch is turned <code>Off</code> (independent from timeout)",
               "required": true,
               "default": false
             },

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "homebridge-multitap-switch",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "homebridge-multitap-switch",
-      "version": "0.1.1",
+      "version": "0.3.0",
       "license": "MIT",
       "devDependencies": {
         "@types/node": "^16.10.9",

package.json

@@ -2,7 +2,7 @@
   "private": false,
   "displayName": "Homebridge Multi-Tap-Switch",
   "name": "homebridge-multi-tap-switch",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A configurable multi-tap switch for i.e. switching scenes",
   "license": "MIT",
   "repository": {

src/config.ts

@@ -60,6 +60,7 @@ export interface AccessoryState {
   numberConfiguredScenes: number;
   triggerTimeout: number;
   //nextSceneToTrigger: number;
+  triggerTimeoutManuallyChanged: boolean;
 }
 
 export function initializeAccessoryState(initConfig: PluginDeviceConfig | AccessoryState): AccessoryState {
@@ -67,5 +68,6 @@ export function initializeAccessoryState(initConfig: PluginDeviceConfig | Access
     numberConfiguredScenes: initConfig.numberConfiguredScenes || DEFAULT_NUM_OF_CONFIGURED_SCENES,
     triggerTimeout: initConfig.triggerTimeout || DEFAULT_TRIGGER_TIMEOUT,
     //nextSceneToTrigger: 0,
+    triggerTimeoutManuallyChanged: false,
   };
 }

src/helper/logger.ts

@@ -21,8 +21,8 @@ export class Logging {
 
   log(...parts: any) {
     this.isDebug ?
-      this.logHandler.debug(this.msgPrefix(), ...parts) :
+      this.logHandler.info(this.msgPrefix(), ...parts) :
-      this.logHandler.info(this.msgPrefix(), ...parts);
+      this.logHandler.debug(this.msgPrefix(), ...parts);
   }
 
   warn = (...parts: any) => this.logHandler.warn(this.msgPrefix(), ...parts);

src/platform.ts

@@ -28,6 +28,12 @@ export class MultiTapSwitchPlatform implements DynamicPlatformPlugin {
 
   public readonly Config: PluginConfig;
 
+  /**
+   * Construct the Homebridge platform
+   * @param log Homebridge Logger
+   * @param config Homebridge Configuration (from config.json)
+   * @param api Homebridge API
+   */
   constructor(
     public readonly log: Logger,
     public readonly config: PlatformConfig,
@@ -55,18 +61,32 @@ export class MultiTapSwitchPlatform implements DynamicPlatformPlugin {
       {value: this.CharacteristicTriggerTimeout});
   }
 
+  /**
+   * Homebridge Accessory Configuration Callback
+   * @param accessory Accessory to previously added by this platform
+   */
   configureAccessory(accessory: PlatformAccessory) {
     this.log.info('Load cached Accessory:', accessory.displayName);
 
-    // add the restored accessory to the accessories cache so we can track if it has already been registered
+    // add the restored accessory to the accessories cache, so we can track if it has already been registered
     this.accessories.push(accessory);
   }
 
+  /**
+   * Calculate the UUIDs
+   * @param name Name to use for the calculation
+   * @param serial (optional) Provide an additional number (might be obsolete in future releases)
+   */
   defineUuid(name: string | undefined, serial = 'UNDEF'): string {
-    return this.api.hap.uuid.generate(name + '_' + serial);
+    return this.api.hap.uuid.generate(PLATFORM_NAME + '_' + name + '_' + serial);
   }
 
+  /**
+   * Discover new and existing accessories
+   */
   discoverDevices() {
+    const knownUuids: string[] = [];
+
     const parsedConfig = new PluginConfig(this.config);
     for (const device of parsedConfig.Devices) {
       const uuid = this.defineUuid(device.name, '0');
@@ -82,8 +102,8 @@ export class MultiTapSwitchPlatform implements DynamicPlatformPlugin {
         // if you need to update the accessory.context then you should run `api.updatePlatformAccessories`. eg.:
         // existingAccessory.context.device = device;
         // this.api.updatePlatformAccessories([existingAccessory]);
-        if (existingAccessory.context.config !== device) {
+        if (JSON.stringify(existingAccessory.context.config) !== JSON.stringify(device)) {
-          this.log.info('Update Accessory ->', device.name);
+          this.log.debug('Update Accessory ->', device.name);
           existingAccessory.context.config = device;
           this.api.updatePlatformAccessories([existingAccessory]);
         }
@@ -91,6 +111,8 @@ export class MultiTapSwitchPlatform implements DynamicPlatformPlugin {
         // Create the accessory handler for the restored accessory
         // This is imported from `platformAccessory.ts`
         new DeviceAccessory(this, existingAccessory);
+
+        knownUuids.push(uuid);
       } else {
         // Accessory does not yet exist, so we need to create it
         this.log.info('Add Device ->', device.name, '/',
@@ -112,5 +134,13 @@ export class MultiTapSwitchPlatform implements DynamicPlatformPlugin {
         this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
       }
     }
+
+    // Unregister unused accessories
+    for (const device of this.accessories) {
+      if (!knownUuids.find(id => id === device.UUID)) {
+        this.log.info('Remove unused device ->', device.displayName, '/', device.UUID);
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [device]);
+      }
+    }
   }
 }

src/platformAccessory.ts

@@ -29,6 +29,11 @@ export class DeviceAccessory {
 
   private Log: Logging;
 
+  /**
+   * Construct the accessory services
+   * @param platform Parent Homebridge platform
+   * @param accessory Accessory to which these services will be attached
+   */
   constructor(
     private readonly platform: MultiTapSwitchPlatform,
     private readonly accessory: PlatformAccessory,
@@ -37,16 +42,20 @@ export class DeviceAccessory {
     this.State = this.accessory.context.persistent;
 
     this.Log = new Logging(platform.log, this.Config.Name(), this.Config.isLogging());
-    this.Log.log('Initialize Accessory', this.Config.Name());
+    this.Log.log('Initialize Accessory ->', this.Config.Name());
 
-    // Set accessory information
+    /**
+     * Accessory information
+     */
     this.accessory.getService(this.platform.Service.AccessoryInformation)!
-      .setCharacteristic(this.platform.Characteristic.Manufacturer, 'TippyTapper')
+      .setCharacteristic(this.platform.Characteristic.Manufacturer, 'HB/dtw')
-      .setCharacteristic(this.platform.Characteristic.Model, 'SceneSwitch')
+      .setCharacteristic(this.platform.Characteristic.Model, 'Multi-Tap-Switch')
       .setCharacteristic(this.platform.Characteristic.Version, VERSION)
-      .setCharacteristic(this.platform.Characteristic.SerialNumber, accessory.UUID);
+      .setCharacteristic(this.platform.Characteristic.SerialNumber, this.Config.Name());
-
 
+    /**
+     * Input Service / Switch
+     */
     // Get or Create the input switch service
     this.serviceIn = this.accessory.getService(this.platform.Service.Switch)
       || this.accessory.addService(this.platform.Service.Switch);
@@ -63,7 +72,7 @@ export class DeviceAccessory {
     (this.serviceIn.getCharacteristic(this.platform.Characteristic.ConfiguredScenes)
       || this.serviceIn.addOptionalCharacteristic(this.platform.Characteristic.ConfiguredScenes))
       .setProps({
-        'minValue': 0,
+        'minValue': 1,
         'maxValue': this.Config.NumOfScenes(),
         'minStep': 1,
       })
@@ -72,6 +81,12 @@ export class DeviceAccessory {
       .updateValue(this.State.numberConfiguredScenes);
 
     // Register handlers for the TriggerTimeout characteristic & restore previous value
+    if (!this.State.triggerTimeoutManuallyChanged) {
+      this.State.triggerTimeout = this.Config.TriggerTimeout();
+    } else {
+      this.Log.debug('Current Trigger Timeout [' + this.State.triggerTimeout + '] differs from configured value [' +
+        this.Config.TriggerTimeout() + ']. It won\'t be updated until it\'s equal again.');
+    }
     (this.serviceIn.getCharacteristic(this.platform.Characteristic.TriggerTimeout)
        || this.serviceIn.addOptionalCharacteristic(this.platform.Characteristic.TriggerTimeout))
       .setProps({
@@ -86,12 +101,15 @@ export class DeviceAccessory {
     // Set the service name, this is what is displayed as the default name on the Home app
     this.serviceIn.setCharacteristic(this.platform.Characteristic.Name, this.Config.Name());
 
+    /**
+     * Output Service / Service Label & Stateless Programmable Switches
+     */
     // Get or Create the output service (excluding the buttons)
     this.serviceOut = this.accessory.getService(this.platform.Service.ServiceLabel)
       || this.accessory.addService(this.platform.Service.ServiceLabel);
     this.serviceOut.setCharacteristic(this.platform.Characteristic.ServiceLabelNamespace, 1);
 
-    // Create max configured number of scene buttons
+    // Create max configured number of programmable switches
     for (let i = 1; i <= this.Config.NumOfScenes(); i++) {
       this.Log.debug('Handle Scene Button -> ', i);
 
@@ -103,13 +121,16 @@ export class DeviceAccessory {
         this.serviceOut.addLinkedService(newButton);
         newButton.getCharacteristic(this.platform.Characteristic.ProgrammableSwitchEvent)
           .setProps(this.singleButtonEvents);
-        newButton.setCharacteristic(this.platform.Characteristic.ServiceLabelIndex, i);
+        newButton
+          .setCharacteristic(this.platform.Characteristic.ServiceLabelIndex, i)
+          .setCharacteristic(this.platform.Characteristic.Name, 'Scene ' + i);
       }
 
+      // Push switches to an internal list for later use
       this.TriggerButtons.push(newButton);
     }
 
-    // Remove buttons, if max buttons is smaller
+    // Remove any programmable switches, that exceed the maximum of configured switches
     for (let i = this.TriggerButtons.length + 1;; i++) {
       const exButton = this.accessory.getService('Scene ' + i);
       if (exButton) {
@@ -126,7 +147,7 @@ export class DeviceAccessory {
   }
 
   /**
-   * Trigger the next event
+   * Trigger/Fire the next programmable switch event
    */
   triggerNext() {
     if (this.NextItemToTrigger >= this.State.numberConfiguredScenes) {
@@ -134,7 +155,7 @@ export class DeviceAccessory {
     }
 
     // Trigger Scene Button
-    this.Log.log('Trigger Scene -> ', this.NextItemToTrigger);
+    this.Log.log('Trigger Event -> ', this.NextItemToTrigger);
     this.TriggerButtons[this.NextItemToTrigger++].updateCharacteristic(this.platform.Characteristic.ProgrammableSwitchEvent, 0);
   }
 
@@ -143,13 +164,15 @@ export class DeviceAccessory {
    */
   resetTrigger() {
     this.Log.log('Reset Scene Trigger');
-    this.serviceIn.updateCharacteristic(this.platform.Characteristic.On,
+    this.serviceIn.updateCharacteristic(this.platform.Characteristic.On, this.SwitchOn = false);
-      this.SwitchOn = false);
     this.NextItemToTrigger = 0;
   }
 
-
+  /**
-  // Switch Handlers
+   * Handle state changes of the input switch
+   * This function does all the necessary work.
+   * @param value Target switch state from Automation or manual state change
+   */
   async setOn(value: CharacteristicValue) {
     // implement your own code to turn your device on/off
     this.SwitchOn = value as boolean;
@@ -159,7 +182,7 @@ export class DeviceAccessory {
         clearTimeout(this.SwitchResetTimer);
       }
 
-      // Start the reset timer, if paramter is greater than 0.
+      // Start the reset timer, if parameter is greater than 0.
       // Otherwise, do nothing.
       if (this.State.triggerTimeout > 0) {
         this.SwitchResetTimer = setTimeout(this.resetTrigger.bind(this), this.State.triggerTimeout * 1000);
@@ -174,44 +197,84 @@ export class DeviceAccessory {
       this.resetTrigger();
     }
 
-    this.Log.debug('Set Characteristic On ->', value);
+    this.Log.debug('Set Switch State ->', value);
   }
 
+  /**
+   * Report state of the input switch back to HomeKit (for visualization)
+   */
   async getOn(): Promise<CharacteristicValue> {
     const isOn = this.SwitchOn;
-    this.Log.debug('Get Characteristic On ->', isOn);
+    this.Log.debug('Get Switch State ->', isOn);
     // if you need to return an error to show the device as "Not Responding" in the Home app:
     // throw new this.platform.api.hap.HapStatusError(this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
     return isOn;
   }
 
-  // NumScenes Handlers
+  /**
+   * Set the number of active switches.
+   * The final value is limited to the maximum configured number of programmable switches.
+   * @param value Number of active switches
+   */
   async setItemsToHandle(value: CharacteristicValue) {
-    const numItemsToHandle = value as number;
+    let numItemsToHandle = value as number;
-    this.Log.debug('Set Characteristic NumScenes ->', numItemsToHandle);
-    this.State.numberConfiguredScenes = numItemsToHandle;
 
-    //this.updatePersistentData();
+    if ((numItemsToHandle > 0) && (numItemsToHandle <= this.Config.NumOfScenes())) {
+      this.Log.log('Set number of Active Switches ->', numItemsToHandle);
+    } else {
+      this.Log.warn(
+        'Set number of Active Switches ->', numItemsToHandle, '-> Out-of-Range / Value must be between 1 and', this.Config.NumOfScenes());
+      if (numItemsToHandle > this.Config.NumOfScenes()) {
+        numItemsToHandle = this.Config.NumOfScenes();
+      } else {
+        numItemsToHandle = 1;
+      }
     }
 
+    this.State.numberConfiguredScenes = numItemsToHandle;
+  }
+
+  /**
+   * Report number of active switches back to HomeKit (for visualization)
+   */
   async getItemsToHandle(): Promise<CharacteristicValue> {
     const numItemsToHandle = this.State.numberConfiguredScenes;
-    this.Log.debug('Get Characteristic NumScenes ->', numItemsToHandle);
+    this.Log.debug('Get Number of Active Switches ->', numItemsToHandle);
     return numItemsToHandle;
   }
 
-  // TriggerTimeout Handlers
+  /**
+   * Set the timeout before resetting the trigger counter.
+   * @param value Time in seconds
+   */
   async setTriggerTimeout(value: CharacteristicValue) {
-    const triggerTimeout = value as number;
+    let triggerTimeout = value as number;
-    this.Log.debug('Set Characteristic TriggerTimeout ->', triggerTimeout);
-    this.State.triggerTimeout = triggerTimeout;
 
-    //this.updatePersistentData();
+    if (triggerTimeout >= 0) {
+      this.Log.log('Set Trigger Timeout ->', triggerTimeout);
+    } else {
+      this.Log.warn(
+        'Set Trigger Timeout ->', triggerTimeout, '-> Out-of-Range / Value must be greater or equal to 0');
+      triggerTimeout = 0;
     }
 
+    this.State.triggerTimeoutManuallyChanged = (this.Config.TriggerTimeout() !== triggerTimeout);
+    if (!this.State.triggerTimeoutManuallyChanged) {
+      this.Log.debug('Trigger Timeout in sync with config.');
+    } else {
+      this.Log.warn('Trigger Timeout not in sync with config value [' + this.Config.TriggerTimeout() + '].');
+      this.Log.warn('It will not be updated by config changes, until it is in sync again!');
+    }
+
+    this.State.triggerTimeout = triggerTimeout;
+  }
+
+  /**
+   * Report the timeout before resetting the trigger back to HomeKit (for visualization)
+   */
   async getTriggerTimeout(): Promise<CharacteristicValue> {
     const triggerTimeout = this.State.triggerTimeout;
-    this.Log.debug('Get Characteristic TriggerTimeout ->', triggerTimeout);
+    this.Log.debug('Get Trigger Timeout ->', triggerTimeout);
     return triggerTimeout;
   }
 }