0.2.0

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "homebridge-multitap-switch",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "homebridge-multitap-switch",
-      "version": "0.1.6",
+      "version": "0.2.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.6",
+  "version": "0.2.0",
   "description": "A configurable multi-tap switch for i.e. switching scenes",
   "license": "MIT",
   "repository": {

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,17 +61,29 @@ 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);
   }
 
+  /**
+   * Discover new and existing accessories
+   */
   discoverDevices() {
     const parsedConfig = new PluginConfig(this.config);
     for (const device of parsedConfig.Devices) {

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.Version, VERSION)
       .setCharacteristic(this.platform.Characteristic.SerialNumber, accessory.UUID);
 
-
+    /**
+     * 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,
       })
@@ -86,12 +95,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);
 
@@ -106,10 +118,11 @@ export class DeviceAccessory {
         newButton.setCharacteristic(this.platform.Characteristic.ServiceLabelIndex, 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 +139,7 @@ export class DeviceAccessory {
   }
 
   /**
-   * Trigger the next event
+   * Trigger/Fire the next programmable switch event
    */
   triggerNext() {
     if (this.NextItemToTrigger >= this.State.numberConfiguredScenes) {
@@ -134,7 +147,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 +156,15 @@ export class DeviceAccessory {
    */
   resetTrigger() {
     this.Log.log('Reset Scene Trigger');
-    this.serviceIn.updateCharacteristic(this.platform.Characteristic.On,
-      this.SwitchOn = false);
+    this.serviceIn.updateCharacteristic(this.platform.Characteristic.On, 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 +174,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 +189,75 @@ 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;
-    this.Log.debug('Set Characteristic NumScenes ->', numItemsToHandle);
-    this.State.numberConfiguredScenes = numItemsToHandle;
+    let numItemsToHandle = value as number;
 
-    //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;
-    this.Log.debug('Set Characteristic TriggerTimeout ->', triggerTimeout);
-    this.State.triggerTimeout = triggerTimeout;
+    let triggerTimeout = value as number;
 
-    //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.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;
   }
 }