From d59d454ab22ee4a6b4e742e002193eccb99cec53 Mon Sep 17 00:00:00 2001 From: ebaauw Date: Mon, 11 Dec 2023 13:10:40 +0100 Subject: [PATCH] Remove mention of deCONZ from documentation. See #1070. --- index.js | 2 +- lib/EventStreamClient.js | 23 +++++++++--- lib/HueAccessory.js | 2 +- lib/HueBridge.js | 4 +-- lib/HueClient.js | 76 ++++++++++------------------------------ lib/HueLight.js | 2 +- lib/HuePlatform.js | 5 +-- lib/HueSchedule.js | 2 +- lib/HueSensor.js | 2 +- lib/WsMonitor.js | 63 +-------------------------------- 10 files changed, 45 insertions(+), 136 deletions(-) diff --git a/index.js b/index.js index b7a51ce..f15af1d 100644 --- a/index.js +++ b/index.js @@ -1,7 +1,7 @@ // homebridge-hue/index.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plug-in for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. 'use strict' diff --git a/lib/EventStreamClient.js b/lib/EventStreamClient.js index d24bc10..50689cc 100644 --- a/lib/EventStreamClient.js +++ b/lib/EventStreamClient.js @@ -1,6 +1,6 @@ // homebridge-hue/lib/EventStreamClient.js // -// Homebridge plug-in for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. // Copyright © 2021-2023 Erik Baauw. All rights reserved. 'use strict' @@ -28,10 +28,8 @@ class EventStreamClient extends events.EventEmitter { * reconnect when the server connection has been closed. * @param {boolean} [params.raw=false] - Issue raw events instead of parsing * them.
- * When specified, {@link WsMonitor#event:notification notification} - * events are emitted, in lieu of {@link WsMonitor#event:changed changed}, - * {@link WsMonitor#event:added added}, and - * {@link WsMonitor#event:sceneRecall sceneRecall} events. + * When specified, {@link EventStreamClient#event:notification notification} + * events are emitted, in lieu of {@link EventStreamClient#event:changed changed}. */ constructor (client, params = {}) { super() @@ -280,6 +278,15 @@ class EventStreamClient extends events.EventEmitter { } } if (Object.keys(attr).length > 0) { + /** Emitted when a `changed` notification has been received. + * @event EventStreamClient#changed + * @param {string} resource - The changed resource.
+ * This can be a `/lights`, `/groups`, or `/sensors` + * resource for top-level attributes, or a `state` or + * `config` sub-resource. + * @param {object} attributes - The top-level, `state`, + * `config`, or `capabilities` attributes. + */ this.emit('changed', resource, attr) emitted = true } @@ -293,6 +300,12 @@ class EventStreamClient extends events.EventEmitter { } } if (!emitted) { + /** Emitted when an unknown notification has been received, or when + * `params.raw` was specified to the + * {@link EventStreamClient constructor}. + * @event EventStreamClient#notification + * @param {object} notification - The raw notification. + */ this.emit('notification', obj) } } diff --git a/lib/HueAccessory.js b/lib/HueAccessory.js index 406a753..ceaabf6 100644 --- a/lib/HueAccessory.js +++ b/lib/HueAccessory.js @@ -1,7 +1,7 @@ // homebridge-hue/lib/HueAccessory.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plugin for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. 'use strict' diff --git a/lib/HueBridge.js b/lib/HueBridge.js index 5335761..65cc0e7 100644 --- a/lib/HueBridge.js +++ b/lib/HueBridge.js @@ -1,7 +1,7 @@ // homebridge-hue/lib/HueBridge.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plugin for Philips Hue and/or deCONZ. +// Homebridge plugin for Philips Hue. 'use strict' @@ -205,7 +205,7 @@ HueBridge.prototype.exposeBridge = async function () { ) this.log.info(this.idString) if (this.platform.config.homebridgeDeconz === '') { - this.log.warn( + this.log.error( '%s: warning: support for deCONZ has been deprecated in favour of Homebridge deCONZ', this.name ) diff --git a/lib/HueClient.js b/lib/HueClient.js index 54d1c7d..b231480 100644 --- a/lib/HueClient.js +++ b/lib/HueClient.js @@ -1,6 +1,6 @@ // homebridge-hue/lib/HueClient.js // -// Homebridge plug-in for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. // Copyright © 2018-2023 Erik Baauw. All rights reserved. 'use strict' @@ -89,21 +89,16 @@ class HueResponse extends HttpClient.HttpResponse { get errors () {} } -/** REST API client for Hue bridge, deCONZ gateway, and compatible servers. +/** REST API client for Hue bridge and compatible servers. * * See the [Hue API](https://developers.meethue.com/develop/get-started-2/) - * and [deCONZ API](https://dresden-elektronik.github.io/deconz-rest-doc/) - * documentation for a better understanding of the APIs. + * documentation for a better understanding of the API. * @extends HttpClient */ class HueClient extends HttpClient { static get HueError () { return HueError } static get HueResponse () { return HueResponse } - /** Check if bridgeid is for a deCONZ gateway. - * @param {string} bridgeid - The bridge ID. - * @returns {boolean} - */ static isDeconzBridgeId (bridgeid) { return deconzMacPrefixes.includes(bridgeid.slice(0, 6)) } @@ -119,7 +114,7 @@ class HueClient extends HttpClient { /** Create a new instance of a HueClient. * * The caller is expected to verify that the given host is a reachable Hue - * bridge or deCONZ gateway, by calling + * bridge, by calling * {@link HueDiscovery#config HueDiscovery#config()} and passing the * response as `params.config`.
* The caller is expected to persist the username (API key), @@ -142,17 +137,13 @@ class HueClient extends HttpClient { * with firmware v1.24.0 or greater. * @param {boolean} [params.forceHttp=false] - Force HTTP instead of HTTPS * for Hue bridge with firmware v1.24.0 and greater. - * @param {!string} params.host - Hostname/IP address and port of the Hue - * bridge or deCONZ gateway. + * @param {!string} params.host - Hostname/IP address of the Hue bridge. * @param {boolean} [params.keepAlive=false] - Keep server connection(s) * open. * @param {integer} [params.maxSockets=20] - Throttle requests to maximum * number of parallel connections. - * @param {boolean} [params.phoscon=false] - Mimic Phoscon web app to use - * deCONZ gateway API extensions. * @param {integer} [params.timeout=5] - Request timeout (in seconds). - * @param {?string} params.username - The API key of the Hue bridge or - * deCONZ gateway. + * @param {?string} params.username - The API key of the Hue bridge. * @param {integer} [params.waitTimePut=50] - The time (in milliseconds), * after sending a PUT request, to wait before sending another PUT request. * @param {integer} [params.waitTimePutGroup=1000] - The time (in @@ -231,7 +222,7 @@ class HueClient extends HttpClient { this.setMaxListeners(30) } - /** The ID (Zigbee mac address) of the Hue bridge or deCONZ gateway. + /** The ID (mac address) of the Hue bridge. * @type {string} * @readonly */ @@ -245,10 +236,6 @@ class HueClient extends HttpClient { get fingerprint () { return this._options.fingerprint } set fingerprint (value) { this._options.fingerprint = value } - /** True when connected to a deCONZ gateway. - * @type {boolean} - * @readonly - */ get isDeconz () { return this._options.isDeconz } /** True when connected to a Hue bridge. @@ -411,7 +398,7 @@ class HueClient extends HttpClient { * Calls {@link HueClient#post post()} to issue a POST request to `/api`. * * Before calling `createuser`, the link button on the Hue bridge must be - * pressed, or the deCONZ gateway must be unlocked. + * pressed. * @return {string} username - The newly created API key. * @throws {HueError} In case of error. */ @@ -436,7 +423,7 @@ class HueClient extends HttpClient { * * Calls {@link HueClient#put put()} to issue a PUT request to * `/api/`_username_`/config`. - * On a Hue bridge, this is the API equivalent of pressing the link button. + * This is the API equivalent of pressing the link button on the Hue bridge. * * Note that as of firmware v1.31.0, the gen-2 Hue bridge no longer allows * unlocking the bridge through the API. @@ -450,28 +437,12 @@ class HueClient extends HttpClient { return this.put('/config', { linkbutton: true }) } - /** Initiate a touchlink pairing (Hue bridge) - * or touchlink scan (deCONZ gateway). + /** Initiate a touchlink pairing. * - * When connected to a Hue bridge, calls {@link HueClient#put put()} to issue + * Calls {@link HueClient#put put()} to issue * a PUT request to `/api/`_username_`/config` to initiate touchlink pairing. * This is the API equivalent of holding the link button on the Hue bridge. * - * Note that deCONZ doesn't support touchlink pairing, only touchlink scan, - * identify, and reset. - * When connected to a deCONZ gateway, calls {@link HueClient#post post()} - * to issue a POST request to `/api/`_username_`/touchlink/scan`, - * to initiate a touchlink scan. - * As the ConBee II and RaspBee II firmware lack support for touchlink, - * this will only work for the original ConBee and RaspBee. - * To see the results of the scan, issue a GET request of - * `/api/`_username_`/touchlink/scan`. - * The ID returned in the scan results is needed to touchlink identify or - * reset the device. - * To issue a touchlink identify, issue a POST request of - * `/api/`_username_`/touchlink/`_ID_`/identify`. - * To issue a touchlink reset, issue a POST request to - * `/api/`_username_`/touchlink/`_ID_`/reset`. * @return {HueResponse} response - The response. * @throws {HueError} In case of error. */ @@ -484,13 +455,8 @@ class HueClient extends HttpClient { /** Search for new devices. * - * When connected to a Hue bridge, calls {@link HueClient#post post()} to - * issue a POST request to `/api/`_username_`/lights`, to enable pairing of - * new Zigbee devices. - * - * When connected to a deCONZ gateway, calls {@link HueClient#put put()} to - * issue a PUT request to `/api/`_username_`/config`, to enable pairing of - * new Zigbee devices. + * Calls {@link HueClient#post post()} to issue a POST request to + * `/api/`_username_`/lights`, to enable pairing of new Zigbee devices. * * To see the newly paired devices, issue a GET request of * `/api/`_username_`/lights/new` and/or `/api/`_username_`/sensor/new` @@ -504,14 +470,9 @@ class HueClient extends HttpClient { return this.post('/lights') } - /** Restart the bridge or gateway. - * When connected to a Hue bridge, calls {@link HueClient#put put()} to - * issue a PUT request to `/api/`_username_`/config`, to reboot the Hue - * bridge. - * - * When connected to a deCONZ gateway, calls {@link HueClient#post post()} - * to issue a POST request to `/api/`_username_`/config/restartapp`, to - * restart the deCONZ gateway. + /** Restart the bridge. + * Calls {@link HueClient#put put()} to issue a PUT request to + * `/api/`_username_`/config`, to reboot the Hue bridge. * * @return {HueResponse} response - The response. * @throws {HueError} In case of error. @@ -557,7 +518,7 @@ class HueClient extends HttpClient { } } - /** Issue an HTTP request to the Hue bridge or deCONZ gateway. + /** Issue an HTTP request to the Hue bridge. * * This method does the heavy lifting for {@link HueClient#get get()}, * {@link HueClient#put put()}, {@link HueClient#post post()}, and @@ -588,8 +549,7 @@ class HueClient extends HttpClient { error.type = e.type error.description = e.description error.nonCritical = nonCriticalApiErrorTypes.includes(error.type) - /** Emitted for each API error returned by the Hue bridge - * or deCONZ gateway. + /** Emitted for each API error returned by the Hue bridge. * * @event HueClient#error * @param {HueError} error - The error. diff --git a/lib/HueLight.js b/lib/HueLight.js index b906dd7..5ba23d3 100644 --- a/lib/HueLight.js +++ b/lib/HueLight.js @@ -1,7 +1,7 @@ // homebridge-hue/lib/HueLight.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plugin for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. 'use strict' diff --git a/lib/HuePlatform.js b/lib/HuePlatform.js index b6df1dd..df0c94f 100644 --- a/lib/HuePlatform.js +++ b/lib/HuePlatform.js @@ -1,7 +1,7 @@ // homebridge-hue/lib/HuePlatform.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plugin for Philips Hue and/or deCONZ. +// Homebridge plugin for Philips Hue. 'use strict' @@ -339,9 +339,6 @@ HuePlatform.prototype.identify = function () { '%s v%s, node %s, homebridge v%s', packageJson.name, packageJson.version, process.version, this.api.serverVersion ) - this.log.warn( - 'warning: planned changes, see https://github.com/ebaauw/homebridge-hue/issues/1070' - ) if (semver.clean(process.version) !== recommendedNodeVersion(packageJson)) { this.log.warn( 'warning: recommended version: node v%s LTS', diff --git a/lib/HueSchedule.js b/lib/HueSchedule.js index 243b5ba..8463090 100644 --- a/lib/HueSchedule.js +++ b/lib/HueSchedule.js @@ -1,7 +1,7 @@ // homebridge-hue/lib/HueSchedule.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plugin for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. 'use strict' diff --git a/lib/HueSensor.js b/lib/HueSensor.js index a274f0c..1cff7c9 100644 --- a/lib/HueSensor.js +++ b/lib/HueSensor.js @@ -1,7 +1,7 @@ // homebridge-hue/lib/HueSensor.js // Copyright © 2016-2023 Erik Baauw. All rights reserved. // -// Homebridge plugin for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. 'use strict' diff --git a/lib/WsMonitor.js b/lib/WsMonitor.js index e0b6516..89a8a71 100644 --- a/lib/WsMonitor.js +++ b/lib/WsMonitor.js @@ -1,6 +1,6 @@ // homebridge-hue/lib/WsMonitor.js // -// Homebridge plug-in for Philips Hue and/or deCONZ. +// Homebridge plug-in for Philips Hue. // Copyright © 2018-2023 Erik Baauw. All rights reserved. 'use strict' @@ -9,27 +9,7 @@ const events = require('events') const { OptionParser } = require('homebridge-lib') const WebSocket = require('ws') -/** Client for deCONZ web socket notifications. - * - * See the - * [deCONZ](https://dresden-elektronik.github.io/deconz-rest-doc/endpoints/websocket/) - * documentation for a better understanding of the web socket notifications. - * @copyright © 2018-2021 Erik Baauw. All rights reserved. - */ class WsMonitor extends events.EventEmitter { - /** Create a new web socket client instance. - * @param {object} params - Parameters. - * @param {string} [params.host='localhost:443'] - IP address or hostname - * and port of the web socket server. - * @param {integer} [params.retryTime=10] - Time (in seconds) to try and - * reconnect when the server connection has been closed. - * @param {boolean} [params.raw=false] - Issue raw events instead of parsing - * them.
- * When specified, {@link WsMonitor#event:notification notification} - * events are emitted, in lieu of {@link WsMonitor#event:changed changed}, - * {@link WsMonitor#event:added added}, and - * {@link WsMonitor#event:sceneRecall sceneRecall} events. - */ constructor (params = {}) { super() this._options = { @@ -44,25 +24,15 @@ class WsMonitor extends events.EventEmitter { optionParser.parse(params) } - /** Listen for web socket notifications. - */ listen () { const url = 'ws://' + this._options.hostname + ':' + this._options.port this.ws = new WebSocket(url, { family: 4 }) this.ws .on('error', (error) => { - /** Emitted on error. - * @event WsMonitor#error - * @param {Error} error - The error. - */ this.emit('error', error) }) .on('open', () => { - /** Emitted when connection to web socket server is opened. - * @event WsMonitor#listening - * @param {string} url - The URL of the web socket server. - */ this.emit('listening', url) }) .on('message', (data, flags) => { @@ -74,15 +44,6 @@ class WsMonitor extends events.EventEmitter { case 'changed': if (obj.r && obj.id && obj.state) { const resource = '/' + obj.r + '/' + obj.id + '/state' - /** Emitted when a `changed` notification has been received. - * @event WsMonitor#changed - * @param {string} resource - The changed resource.
- * This can be a `/lights`, `/groups`, or `/sensors` - * resource for top-level attributes, or a `state` or - * `config` sub-resource. - * @param {object} attributes - The top-level, `state`, - * `config`, or `capabilities` attributes. - */ this.emit('changed', resource, obj.state) return } @@ -105,12 +66,6 @@ class WsMonitor extends events.EventEmitter { case 'added': if (obj.r && obj.id) { const resource = '/' + obj.r + '/' + obj.id - /** Emitted when an `added` notification has been received. - * @event WsMonitor#added - * @param {string} resource - The added resource. - * @param {object} attributes - The full attributes of the - * added resource. - */ this.emit('added', resource, obj[obj.r.slice(0, -1)]) return } @@ -118,10 +73,6 @@ class WsMonitor extends events.EventEmitter { case 'scene-called': if (obj.gid && obj.scid) { const resource = '/groups/' + obj.gid + '/scenes/' + obj.scid - /** Emitted when an `sceneRecall` notification has been received. - * @event WsMonitor#sceneRecall - * @param {string} resource - The scene resource. - */ this.emit('sceneRecall', resource) return } @@ -131,22 +82,12 @@ class WsMonitor extends events.EventEmitter { } } } - /** Emitted when an unknown notification has been received, or when - * `params.raw` was specified to the - * {@link WsMonitor constructor}. - * @event WsMonitor#notification - * @param {object} notification - The raw notification. - */ this.emit('notification', obj) } catch (error) { this.emit('error', error) } }) .on('close', () => { - /** Emitted when the connection to the web socket server has been closed. - * @event WsMonitor#closed - * @param {string} url - The URL of the web socket server. - */ this.emit('closed', url) if (this._options.retryTime > 0) { setTimeout(this.listen.bind(this), this._options.retryTime * 1000) @@ -154,8 +95,6 @@ class WsMonitor extends events.EventEmitter { }) } - /** Close the websocket. - */ async close () { if (this.ws != null) { this.ws.close()