homebridge-lib 6.0.2 → 6.2.0

package/README.md

@@ -13,7 +13,7 @@
 </span>
 
 ## Library for Homebridge Plugins
-Copyright © 2018-2022 Erik Baauw. All rights reserved.
+Copyright © 2018-2023 Erik Baauw. All rights reserved.
 
 While developing a number of [Homebridge](https://github.com/homebridge/homebridge) plugins, I find myself duplicating a lot of code.
 The idea behind this library is to ease developing and maintaining Homebridge plugins by separating this generic code, dealing with [HomeKit](http://www.apple.com/ios/home/) and Homebridge, from the specific code, dealing with the actual devices being exposed to HomeKit.

package/cli/hap.js

@@ -3,7 +3,7 @@
 // homebridge-lib/cli/hap.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2018-2022 Erik Baauw. All rights reserved.
+// Copyright © 2018-2023 Erik Baauw. All rights reserved.
 //
 // Logger for HomeKit accessory announcements.
 

package/cli/json.js

@@ -3,7 +3,7 @@
 // homebridge-lib/cli/json.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2018-2022 Erik Baauw. All rights reserved.
+// Copyright © 2018-2023 Erik Baauw. All rights reserved.
 //
 // JSON formatter.
 

package/cli/sysinfo.js

@@ -3,7 +3,7 @@
 // homebridge-lib/cli/sysinfo.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2021-2022 Erik Baauw. All rights reserved.
+// Copyright © 2021-2023 Erik Baauw. All rights reserved.
 //
 // Show system info.
 

package/cli/upnp.js

@@ -3,7 +3,7 @@
 // homebridge-lib/cli/upnp.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2018-2022 Erik Baauw. All rights reserved.
+// Copyright © 2018-2023 Erik Baauw. All rights reserved.
 //
 // Logger for UPnP device announcements.
 

package/index.js

@@ -1,7 +1,7 @@
 // homebridge-lib/index.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 

package/lib/AccessoryDelegate.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/AccessoryDelegate.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
@@ -49,23 +49,20 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
 
     // Link or create associated PlatformAccessory.
     this._accessory = this._platform._getAccessory(this, params)
-
-    if (params.logLevel != null) {
-      this.warn('params.logLevel: deprecated')
-    }
-    if (params.inheritLogLevel != null) {
-      this.warn('params.inheritLogLevel: deprecated')
-    }
     this._context = this._accessory.context
 
-    delete this._context.logLevel
-
     // Setup shortcut for property values and values of the characteristics
     // of the _Accessory Information_ service.
     this._values = {} // by key
     this._propertyDelegates = {}
+    this.addPropertyDelegate({ key: 'className', value: this.constructor.name, silent: true })
+    this.addPropertyDelegate({ key: 'version', silent: true })
+    this.values.version = platform.packageJson.version
+    this.addPropertyDelegate({ key: 'id', value: params.id, silent: true })
+    this.addPropertyDelegate({ key: 'logLevel', value: platform.logLevel })
     this.addPropertyDelegate({ key: 'name', value: this.name, silent: true })
       .on('didSet', (name) => { this.name = name })
+    this.addPropertyDelegate({ key: 'uiPort', silent: true })
 
     // Create delegate for AccessoryInformation service.
     this._serviceDelegates = {}
@@ -76,30 +73,37 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     this._accessory.on('identify', this._identify.bind(this))
 
     this.once('initialised', () => {
-      const services = []
+      const staleServices = []
       for (const service of this._accessory.services) {
         const key = service.UUID +
           (service.subtype == null ? '' : '.' + service.subtype)
         if (this._serviceDelegates[key] == null) {
           if (service.UUID !== this.Services.hap.ProtocolInformation.UUID) {
-            services.push(service)
+            service.key = key
+            staleServices.push(service)
           }
         } else {
           this._serviceDelegates[key].emit('initialised')
         }
       }
-      for (const service of services) {
-        this.debug('remove stale service %s', service.displayName)
+      for (const service of staleServices) {
+        this.warn('remove stale service %s (%s)', service.key, service.constructor.name)
         this._accessory.removeService(service)
       }
       const staleKeys = []
       for (const key in this._context) {
-        if (this._serviceDelegates[key] == null && startsWithUuid.test(key)) {
-          staleKeys.push(key)
+        if (startsWithUuid.test(key)) {
+          if (this._serviceDelegates[key] == null) {
+            staleKeys.push(key)
+          }
+        } else {
+          if (key !== 'context' && this._propertyDelegates[key] == null) {
+            staleKeys.push(key)
+          }
         }
       }
       for (const key of staleKeys) {
-        this.debug('remove stale context %s', key)
+        this.warn('remove stale context %s', key)
         delete this._context[key]
       }
     })
@@ -142,10 +146,6 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     * @param {?boolean} params.logLevel - Level for homebridge log messages
     * when property was set or has been changed.
     * @param {?string} params.unit - The unit of the value of the property.
-    * @throws {TypeError} When a parameter has an invalid type.
-    * @throws {RangeError} When a parameter has an invalid value.
-    * @throws {SyntaxError} When a mandatory parameter is missing or an
-    * optional parameter is not applicable.
     * @returns {PropertyDelegate}
     * @throws {TypeError} When a parameter has an invalid type.
     * @throws {RangeError} When a parameter has an invalid value.
@@ -186,7 +186,7 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     const delegate = this._propertyDelegates[key]
     delegate._destroy()
     delete this._propertyDelegates[key]
-    delete this._context[key]
+    delete this.context[key]
   }
 
   /** Returns the property delegate correspondig to the property key.
@@ -251,7 +251,7 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     * @type {!integer}
     */
   get logLevel () {
-    return this.platform.logLevel
+    return this.values.logLevel == null ? this.platform.logLevel : this.values.logLevel
   }
 
   /** Inherit `logLevel` from another accessory delegate.
@@ -271,14 +271,17 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
   }
 
   /** Manage `logLevel` from characteristic delegate.
-    * @param {CharacteristicDelegate} delegate - The delegate of the `logLevel`
-    * characteristic.
+    * @param {CharacteristicDelegate|PropertyDelegate} delegate - The delegate
+    * of the `logLevel` characteristic.
     * @param {Boolean} [forPlatform=false] - Manage the Platform `logLevel` as
     * well.
     */
   manageLogLevel (delegate, forPlatform = false) {
-    if (!(delegate instanceof homebridgeLib.CharacteristicDelegate)) {
-      throw new TypeError('delegate: not an CharacteristicDelegate')
+    if (
+      !(delegate instanceof homebridgeLib.CharacteristicDelegate) &&
+      !(delegate instanceof homebridgeLib.PropertyDelegate)
+    ) {
+      throw new TypeError('delegate: not a CharacteristicDelegate or PropertyDelegate')
     }
     Object.defineProperty(this, 'logLevel', {
       get () { return delegate.value }

package/lib/AdaptiveLighting.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/AdaptiveLighting.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2020-2022 Erik Baauw. All rights reserved.
+// Copyright © 2020-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 

package/lib/CharacteristicDelegate.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/CharacteristicDelegate.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
@@ -121,11 +121,13 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
       const Characteristic = params.Characteristic
       if (this._service.testCharacteristic(Characteristic)) {
         this._characteristic = this._service.getCharacteristic(Characteristic)
-        this._characteristic.props = new Characteristic().props
       } else {
         this._characteristic = this._service.addCharacteristic(Characteristic)
       }
       if (params.props != null) {
+        if (this._characteristic.value < params.props.minValue) {
+          this._characteristic.updateValue(params.props.minValue)
+        }
         this._characteristic.setProps(params.props)
       }
       if (this._characteristic.props.unit != null) {
@@ -147,10 +149,7 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
       )
       // Check that we are the only listener
       if (this._characteristic.listenerCount('set') > 1) {
-        this.warn(
-          '%s: %d listeners', this.displayName,
-          this._characteristic.listenerCount('set')
-        )
+        this.warn('%d listeners', this._characteristic.listenerCount('set'))
       }
     }
     if (params.unit != null) {
@@ -173,7 +172,7 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
     * Removes the associated HomeKit characteristic.
     */
   _destroy () {
-    this.debug('destroy %s (%s)', this._key, this.displayName)
+    this.debug('destroy %s', this._key)
     this.removeAllListeners()
     if (this._characteristic != null) {
       this._service.removeCharacteristic(this._characteristic)
@@ -189,11 +188,11 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
   }
 
   get _canRead () {
-    return this._hasPerm(this.Characteristic.Perms.READ)
+    return this._hasPerm(this.Characteristic.Perms.PAIRED_READ)
   }
 
   get _canWrite () {
-    return this._hasPerm(this.Characteristic.Perms.WRITE)
+    return this._hasPerm(this.Characteristic.Perms.PAIRED_WRITE)
   }
 
   get _canNotify () {
@@ -240,6 +239,10 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
       : this._characteristic.displayName
   }
 
+  get _namePrefix () {
+    return this._serviceDelegate._namePrefix + this.displayName + ': '
+  }
+
   validate (value) {
     let s = ''
     if (this._characteristic != null) {
@@ -293,20 +296,11 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
 
     // Issue info message that Characteristic value is updated by the plugin.
     if (this._notifyOnly) {
-      this._log(
-        '%s: %s%s', this.displayName,
-        ['Single Press', 'Double Press', 'Long Press'][value], s
-      )
+      this._log('%s%s', ['Single Press', 'Double Press', 'Long Press'][value], s)
     } else if (this.value == null) {
-      this._log(
-        'set %s to %j%s%s', this.displayName,
-        value, this._unit, s
-      )
+      this._log('set to %j%s%s', value, this._unit, s)
     } else {
-      this._log(
-        'set %s from %j%s to %j%s%s', this.displayName,
-        this.value, this._unit, value, this._unit, s
-      )
+      this._log('set to %j%s%s (from %j%s)', value, this._unit, s, this.value, this._unit)
     }
 
     // Update persisted value in ~/.homebridge/accessories/cachedAccessories.
@@ -344,10 +338,7 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
     let value = this.value
     const timeout = setTimeout(() => {
       timedOut = true
-      this.warn(
-        'get %s: timed out - return previous value %j%s',
-        this.displayName, this.value, this._unit
-      )
+      this.warn('get: timed out - return previous value %j%s', this.value, this._unit)
       callback(null, this.value)
     }, this._timeout)
     try {
@@ -358,12 +349,10 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
     clearTimeout(timeout)
 
     if (timedOut) {
-      this._log(
-        'get %s: ignore %j%s - timed out', this.displayName, value, this._unit
-      )
+      this._log('get: ignore %j%s - timed out', value, this._unit)
     } else {
       // Return value to HomeKit.
-      this._log('get %s: return %j%s', this.displayName, value, this._unit)
+      this._log('get: return %j%s', value, this._unit)
       callback(null, value)
     }
 
@@ -383,12 +372,9 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
 
     // Issue info message that Characteristic value was updated from HomeKit.
     if (this._writeOnly || this.value == null) {
-      this._log('%s changed to %j%s', this.displayName, value, this._unit)
+      this._log('changed to %j%s', value, this._unit)
     } else if (value !== this.value) {
-      this._log(
-        '%s changed from %j%s to %j%s', this.displayName,
-        this.value, this._unit, value, this._unit
-      )
+      this._log('changed to %j%s (from %j%s)', value, this._unit, this.value, this._unit)
     }
 
     // Check for actual change.
@@ -408,14 +394,14 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
       let timedOut = false
       const timeout = setTimeout(() => {
         timedOut = true
-        this.warn('set %s: timed out', this.displayName)
+        this.warn('set: timed out')
         callback(new Error('timed out'))
       }, this._timeout)
       try {
         result = await this._setter(value)
       } catch (error) {
         clearTimeout(timeout)
-        this.warn('set %s: %s', this.displayName, error)
+        this.warn('set: %s', error)
         if (!timedOut) {
           callback(error)
         }

package/lib/Colour.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/Colour.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2016-2022 Erik Baauw. All rights reserved.
+// Copyright © 2016-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 

package/lib/CommandLineParser.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/CommandLineParser.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 // TODO:
 // - Change parameters to (params, callback) with:

package/lib/CommandLineTool.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/CommandLineUtility.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2018-2022 Erik Baauw. All rights reserved.
+// Copyright © 2018-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 

package/lib/CustomHomeKitTypes.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/CustomeHomeKitTypes.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 const regExps = {
   uuid: /^[0-9A-F]{8}-[0-9A-F]{4}-[1-5][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/,

package/lib/Delegate.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/Delegate.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
@@ -93,6 +93,29 @@ class Delegate extends events.EventEmitter {
     */
   get Services () { return this._platform.Services }
 
+  /** Current log level.
+    *
+    * The log level determines what type of messages are printed:
+    *
+    * 0. Print error and warning messages.
+    * 1. Print error, warning, and log messages.
+    * 2. Print error, warning, log, and debug messages.
+    * 3. Print error, warning, log, debug, and verbose debug messages.
+    * 3. Print error, warning, log, debug, verbose debug, and very verbose
+    * debug messages.
+    *
+    * Note that debug messages (level 2, 3 and 4) are only printed when
+    * Homebridge was started with the `-D` or `--debug` command line option.
+    *
+    * The log level defaults at 2.
+    *
+    * @type {!integer}
+    * @readonly
+    */
+  get logLevel () {
+    return 2
+  }
+
   /** The name used to prefix log and error messages.
     * @type {string}
     */
@@ -108,7 +131,13 @@ class Delegate extends events.EventEmitter {
       throw new RangeError(`${name}: invalid name`)
     }
     this._name = name
-    this._namePrefix = this._name == null ? '' : name + ': '
+  }
+
+  /** The name prefix for log messages.
+    *  @type {string}
+    */
+  get _namePrefix () {
+    return this._name == null ? '' : this._name + ': '
   }
 
   /** Reference to the corresponding platform plugin instance.
@@ -121,37 +150,6 @@ class Delegate extends events.EventEmitter {
     return this._platform
   }
 
-  /** Name of the (final) class of this instance.
-    * @type {!string}
-    * @readonly
-    */
-  get className () {
-    return this.constructor.name
-  }
-
-  /** Current log level.
-    *
-    * The log level determines what type of messages are printed:
-    *
-    * 0. Print error and warning messages.
-    * 1. Print error, warning, and log messages.
-    * 2. Print error, warning, log, and debug messages.
-    * 3. Print error, warning, log, debug, and verbose debug messages.
-    * 3. Print error, warning, log, debug, verbose debug, and very verbose
-    * debug messages.
-    *
-    * Note that debug messages (level 2, 3 and 4) are only printed when
-    * Homebridge was started with the `-D` or `--debug` command line option.
-    *
-    * The log level defaults at 2.
-    *
-    * @type {!integer}
-    * @readonly
-    */
-  get logLevel () {
-    return 2
-  }
-
   /** Print a debug message to Homebridge standard output.
     * <br>The message is printed only, when the current log level >= 2 and when
     * Homebridge was started with the `-D` or `--debug` command line option.