homebridge-lib 5.1.24-4 → 5.2.1

package/index.js

@@ -175,6 +175,13 @@ class homebridgeLib {
     */
   static get Platform () { return require('./lib/Platform') }
 
+  /** Delegate of a property of a HomeKit accessory or service.
+    * <br>See {@link PropertyDelegate}.
+    * @type {Class}
+    * @memberof module:homebridgeLib
+    */
+  static get PropertyDelegate () { return require('./lib/PropertyDelegate') }
+
   /** Delegate of a HomeKit service.
     * <br>See {@link ServiceDelegate}.
     * @type {Class}

package/lib/AccessoryDelegate.js

@@ -7,7 +7,6 @@
 
 const homebridgeLib = require('../index')
 
-const maxLogLevel = 4
 const startsWithUuid = /^[0-9A-F]{8}-[0-9A-F]{4}-[1-5][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}/
 
 /** Delegate of a HomeKit accessory.
@@ -35,9 +34,6 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     * @param {!string} params.firmware - The accessory firmware revision.
     * @param {?string} params.hardware - The accessory hardware revision.
     * @param {?string} params.software - The accessory software revision.
-    * @param {integer} params.logLevel - The log level for the accessory.
-    * @param {?boolean} [params.inheritLogLevel] - Inherit `logLevel` from
-    * `platform` instead of maintaining it oneself.
     */
   constructor (platform, params = {}) {
     if (params.name == null) {
@@ -53,18 +49,22 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
 
     // Link or create associated PlatformAccessory.
     this._accessory = this._platform._getAccessory(this, params)
-    this._context = this._accessory.context
 
     if (params.logLevel != null) {
-      this._context.logLevel = Math.max(0, Math.min(params.logLevel, maxLogLevel))
-    } else if (params.inheritLogLevel != null) {
-      if (params.inheritLogLevel) {
-        Object.defineProperty(this, 'logLevel', {
-          get () { return platform.logLevel }
-        })
-      }
-      delete params.inheritLogLevel
+      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 = {}
 
     // Create delegate for AccessoryInformation service.
     this._serviceDelegates = {}
@@ -138,16 +138,88 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     }
   }
 
+  /** Creates a new {@link PropertyDelegate} instance, for a property of the
+    * associated HomeKit accessory.
+    *
+    * The property value is accessed through
+    * {@link AccessoryDelegate#values values}.
+    * The delegate is returned, but can also be accessed through
+    * {@link AccessoryDelegate#propertyDelegate propertyDelegate()}.
+    * @param {!object} params - Parameters of the property delegate.
+    * @param {!string} params.key - The key for the property delegate.<br>
+    * Needs to be unique with parent delegate.
+    // * @param {!type} params.type - The type of the property value.
+    * @param {?*} params.value - The initial value of the property.<br>
+    * Only used when the property delegate is created for the first time.
+    * Otherwise, the value is restored from persistent storage.
+    * @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.
+    * @throws {SyntaxError} When a mandatory parameter is missing or an
+    * optional parameter is not applicable.
+    */
+  addPropertyDelegate (params = {}) {
+    if (typeof params.key !== 'string') {
+      throw new TypeError(`params.key: ${params.key}: invalid key`)
+    }
+    if (params.key === '') {
+      throw new RangeError(`params.key: ${params.key}: invalid key`)
+    }
+    const key = params.key
+    if (this.values[key] !== undefined) {
+      throw new SyntaxError(`${key}: duplicate key`)
+    }
+
+    const delegate = new homebridgeLib.PropertyDelegate(this, params)
+    this._propertyDelegates[key] = delegate
+
+    // Create shortcut for characteristic value.
+    Object.defineProperty(this.values, key, {
+      configurable: true, // make sure we can delete it again
+      writeable: true,
+      get () { return delegate.value },
+      set (value) { delegate.value = value }
+    })
+
+    return delegate
+  }
+
+  removePropertyDelegate (key) {
+    if (this._accessoryInformationDelegate.values[key] != null) {
+      throw new RangeError('%s: invalid key')
+    }
+    delete this.values[key]
+    const delegate = this._propertyDelegates[key]
+    delegate._destroy()
+    delete this._propertyDelegates[key]
+    delete this._context[key]
+  }
+
+  /** Returns the property delegate correspondig to the property key.
+    * @param {!string} key - The key for the property.
+    * returns {PropertyDelegate}
+    */
+  propertyDelegate (key) {
+    return this._propertyDelegates[key]
+  }
+
   /** Values of the HomeKit characteristics for the `AccessoryInformation` service.
     *
-    * Contains the key of each characteristic in
+    * Contains the key of each property and of each characteristic in
     * {@link ServiceDelegate.AccessoryInformation AccessoryInformation}.
     * When the value is written, the value of the corresponding HomeKit
     * characteristic is updated.
     * @type {object}
     */
   get values () {
-    return this._accessoryInformationDelegate._values
+    return this._values
   }
 
   /** Enable `heartbeat` events for this accessory delegate.
@@ -192,16 +264,7 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     * @type {!integer}
     */
   get logLevel () {
-    return this._context.logLevel
-  }
-
-  set logLevel (value) {
-    const oldLogLevel = this._context.logLevel
-    this._context.logLevel = Math.max(0, Math.min(value, maxLogLevel))
-    this._platform._message(
-      'log', 2, this.name + ': ',
-      'set Log Level from %d to %d', oldLogLevel, this.logLevel
-    )
+    return this.platform.logLevel
   }
 
   /** Inherit `logLevel` from another accessory delegate.
@@ -220,6 +283,19 @@ class AccessoryDelegate extends homebridgeLib.Delegate {
     })
   }
 
+  /** Manage `logLevel` from characteristic delegate.
+    * @param {CharacteristicDelegate} delegate - The delegate of the `logLevel`
+    * characteristic.
+    */
+  manageLogLevel (delegate) {
+    if (!(delegate instanceof homebridgeLib.CharacteristicDelegate)) {
+      throw new TypeError('delegate: not an CharacteristicDelegate')
+    }
+    Object.defineProperty(this, 'logLevel', {
+      get () { return delegate.value }
+    })
+  }
+
   // Called by homebridge when Identify is selected.
   _identify () {
     this.emit('identify')

package/lib/AdaptiveLighting.js

@@ -5,6 +5,8 @@
 
 'use strict'
 
+const homebridgeLib = require('../index')
+
 /* global BigInt */
 
 const epoch = (new Date('2001-01-01T00:00:00Z')).valueOf()
@@ -170,8 +172,12 @@ class AdaptiveLighting {
     * @param {integer} ct - The IID of the _Color Temperature_ characteristic.
     */
   constructor (bri, ct) {
-    this.bri = bri
-    this.ct = ct
+    this.bri = bri instanceof homebridgeLib.CharacteristicDelegate
+      ? bri._characteristic.iid
+      : bri
+    this.ct = ct instanceof homebridgeLib.CharacteristicDelegate
+      ? ct._characteristic.iid
+      : ct
     this._active = false
   }
 

package/lib/CharacteristicDelegate.js

@@ -200,6 +200,10 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
     return this._hasPerm(this.Characteristic.Perms.NOTIFY)
   }
 
+  get _writeResponse () {
+    return this._hasPerm(this.Characteristic.Perms.WRITE_RESPONSE)
+  }
+
   get _writeOnly () {
     return this._canWrite && !this._canRead && !this._canNotifiy
   }
@@ -375,6 +379,7 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
   // Called when characteristic is updated from HomeKit.
   async _onSet (v, callback) {
     const { value } = this.validate(v)
+    let result
 
     // Issue info message that Characteristic value was updated from HomeKit.
     if (this._writeOnly || this.value == null) {
@@ -407,7 +412,7 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
         callback(new Error('timed out'))
       }, this._timeout)
       try {
-        await this._setter(value)
+        result = await this._setter(value)
       } catch (error) {
         clearTimeout(timeout)
         this.error(error)
@@ -423,7 +428,11 @@ class CharacteristicDelegate extends homebridgeLib.Delegate {
     }
 
     // Return status to HomeKit.
-    callback()
+    if (this._writeResponse) {
+      callback(null, result)
+    } else {
+      callback()
+    }
 
     // Update persisted value in ~/.homebridge/accessories/cachedAccessories.
     this._serviceDelegate._context[this._key] = value

package/lib/EveHomeKitTypes.js

@@ -188,10 +188,11 @@ class EveHomeKitTypes extends homebridgeLib.CustomHomeKitTypes {
     }, 'Current Consumption')
 
     this.createCharacteristicClass('AirPressure', uuid('10F'), {
-      format: this.Formats.UINT16,
+      format: this.Formats.FLOAT,
       unit: 'hPa',
       minValue: 700,
       maxValue: 1100,
+      minStep: 0.1,
       perms: [this.Perms.READ, this.Perms.NOTIFY]
     }, 'Air Pressure')
 
@@ -284,6 +285,11 @@ class EveHomeKitTypes extends homebridgeLib.CustomHomeKitTypes {
       perms: [this.Perms.READ, this.Perms.NOTIFY, this.Perms.WRITE],
       adminOnlyAccess: [this.Access.WRITE]
     })
+    this.Characteristics.Duration.VALID_VALUES = [
+      5, 10, 20, 30,
+      1 * 60, 2 * 60, 3 * 60, 5 * 60, 10 * 60, 20 * 60, 30 * 60,
+      1 * 3600, 2 * 3600, 3 * 3600, 5 * 3600, 10 * 3600, 12 * 3600, 15 * 3600
+    ]
 
     this.createCharacteristicClass('ValvePosition', uuid('12E'), {
       format: this.Formats.UINT8,

package/lib/MyHomeKitTypes.js

@@ -589,7 +589,7 @@ class MyHomeKitTypes extends homebridgeLib.CustomHomeKitTypes {
     this.createCharacteristicClass('LogLevel', uuid('065'), {
       format: this.Formats.UINT8,
       minValue: 0,
-      maxValue: 3,
+      maxValue: 3, // 4 for homebridge-zp
       minStep: 1, // Force Down|Up control in Eve
       perms: [this.Perms.READ, this.Perms.NOTIFY, this.Perms.WRITE],
       adminOnlyAccess: [this.Access.WRITE]
@@ -598,6 +598,7 @@ class MyHomeKitTypes extends homebridgeLib.CustomHomeKitTypes {
     this.Characteristics.LogLevel.LOG = 1
     this.Characteristics.LogLevel.DEBUG = 2
     this.Characteristics.LogLevel.VDEBUG = 3
+    this.Characteristics.LogLevel.VVDEBUG = 4
 
     this.createCharacteristicClass('Repeat', uuid('066'), {
       format: this.Formats.UINT8,

package/lib/Platform.js

@@ -27,8 +27,6 @@ const context = {
   checkInterval: 7 * 24 * 3600
 }
 
-const globalKey = context.libName // + '@' + context.libVersion
-
 /** Homebridge dynamic platform plugin.
   *
   * `Platform` provides the following features to a platform plugin:
@@ -59,6 +57,8 @@ class Platform extends homebridgeLib.Delegate {
   static loadPlatform (homebridge, packageJson, platformName, Platform) {
     if (context.homebridge == null) {
       context.homebridge = homebridge
+      context.packageJson = packageJson
+      context.platformName = platformName
       context.homebridgeVersion = homebridge.serverVersion
       context.PlatformAccessory = homebridge.platformAccessory
       const hap = {
@@ -98,25 +98,6 @@ class Platform extends homebridgeLib.Delegate {
         my: Object.freeze(my.Characteristics)
       })
     }
-    if (global[globalKey] == null) {
-      global[globalKey] = {
-        Platform: {
-          platformName: context.libName,
-          packageJson: libPackageJson,
-          UpnpClient: homebridgeLib.UpnpClient
-        }
-      }
-      homebridge.registerPlatform(
-        // libPackageJson.name, 'Lib', homebridgeLib.Platform, false
-        packageJson.name, 'Lib', homebridgeLib.Platform, false
-      )
-    // } else {
-      // TODO: check compatible homebridge-lib version.
-    }
-    global[globalKey][Platform.name] = {
-      platformName: platformName,
-      packageJson: packageJson
-    }
     homebridge.registerPlatform(
       packageJson.name, platformName, Platform, true
     )
@@ -148,50 +129,19 @@ class Platform extends homebridgeLib.Delegate {
     this._log = log
     this._configJson = configJson
     this._homebridge = homebridge
-    const myContext = global[globalKey][this.className]
-    this._platformName = myContext.platformName
-    this._pluginName = myContext.packageJson.name
-    this._pluginVersion = myContext.packageJson.version
-    if (myContext.packageJson.name === context.libName) {
-      this._isHomebridgeLib = true
-      myContext.heartbeat = this
-      // Delay start of Homebridge's HAP server until all plugins have
-      // initialised.
-      this.accessories = (f) => {
-        this.on('initialised', () => { f([]) })
-      }
-      // this.debug('Categories: %j', this.Accessory.Categories)
-      // for (const type of ['Access', 'Formats', 'Perms', 'Units']) {
-      //   this.debug('%s: %j', type, this.Characteristic[type])
-      // }
-      // for (const module of ['hap', 'eve', 'my']) {
-      //   this.debug('Services.%s: %j', module, Object.keys(this.Services[module]))
-      //   this.debug('Characteristics.%s: %j', module, Object.keys(this.Characteristics[module]))
-      // }
-    } else {
-      /** Configure an accessory, after it has been restored from peristent
-        * storage.
-        *
-        * Called by homebridge when restoring peristed accessories, typically from
-        * `~/.homebridge/accessories/cachedAccessories`.
-        * @method
-        * @param {!PlatformAccessory} accessory - The restored Homebridge
-        * [PlatformAccessory](https://github.com/nfarina/homebridge/blob/master/lib/platformAccessory.js).
-        */
-      this.configureAccessory = this._configureAccessory
-    }
+    this._platformName = context.platformName
+    this._pluginName = context.packageJson.name
+    this._pluginVersion = context.packageJson.version
+
     this._accessories = {}
     this._accessoryDelegates = {}
 
-    if (myContext.platform != null) {
+    if (context.platform != null) {
       this.fatal(
-        'config.json: duplicate entry for %s platform', myContext.platformName
+        'config.json: duplicate entry for %s platform', context.platformName
       )
     }
-    myContext.platform = this
-    if (global[globalKey].Platform == null) {
-      this.fatal('%s platform not registered', context.libName)
-    }
+    context.platform = this
     this._identify()
 
     this._homebridge
@@ -205,54 +155,29 @@ class Platform extends homebridgeLib.Delegate {
   // Main platform function.
   // Called by homebridge after restoring accessories from cache.
   async _main () {
-    if (this._isHomebridgeLib || global[globalKey].Platform.heartbeat == null) {
-      // process.on('unhandledRejection', (error) => {
-      //   this.error('unhandled rejection: %s', error.stack)
-      // })
-      global[globalKey].Platform.heartbeat = this
-      /** System information.
-        * @type {SystemInfo}
-        * @readonly
-        */
-      this.systemInfo = new homebridgeLib.SystemInfo()
-      this.systemInfo
-        .on('error', (error) => { this.warn(error) })
-        .on('exec', (command) => { this.debug('exec: %s', command) })
-        .on('readFile', (filename) => { this.debug('read file: %s', filename) })
-      await this.systemInfo.init()
-      this.log('hardware: %s', this.systemInfo.hwInfo.prettyName)
-      this.log('os: %s', this.systemInfo.osInfo.prettyName)
-      this.heartbeatClients = Object.keys(global[globalKey]).filter((key) => {
-        return global[globalKey][key].platform != null
-      })
-      this.debug('starting heartbeat for %j', this.heartbeatClients)
-      this._heartbeatStart = new Date()
-      setTimeout(() => { this._beat(-1) }, 1000)
-      this.on('exit', () => {
-        this.debug('flush cachedAccessories')
-        this._homebridge.updatePlatformAccessories()
-        this.log('goodbye')
-      })
-    } else {
-      this.systemInfo = global[globalKey].Platform.heartbeat.systemInfo
-    }
-    if (this._isHomebridgeLib) {
-      const jobs = []
-      for (const plugin in global[globalKey]) {
-        const platform = global[globalKey][plugin].platform
-        if (
-          platform != null && platform !== this &&
-          Object.keys(platform._accessories).length === 0
-        ) {
-          this.warn('waiting on %s', plugin)
-          jobs.push(events.once(platform, 'initialised'))
-        }
-      }
-      for (const job of jobs) {
-        await job
-      }
-      this.emit('initialised')
-    }
+    // process.on('unhandledRejection', (error) => {
+    //   this.error('unhandled rejection: %s', error.stack)
+    // })
+    /** System information.
+      * @type {SystemInfo}
+      * @readonly
+      */
+    this.systemInfo = new homebridgeLib.SystemInfo()
+    this.systemInfo
+      .on('error', (error) => { this.warn(error) })
+      .on('exec', (command) => { this.debug('exec: %s', command) })
+      .on('readFile', (filename) => { this.debug('read file: %s', filename) })
+    await this.systemInfo.init()
+    this.log('hardware: %s', this.systemInfo.hwInfo.prettyName)
+    this.log('os: %s', this.systemInfo.osInfo.prettyName)
+    this._heartbeatStart = new Date()
+    setTimeout(() => { this._beat(-1) }, 1000)
+    this.on('exit', () => {
+      this.debug('flush cachedAccessories')
+      this._homebridge.updatePlatformAccessories()
+      this.log('goodbye')
+    })
+
     const n = Object.keys(this._accessories).length
     if (n > 0) {
       this.log('restored %d accessories from cache', n)
@@ -301,15 +226,11 @@ class Platform extends homebridgeLib.Delegate {
       this._homebridge.updatePlatformAccessories()
     }
 
-    for (const plugin of this.heartbeatClients) {
-      global[globalKey][plugin].platform._heartbeat(beat)
-    }
-  }
-
-  _heartbeat (beat) {
     if (beat % context.checkInterval === 0) {
-      this._checkLatest()
+      this._checkLatest(this._pluginName, this._pluginVersion)
+      this._checkLatest(context.libName, context.libVersion)
     }
+
     /** Emitted every second.
       * @event Platform#heartbeat
       * @param {number} beat - The sequence number of this heartbeat.
@@ -364,13 +285,10 @@ class Platform extends homebridgeLib.Delegate {
 
   // Issue an identity message.
   _identify () {
-    const s = this._isHomebridgeLib
-      ? ''
-      : ', ' + context.libName + ' v' + context.libVersion
     this.log(
-      '%s v%s, node v%s, homebridge v%s%s',
-      this._pluginName, this._pluginVersion,
-      context.nodeVersion, context.homebridgeVersion, s
+      '%s v%s, node v%s, homebridge v%s, %s v%s',
+      this._pluginName, this._pluginVersion, context.nodeVersion,
+      context.homebridgeVersion, context.libName, context.libVersion
     )
     if (context.nodeVersion !== context.recommendedNodeVersion) {
       this.warn(
@@ -391,16 +309,16 @@ class Platform extends homebridgeLib.Delegate {
   }
 
   // Check the NPM registry for the latest version of this plugin.
-  async _checkLatest () {
+  async _checkLatest (name, version) {
     try {
-      if (global[globalKey].Platform.npmRegistry == null) {
-        const npmRegistry = new homebridgeLib.HttpClient({
+      if (this.npmRegistry == null) {
+        this.npmRegistry = new homebridgeLib.HttpClient({
           https: true,
           host: 'registry.npmjs.org',
           json: true,
           maxSockets: 1
         })
-        npmRegistry
+        this.npmRegistry
           .on('error', (error) => {
             this.log(
               'npm registry: request %d: %s %s', error.request.id,
@@ -428,15 +346,14 @@ class Platform extends homebridgeLib.Delegate {
               response.statusCode, response.statusMessage
             )
           })
-        global[globalKey].Platform.npmRegistry = npmRegistry
       }
-      const { body } = await global[globalKey].Platform.npmRegistry.get(
-        '/' + this._pluginName + '/latest', { Accept: 'application/json' })
+      const { body } = await this.npmRegistry.get(
+        '/' + name + '/latest', { Accept: 'application/json' })
       if (body != null && body.version != null) {
-        if (body.version !== this._pluginVersion) {
-          this.warn('latest version: %s v%s', this._pluginName, body.version)
+        if (body.version !== version) {
+          this.warn('latest version: %s v%s', name, body.version)
         } else {
-          this.debug('latest version: %s v%s', this._pluginName, body.version)
+          this.debug('latest version: %s v%s', name, body.version)
         }
       }
     } catch (error) {
@@ -448,7 +365,16 @@ class Platform extends homebridgeLib.Delegate {
 
   // ===== Handle Accessories ==================================================
 
-  _configureAccessory (accessory) {
+  /** Configure an accessory, after it has been restored from peristent
+    * storage.
+    *
+    * Called by homebridge when restoring peristed accessories, typically from
+    * `~/.homebridge/accessories/cachedAccessories`.
+    * @method
+    * @param {!PlatformAccessory} accessory - The restored Homebridge
+    * [PlatformAccessory](https://github.com/nfarina/homebridge/blob/master/lib/platformAccessory.js).
+    */
+  configureAccessory (accessory) {
     const className = accessory.context.className
     const version = accessory.context.version
     const id = accessory.context.id
@@ -584,7 +510,7 @@ class Platform extends homebridgeLib.Delegate {
     if (this._upnpMonitor != null) {
       throw new SyntaxError('upnpConfig(): already called')
     }
-    this._upnpMonitor = new global[globalKey].Platform.UpnpClient(config)
+    this._upnpMonitor = new homebridgeLib.UpnpClient(config)
     this._upnpMonitor
       .on('error', (error) => {
         this.error('upnp: error')