homebridge-lib 6.0.2 → 6.1.0

package/lib/OptionParser.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/OptionParser.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2018-2022 Erik Baauw. All rights reserved.
+// Copyright © 2018-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
@@ -769,6 +769,31 @@ class OptionParser extends events.EventEmitter {
     return this
   }
 
+  /** Defines a key that takes an number value,
+    * optionally clamped between min and max.
+    *
+    * @param {!string} key - The key.
+    * @param {?number} min - Minimum value returned.
+    * @param {?number} max - Maximum value returned.
+    * @return {OptionParser} this - For chaining.
+    * @throws {TypeError} When key is not a string.
+    * @throws {RangeError} When key is empty string.
+    * @throws {SyntaxError} On duplicate key.
+    */
+  numberKey (key, min, max) {
+    key = this._toKey(key)
+    min = min == null ? -Infinity : OptionParser.toNumber('min', min)
+    max = max == null ? Infinity : OptionParser.toNumber('max', max)
+    if (max < min) {
+      throw newRangeError('max: smaller than min')
+    }
+
+    this._callbacks[key] = (value) => {
+      this._object[key] = OptionParser.toNumber(key, value, min, max, this._userInput)
+    }
+    return this
+  }
+
   /** Defines a key that takes an object as value.
     *
     * @param {!string} key - The key.
@@ -832,7 +857,7 @@ class OptionParser extends events.EventEmitter {
     * @throws {TypeError} When option has wrong type.
     * @throws {RangeError} When option has wrong value.
     * @throws {SyntaxError} Unknown option.
-    * @throws {UserError} On error, when value was input by user.
+    * @throws {UserInputError} On error, when value was input by user.
     */
   parse (options) {
     options = OptionParser.toObject('options', options)

package/lib/Platform.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/Platform.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
@@ -139,7 +139,7 @@ class Platform extends homebridgeLib.Delegate {
     this._log = log
     this._configJson = configJson
     this._homebridge = homebridge
-    this._myContext = context[this.className]
+    this._myContext = context[this.constructor.name]
     this._platformName = this._myContext.platformName
     this._pluginName = this._myContext.packageJson.name
     this._pluginVersion = this._myContext.packageJson.version
@@ -460,8 +460,7 @@ class Platform extends homebridgeLib.Delegate {
 
   // Get or create accessory.
   _getAccessory (delegate, params) {
-    const className = delegate.className
-    const version = this._pluginVersion
+    const className = delegate.constructor.name
     const id = params.id
     const name = params.name
     let accessory = this._accessories[id]
@@ -473,11 +472,6 @@ class Platform extends homebridgeLib.Delegate {
       this._accessories[id] = accessory
       accessory.displayName = name
       accessory.context = {
-        className,
-        version,
-        id,
-        name,
-        logLevel: this.logLevel,
         context: {}
       }
       delegate.once('initialised', () => {
@@ -507,14 +501,6 @@ class Platform extends homebridgeLib.Delegate {
           delegate.emit('exposeError', error)
         }
       })
-    } else {
-      // Allow for plugin to change delegate class, version, and name.
-      accessory.context.className = className
-      accessory.context.version = version
-      accessory.context.name = name
-      if (accessory.context.logLevel == null) {
-        accessory.context.logLevel = this.logLevel
-      }
     }
     this._accessoryDelegates[id] = delegate
     return accessory

package/lib/PropertyDelegate.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/PropertyDelegate.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
@@ -22,8 +22,7 @@ class PropertyDelegate extends homebridgeLib.Delegate {
   /** Instantiate a property delegate.
     *
     * Note that instances are normally created by invoking
-    * {@link AccessoryDelegate#addPropertyDelegate addPropertyDelegate()} or
-    * {@link ServiceDelegate#addPropertyDelegate addPropertyDelegate()}.
+    * {@link AccessoryDelegate#addPropertyDelegate addPropertyDelegate()}.
     * @param {!AccessoryDelegate|ServiceDelegate} delegate - Reference to the
     * delegate of the corresponding HomeKit accessory or service.
     * @param {!object} params - Parameters of the property delegate.
@@ -41,10 +40,7 @@ class PropertyDelegate extends homebridgeLib.Delegate {
     * optional parameter is not applicable.
     */
   constructor (parent, params = {}) {
-    if (!(
-      parent instanceof homebridgeLib.AccessoryDelegate ||
-      parent instanceof homebridgeLib.ServiceDelegate
-    )) {
+    if (!(parent instanceof homebridgeLib.AccessoryDelegate)) {
       throw new TypeError('parent: not an AccessoryDelegate')
     }
     super(parent.platform, parent.name + ': ' + params.key)
@@ -61,8 +57,6 @@ class PropertyDelegate extends homebridgeLib.Delegate {
     if (this.value == null && params.value != null) {
       this.value = params.value
     }
-
-    this.vdebug('created')
   }
 
   /** Destroy the propery delegate.
@@ -92,6 +86,10 @@ class PropertyDelegate extends homebridgeLib.Delegate {
     return this._parent.logLevel
   }
 
+  get _namePrefix () {
+    return this._parent._namePrefix + this._key + ': '
+  }
+
   validate (value) {
     // Todo: check value against type.
     return { value, s: '' }
@@ -116,8 +114,7 @@ class PropertyDelegate extends homebridgeLib.Delegate {
       this._log('set to %j%s%s', value, this._unit, s)
     } else {
       this._log(
-        'set to %j%s%s (from %j%s)', value, this._unit, s,
-        this.value, this._unit
+        'set to %j%s%s (from %j%s)', value, this._unit, s, this.value, this._unit
       )
     }
 

package/lib/ServiceDelegate/AccessoryInformation.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/ServiceDelegate/AccessoryInformation.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/ServiceDelegate/Battery.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/ServiceDelegate/Battery.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/ServiceDelegate/Dummy.js

@@ -1,7 +1,7 @@
 // homebridge-lib/lib/ServiceDelegate/Dummy.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/ServiceDelegate/History/Consumption.js

@@ -1,20 +1,13 @@
 // homebridge-lib/lib/ServiceDelegate/History/Consumption.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
-//
-// The logic for handling Eve history was copied from Simone Tisa's
-// fakagato-history repository, copyright © 2017 simont77.
-// See https://github.com/simont77/fakegato-history.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
 const homebridgeLib = require('../../../index')
-const util = require('util')
 
-const { ServiceDelegate } = homebridgeLib
-const { History } = ServiceDelegate
-const { swap16, swap32, numToHex } = History
+const { History } = homebridgeLib.ServiceDelegate
 
 /** Class for an Eve Energy _History_ service delegate.
   *
@@ -53,9 +46,9 @@ class Consumption extends History {
     * @param {?CharacteristicDelegate} params.powerDelegate - A reference to the
     * delegate of the associated `Characteristics.eve.CurrentConsumption`
     * characteristic.
-    * @param {!CharacteristicDelegate} params.onDelegate - A reference to the
+    * @param {?CharacteristicDelegate} params.onDelegate - A reference to the
     * delegate of the associated `Characteristics.hap.On` characteristic.
-    * @param {!CharacteristicDelegate} params.lastActivationDelegate - A
+    * @param {?CharacteristicDelegate} params.lastActivationDelegate - A
     * reference to the delegate of the associated
     * `Characteristics.eve.LastActivation` characteristic.
     */
@@ -85,66 +78,55 @@ class Consumption extends History {
     this._consumptionDelegate = params.consumptionDelegate
     this._powerDelegate = params.powerDelegate
 
-    this._entry = { time: 0, power: 0 }
+    this.entry = { p: 0 }
     if (params.onDelegate != null) {
-      this._entry.on = params.onDelegate.value ? 1 : 0
+      this.entry.o = params.onDelegate.value ? 1 : 0
       params.onDelegate.on('didSet', (value) => {
-        const now = Math.round(new Date().valueOf() / 1000)
+        const now = History.now()
         if (params.lastActivationDelegate != null) {
-          params.lastActivationDelegate.value = now - this._h.initialTime
+          params.lastActivationDelegate.value = this.lastActivationValue(now)
         }
-        this._entry.on = value ? 1 : 0
-        const power = this._entry.power
-        this._entry.power = null
-        super._addEntry(now)
-        this._entry.power = power
+        this.entry.o = value ? 1 : 0
+        super.addEntry({ time: now, o: this.entry.o })
       })
     }
   }
 
-  _addEntry () {
-    const now = Math.round(new Date().valueOf() / 1000)
+  addEntry (entry) {
     // Sensor deliveres totalConsumption, optionally compute currentConsumption
     if (this._consumption != null && this._time != null) {
       const delta = this._consumptionDelegate.value - this._consumption // kWh
-      const period = now - this._time // s
+      const period = entry.time - this._time // s
       const power = 1000 * 3600 * delta / period // W
       if (this._powerDelegate != null) {
         this._powerDelegate.value = Math.round(power) // W
       }
-      this._entry.power = Math.round(power * 10) // 0.1 W * 10 min
-      super._addEntry(now)
+      entry.p = Math.round(power * 10) // 0.1 W * 10 min
     }
+    super.addEntry(entry)
     this._consumption = this._consumptionDelegate.value
-    this._time = now
+    this._time = entry.time
   }
 
-  get _fingerPrint () { return '02 0702 0E01' }
+  get fingerPrint () { return '02 0702 0E01' }
 
-  _entryStream (entry) {
-    if (entry.on == null) {
-      return util.format(
-        '|0c %s %s 01 %s',
-        numToHex(swap32(this._h.currentEntry), 8),
-        numToHex(swap32(entry.time - this._h.initialTime), 8),
-        numToHex(swap16(entry.power), 4)
-      )
+  entryToBuffer (entry) {
+    const buffer = Buffer.alloc(4)
+    let o = 0
+    if (entry.o == null) {
+      buffer.writeUInt8(0x01, o); o += 1
+      buffer.writeUInt16LE(entry.p, o); o += 2
+      return buffer.slice(0, o)
     }
-    if (entry.power == null) {
-      return util.format(
-        '|0b %s %s 02 %s',
-        numToHex(swap32(this._h.currentEntry), 8),
-        numToHex(swap32(entry.time - this._h.initialTime), 8),
-        numToHex(entry.on, 2)
-      )
+    if (entry.p == null) {
+      buffer.writeUInt8(0x02, o); o += 1
+      buffer.writeUInt8(entry.o, o); o += 1
+      return buffer.slice(0, o)
     }
-    return util.format(
-      '|0d %s %s 03 %s %s',
-      numToHex(swap32(this._h.currentEntry), 8),
-      numToHex(swap32(entry.time - this._h.initialTime), 8),
-      numToHex(swap16(entry.power), 4),
-      numToHex(entry.on, 2)
-    )
+    buffer.writeUInt8(0x03, o); o += 1
+    buffer.writeUInt16LE(entry.p, o); o += 2
+    buffer.writeUInt8(entry.o, o); o += 1
+    return buffer.slice(0, o)
   }
 }
 

package/lib/ServiceDelegate/History/Contact.js

@@ -1,20 +1,13 @@
 // homebridge-lib/lib/ServiceDelegate/History/Contact.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
-//
-// The logic for handling Eve history was copied from Simone Tisa's
-// fakagato-history repository, copyright © 2017 simont77.
-// See https://github.com/simont77/fakegato-history.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
 const homebridgeLib = require('../../../index')
-const util = require('util')
 
-const { ServiceDelegate } = homebridgeLib
-const { History } = ServiceDelegate
-const { swap32, numToHex } = History
+const { History } = homebridgeLib.ServiceDelegate
 
 /** Class for an Eve Door _History_ service delegate.
   *
@@ -64,13 +57,13 @@ class Contact extends History {
     if (!(params.lastActivationDelegate instanceof homebridgeLib.CharacteristicDelegate)) {
       throw new TypeError('params.lastActivationDelegate: not a CharacteristicDelegate')
     }
-    this._entry = { time: 0, status: params.contactDelegate.value }
+    this.entry = { c: params.contactDelegate.value ? 1 : 0 }
     params.contactDelegate.on('didSet', (value) => {
-      const now = Math.round(new Date().valueOf() / 1000)
+      const now = History.now()
       params.timesOpenedDelegate.value += value
-      params.lastActivationDelegate.value = now - this._h.initialTime
-      this._entry.status = value
-      this._addEntry(now)
+      params.lastActivationDelegate.value = this.lastActivationValue(now)
+      this.entry.c = value ? 1 : 0
+      this.addEntry({ time: now, c: this.entry.c })
     })
     this.addCharacteristicDelegate({
       key: 'resetTotal',
@@ -81,15 +74,14 @@ class Contact extends History {
     })
   }
 
-  get _fingerPrint () { return '01 0601' }
+  get fingerPrint () { return '01 0601' }
 
-  _entryStream (entry) {
-    return util.format(
-      '|0b %s %s 01 %s',
-      numToHex(swap32(this._h.currentEntry), 8),
-      numToHex(swap32(entry.time - this._h.initialTime), 8),
-      numToHex(entry.status, 2)
-    )
+  entryToBuffer (entry) {
+    const buffer = Buffer.alloc(2)
+    let o = 0
+    buffer.writeUInt8(0x01, o); o += 1
+    buffer.writeUInt8(entry.c, o); o += 1
+    return buffer.slice(0, o)
   }
 }
 

package/lib/ServiceDelegate/History/Light.js

@@ -1,18 +1,13 @@
 // homebridge-lib/lib/ServiceDelegate/History/On.js
 //
 // Library for Homebridge plugins.
-// Copyright © 2017-2022 Erik Baauw. All rights reserved.
-//
-// The logic for handling Eve history was copied from Simone Tisa's
-// fakagato-history repository, copyright © 2017 simont77.
-// See https://github.com/simont77/fakegato-history.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
 
 'use strict'
 
 const homebridgeLib = require('../../../index')
 
-const { ServiceDelegate } = homebridgeLib
-const { History } = ServiceDelegate
+const { History } = homebridgeLib.ServiceDelegate
 
 /** Class for an Eve Light Strip _History_ service delegate.
   *
@@ -28,7 +23,12 @@ const { History } = ServiceDelegate
   * `historyEntries` | `Characteristics.eve.HistoryEntries`
   *
   * This delegate creates the history from the associated
-  * `Characteristics.hap.On` characteristic.
+  * `Characteristics.hap.On` characteristic.  It updates the
+  * values of the associated `Characteristics.eve.LastActivation`
+  * characteristic.
+  * Note that the Eve Light Strip doesn't actually provide history entries;
+  * the _History_ service is used only to provide a reference time for
+  * last `LastActivation`.
   * @extends ServiceDelegate.History
   * @memberof ServiceDelegate.History
   */
@@ -54,28 +54,20 @@ class Light extends History {
     if (!(params.lastActivationDelegate instanceof homebridgeLib.CharacteristicDelegate)) {
       throw new TypeError('params.lastActivationDelegate: not a CharacteristicDelegate')
     }
-    if (
-      params.temperatureDelegate != null &&
-      !(params.temperatureDelegate instanceof homebridgeLib.CharacteristicDelegate)
-    ) {
-      throw new TypeError('params.temperatureDelegate: not a CharacteristicDelegate')
-    }
-    this._entry = {
-      time: 0
-    }
+    this.entry = { }
     params.onDelegate.on('didSet', (value) => {
-      const now = Math.round(new Date().valueOf() / 1000)
+      const now = History.now()
       if (params.lastActivationDelegate != null) {
-        params.lastActivationDelegate.value = now - this._h.initialTime
+        params.lastActivationDelegate.value = this.lastActivationValue(now)
       }
-      this._addEntry(now)
+      this.addEntry({ time: now })
     })
   }
 
-  get _fingerPrint () { return '00' }
+  get fingerPrint () { return '00' }
 
-  _entryStream (entry) {
-    return ''
+  entryToBuffer (entry) {
+    return Buffer.alloc(0)
   }
 }
 

package/lib/ServiceDelegate/History/LightLevel.js

@@ -0,0 +1,113 @@
+// homebridge-lib/lib/ServiceDelegate/History/LightLevel.js
+//
+// Library for Homebridge plugins.
+// Copyright © 2017-2023 Erik Baauw. All rights reserved.
+
+'use strict'
+
+const homebridgeLib = require('../../../index')
+
+const { History } = homebridgeLib.ServiceDelegate
+
+/** Class for an Eve Motion _History_ service delegate.
+  *
+  * This delegate sets up a `Services.eve.History` HomeKit service
+  * with keys for the following HomeKit characteristics:
+  *
+  * key              | Characteristic
+  * ---------------- | ----------------------------------
+  * `name`           | `Characteristics.hap.Name`
+  * `historyRequest` | `Characteristics.eve.HistoryRequest`
+  * `setTime`        | `Characteristics.eve.SetTime`
+  * `historyStatus`  | `Characteristics.eve.HistoryStatus`
+  * `historyEntries` | `Characteristics.eve.HistoryEntries`
+  * `resetTotal`     | `Characteristics.eve.ResetTotal`
+  *
+  * This delegate creates the history from the associated
+  * `Characteristics.hap.MotionDetected` characteristic.  It updates the
+  * value of the associated `Characteristics.eve.LastActivation` characteristic.
+  * Optionally, this delegate also mainatins history for
+  * `Characteristics.hap.CurrentAmbientLightLevel`,
+  * `Characteristics.hap.CurrentTemperature`, and
+  * `Characteristics.hap.CurrentRelativeHumidity`.
+  * @extends ServiceDelegate.History
+  * @memberof ServiceDelegate.History
+  */
+class LightLevel extends History {
+  /** Create a new instance of an Eve Motion _History_ service delegate.
+    * @param {!AccessoryDelegate} accessoryDelegate - The delegate of the
+    * corresponding HomeKit accessory.
+    * @param {!object} params - The parameters for the
+    * _History_ HomeKit service.
+    * @param {!CharacteristicDelegate} params.lightLevelDelegate - A reference
+    * to the delegate of the associated
+    * `Characteristics.hap.CurrentAmbientLightLevel` characteristic.
+    * For PIR sensors (like the Hue motion sensor) that report light level in
+    * addition to motion.
+    * @param {?CharacteristicDelegate} params.temperatureDelegate - A reference
+    * to the delegate of the associated `Characteristics.hap.CurrentTemperature`
+    * characteristic.
+    * For PIR sensors (like the Hue motion sensor) that report temperature in
+    * addition to motion and light level.
+    * @param {?CharacteristicDelegate} params.humidityDelegate - A reference
+    * to the delegate of the associated `Characteristics.hap.CurrentRelativeHumidity`
+    * characteristic.
+    * For PIR sensors (like the OWON PIR313 sensor) that report humidity in
+    * addition to motion, light level, and temperature.
+    */
+  constructor (accessoryDelegate, params) {
+    super(accessoryDelegate, params)
+    if (!(params.lightLevelDelegate instanceof homebridgeLib.CharacteristicDelegate)) {
+      throw new TypeError('params.lightLevelDelegate: not a CharacteristicDelegate')
+    }
+    this.entry = { l: params.lightLevelDelegate.value }
+    params.lightLevelDelegate.on('didSet', (value) => {
+      this.entry.l = value
+    })
+    if (params.temperatureDelegate != null) {
+      if (!(params.temperatureDelegate instanceof homebridgeLib.CharacteristicDelegate)) {
+        throw new TypeError('params.temperatureDelegate: not a CharacteristicDelegate')
+      }
+      this.entry.t = params.temperatureDelegate.value
+      params.temperatureDelegate.on('didSet', (value) => {
+        this.entry.t = value
+      })
+      if (params.humidityDelegate != null) {
+        if (!(params.humidityDelegate instanceof homebridgeLib.CharacteristicDelegate)) {
+          throw new TypeError('params.humidityDelegate: not a CharacteristicDelegate')
+        }
+        this.entry.h = params.humidityDelegate.value
+        params.humidityDelegate.on('didSet', (value) => {
+          this.entry.h = value
+        })
+      }
+    }
+  }
+
+  get fingerPrint () {
+    return '03 3002 0102 0202'
+  }
+
+  entryToBuffer (entry) {
+    const buffer = Buffer.alloc(6)
+    let o = 0
+    if (entry.t == null) {
+      buffer.writeUInt8(0x01, o); o += 1
+      buffer.writeUInt16LE(entry.l, o); o += 2
+      return buffer.slice(0, o)
+    }
+    if (entry.h == null) {
+      buffer.writeUInt8(0x03, o); o += 1
+      buffer.writeUInt16LE(entry.l, o); o += 2
+      buffer.writeUInt16LE(entry.t * 100, o); o += 2
+      return buffer.slice(0, o)
+    }
+    buffer.writeUInt8(0x07, o); o += 1
+    buffer.writeUInt16LE(entry.l, o); o += 2
+    buffer.writeUInt16LE(entry.t * 100, o); o += 2
+    buffer.writeUInt16LE(entry.h * 100, o); o += 2
+    return buffer.slice(0, o)
+  }
+}
+
+module.exports = LightLevel