homebridge-flume 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to homebridge-flume will be documented in this file.
 
+## 0.5.0 (2021-11-23)
+
+### Added
+
+- Make use of the debug logging option for HTTP responses
+
+### Changed
+
+- `client_id` and `client_secret` config options changed to `clientId` and `clientSecret` for consistency
+
+## 0.4.0 (2021-11-23)
+
+### Added
+
+- The plugin will remove 'stale' accessories that don't appear in the obtained device list
+
+## 0.3.1 (2021-11-23)
+
+### Fixed
+
+- Some logging references to Thermobit rather than Flume
+
 ## 0.3.0 (2021-11-22)
 
 Changed some configuration options
@@ -12,4 +34,4 @@ Converted from accessory plugin to platform plugin
 
 ## 0.1.0 (2021-11-22)
 
-Initial release
+Initial release

package/README.md

@@ -1,32 +1,49 @@
-# homebridge-flume
-
-# Configuration
-
-Configuration sample:
-
-```
-{
-  "name": "Flume Water Monitor",
-  "username": "user@domain.com",
-  "password": "password",
-  "client_id": "12345678901234567890",
-  "client_secret": "1234567890",
-  "refreshInterval": 1,
-  "threshold": 0.1,
-  "platform": "Flume"
-}
-```
-
-Fields:
-
-- "username": Your username for accessing the Flume site at https://portal.flumetech.com/ (required)
-- "password": Your password for accessing the Flume site (required)
-- "client_id": Your Client ID for API access, found in Settings on the Flume site (required)
-- "client_secret": Your Client Secret for API access, found in Settings on the Flume site (required)
-- "refreshInterval": Number of minutes between updates. Defaults to 1 minute. API has a cap of 120 calls per hour. (optional)
-- "threshold": Set to ignore a steady water draw below this value. Defaults to zero (0.0) gallons. (optional)
-
-# Retrieving API Login Credentials
-
-You'll need to get your API Access Client ID and Client Secret from Flume's site at https://portal.flumetech.com/
-This guide offers the steps to take: https://flumetech.readme.io/reference#accessing-the-api
+<span align="center">
+  
+  # homebridge-flume
+  
+  Homebridge plugin to integrate Flume devices into HomeKit
+  
+  [![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)  
+  [![npm](https://img.shields.io/npm/v/homebridge-flume/latest?label=latest)](https://www.npmjs.com/package/homebridge-flume)
+  [![npm](https://img.shields.io/npm/v/homebridge-flume/beta?label=beta)](https://github.com/bwp91/homebridge-flume/wiki/Beta-Version)  
+  [![npm](https://img.shields.io/npm/dt/homebridge-flume)](https://www.npmjs.com/package/homebridge-flume)
+  [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)  
+  [![Discord](https://img.shields.io/discord/784827113378676736?color=728ED5&logo=discord&label=bwp91-discord)](https://discord.com/channels/784827113378676736/784827113378676739)
+  [![Discord](https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=hb-discord)](https://discord.com/channels/432663330281226270/742733745743855627)
+  
+</span>
+
+### Plugin Information
+
+- This plugin allows you to view and control your Flume devices within HomeKit.
+
+### Prerequisites
+
+- To use this plugin, you will need to already have [Homebridge](https://homebridge.io) (at least v1.3) or [HOOBS](https://hoobs.org) (at least v4.1) installed. Refer to the links for more information and installation instructions.
+- Whilst it is recommended to use [Node](https://nodejs.org/en/) v16, the plugin supports v12 and v14 as per the [Homebridge guidelines](https://github.com/homebridge/homebridge/wiki/How-To-Update-Node.js).
+
+### Setup
+
+- [Installation](https://github.com/bwp91/homebridge-flume/wiki/Installation)
+- [Configuration](https://github.com/bwp91/homebridge-flume/wiki/Configuration)
+- [Beta Version](https://github.com/bwp91/homebridge-flume/wiki/Beta-Version)
+- [Node Version](https://github.com/bwp91/homebridge-flume/wiki/Node-Version)
+- [Uninstallation](https://github.com/bwp91/homebridge-flume/wiki/Uninstallation)
+
+### Help/About
+
+- [Common Errors](https://github.com/bwp91/homebridge-flume/wiki/Common-Errors)
+- [Support Request](https://github.com/bwp91/homebridge-flume/issues/new/choose)
+- [Changelog](https://github.com/bwp91/homebridge-flume/blob/latest/CHANGELOG.md)
+- [About Me](https://github.com/sponsors/bwp91)
+
+### Credits
+
+- This is a forked rewrite of the [homebridge-flume-water-sensor](https://www.npmjs.com/package/homebridge-flume-water-sensor) plugin by @weallknowwhoisatfaulthere.
+- To the creators/contributors of [Homebridge](https://homebridge.io) who make this plugin possible.
+
+### Disclaimer
+
+- I am in no way affiliated with Flume and this plugin is a personal project that I maintain in my free time.
+- Use this plugin entirely at your own risk - please see licence for more information.

package/config.schema.json

@@ -17,75 +17,69 @@
         "title": "Username",
         "type": "string",
         "required": true,
-        "description": "Your username for accessing the Flume site at https://portal.flumetech.com"
+        "description": "Your Flume username."
       },
       "password": {
         "title": "Password",
         "type": "string",
         "required": true,
-        "description": "Your password for accessing the Flume site"
+        "description": "Your Flume password."
       },
-      "client_id": {
+      "clientId": {
         "title": "Client ID",
         "type": "string",
-        "placeholder": "12345678901234567890",
+        "placeholder": "1234567890ABCD",
         "required": true,
-        "description": "Your Client ID for API access, found in Settings on the Flume site"
+        "description": "Your Flume Client ID, found at https://portal.flumetech.com."
       },
-      "client_secret": {
+      "clientSecret": {
         "title": "Client Secret",
         "type": "string",
-        "placeholder": "1234567890",
+        "placeholder": "1234567890ABCDEFGHIJ",
         "required": true,
-        "description": "Your Client Secret for API access, found in Settings on the Flume site"
+        "description": "Your Flume Client Secret, found at https://portal.flumetech.com."
       },
       "refreshInterval": {
-        "title": "Refresh interval",
+        "title": "Refresh Interval",
         "type": "integer",
         "placeholder": 1,
-        "description": "Number of minutes between updates. API has a cap of 120 calls per hour."
+        "description": "Number of minutes between updates. Must be 1 or more."
       },
       "threshold": {
-        "title": "Adjustment for False Positives",
+        "title": "Threshold",
         "type": "number",
         "placeholder": 0,
-        "description": "Set to ignore a steady water draw below this value (gallons)."
+        "description": "Ignore a steady water draw below this value in gallons per refresh interval. Must be 0 or more."
       },
       "disableDeviceLogging": {
-          "type": "boolean",
-          "title": "Disable Device Logging",
-          "description": "Global logging setting for accessory status changes. If true then accessory status changes will not be logged."
-        },
-        "debug": {
-          "title": "Debug Logging",
-          "type": "boolean",
-          "description": "Global logging setting for the plugin. If true then debug information will be added to the log."
-        },
-        "disablePlugin": {
-          "title": "Disable Plugin",
-          "type": "boolean",
-          "description": "If true, the plugin will remove all accessories and not load the plugin on restart."
-        }
+        "type": "boolean",
+        "title": "Disable Device Logging",
+        "description": "Global logging setting for accessory status changes. If true then accessory status changes will not be logged."
+      },
+      "debug": {
+        "title": "Debug Logging",
+        "type": "boolean",
+        "description": "Global logging setting for the plugin. If true then debug information will be added to the log."
+      },
+      "disablePlugin": {
+        "title": "Disable Plugin",
+        "type": "boolean",
+        "description": "If true, the plugin will remove all accessories and not load the plugin on restart."
+      }
     }
   },
   "layout": [
     {
       "type": "fieldset",
       "title": "Required Settings",
-      "items": ["username", "password", "client_id", "client_secret"]
+      "items": ["username", "password", "clientId", "clientSecret"]
     },
     {
       "type": "fieldset",
       "title": "Optional Settings",
       "description": "Optional settings for the plugin, including global logging settings.",
       "expandable": true,
-      "items": [
-        "refreshInterval",
-        "threshold",
-        "disableDeviceLogging",
-        "debug",
-        "disablePlugin"
-      ]
+      "items": ["refreshInterval", "threshold", "disableDeviceLogging", "debug", "disablePlugin"]
     }
   ]
 }

package/lib/connection/http.js

@@ -15,8 +15,8 @@ module.exports = class connectionHTTP {
     this.log = platform.log
     this.username = platform.config.username
     this.password = platform.config.password
-    this.client_id = platform.config.client_id
-    this.client_secret = platform.config.client_secret
+    this.clientId = platform.config.clientId
+    this.clientSecret = platform.config.clientSecret
   }
 
   async obtainToken () {
@@ -24,8 +24,8 @@ module.exports = class connectionHTTP {
       // Generate the JSON data to send
       const body = {
         grant_type: 'password',
-        client_id: this.client_id,
-        client_secret: this.client_secret,
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
         username: this.username,
         password: this.password
       }
@@ -38,7 +38,7 @@ module.exports = class connectionHTTP {
 
       // Check to see we got a response
       if (!res.data) {
-        throw new Error(this.lang.noToken)
+        throw new Error(this.lang.noDataReceived)
       }
 
       /*
@@ -62,6 +62,11 @@ module.exports = class connectionHTTP {
         }
       */
 
+      // Log the response if in debug mode
+      if (this.debug) {
+        this.log('[HTTP obtainToken()] %s.', JSON.stringify(res.data))
+      }
+
       // Make the token available in other functions
       this.accessToken = res.data.data[0].access_token
       this.refreshToken = res.data.data[0].refresh_token
@@ -84,7 +89,7 @@ module.exports = class connectionHTTP {
     } catch (err) {
       if (err.code && this.consts.httpRetryCodes.includes(err.code)) {
         // Retry if another attempt could be successful
-        this.log.warn('[HTTP login()] %s [%s].', this.lang.httpRetry, err.code)
+        this.log.warn('[HTTP obtainToken()] %s [%s].', this.lang.httpRetry, err.code)
         await this.funcs.sleep(30000)
         return await this.login()
       } else {
@@ -95,11 +100,16 @@ module.exports = class connectionHTTP {
 
   async renewToken () {
     try {
+      // Check we have a refresh token
+      if (!this.refreshToken) {
+        throw new Error(this.lang.noRefreshToken)
+      }
+
       // Generate the JSON data to send
       const body = {
         grant_type: 'refresh_token',
-        client_id: this.client_id,
-        client_secret: this.client_secret,
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
         refresh_token: this.refreshToken
       }
       const now = Date.now()
@@ -111,7 +121,12 @@ module.exports = class connectionHTTP {
 
       // Check to see we got a response
       if (!res.data) {
-        throw new Error(this.lang.noToken)
+        throw new Error(this.lang.noDataReceived)
+      }
+
+      // Log the response if in debug mode
+      if (this.debug) {
+        this.log('[HTTP renewToken()] %s.', JSON.stringify(res.data))
       }
 
       /*
@@ -142,11 +157,11 @@ module.exports = class connectionHTTP {
     } catch (err) {
       if (err.code && this.consts.httpRetryCodes.includes(err.code)) {
         // Retry if another attempt could be successful
-        this.log.warn('[HTTP login()] %s [%s].', this.lang.httpRetry, err.code)
+        this.log.warn('[HTTP renewToken()] %s [%s].', this.lang.httpRetry, err.code)
         await this.funcs.sleep(30000)
         return await this.login()
       } else {
-        throw new Error('[HTTP refreshToken()] ' + err.message)
+        throw new Error('[HTTP renewToken()] ' + err.message)
       }
     }
   }
@@ -154,8 +169,8 @@ module.exports = class connectionHTTP {
   async getDevices () {
     try {
       // Check we have a user id
-      if (!this.userId) {
-        throw new Error('No user id has been retrieved')
+      if (!this.userId || !this.accessToken) {
+        throw new Error(this.lang.noUserId)
       }
 
       // Perform the HTTP request
@@ -166,14 +181,19 @@ module.exports = class connectionHTTP {
 
       // Check to see we got a response
       if (!res.data) {
-        throw new Error('No data received')
+        throw new Error(this.lang.noDataReceived)
+      }
+
+      // Log the response if in debug mode
+      if (this.debug) {
+        this.log('[HTTP getDevices()] %s.', JSON.stringify(res.data))
       }
 
       return res.data.data
     } catch (err) {
       if (err.code && this.consts.httpRetryCodes.includes(err.code)) {
         // Retry if another attempt could be successful
-        this.log.warn('[HTTP login()] %s [%s].', this.lang.httpRetry, err.code)
+        this.log.warn('[HTTP getDevices()] %s [%s].', this.lang.httpRetry, err.code)
         await this.funcs.sleep(30000)
         return await this.login()
       } else {
@@ -212,6 +232,16 @@ module.exports = class connectionHTTP {
       }
     )
 
+    // Check to see we got a response
+    if (!res.data) {
+      throw new Error(this.lang.noDataReceived)
+    }
+
+    // Log the response if in debug mode
+    if (this.debug) {
+      this.log('[HTTP getDevice()] %s.', JSON.stringify(res.data))
+    }
+
     // Parse the response
     return res.data.data[0]
   }

package/lib/device/valve.js

@@ -6,14 +6,13 @@ module.exports = class deviceValve {
   constructor (platform, accessory) {
     // Set up variables from the platform
     this.accessory = accessory
-    this.disableDeviceLogging = platform.config.disableDeviceLogging
     this.funcs = platform.funcs
     this.threshold = platform.config.threshold
     this.hapChar = platform.api.hap.Characteristic
     this.hapErr = platform.api.hap.HapStatusError
     this.hapServ = platform.api.hap.Service
     this.lang = platform.lang
-    this.log = platform.log
+    this.log = platform.config.disableDeviceLogging ? () => {} : platform.log
     this.name = accessory.displayName
     this.platform = platform
     this.refreshInterval = platform.config.refreshInterval
@@ -27,9 +26,8 @@ module.exports = class deviceValve {
         : 0
     if (usage > this.threshold) {
       this.log(
-        '[%s] %s - [%s] gallons within the last [%s] minutes.',
+        '[%s] usage detected - [%s] gallons within the last [%s] minutes.',
         this.name,
-        'usage detected',
         usage,
         this.refreshInterval
       )

package/lib/homebridge-ui/public/index.html

@@ -76,6 +76,13 @@
   </ul>
   <h4>Credits</h4>
   <ul>
+    <li>
+      This is a forked rewrite of the
+      <a href="https://www.npmjs.com/package/homebridge-flume-water-sensor" target="_blank"
+        >homebridge-flume-water-sensor</a
+      >
+      plugin by @weallknowwhoisatfaulthere
+    </li>
     <li>
       To the creators/contributors of
       <a href="https://homebridge.io" target="_blank">Homebridge</a> who make this plugin possible.

package/lib/index.js

@@ -88,8 +88,8 @@ class FlumePlatform {
     // Begin applying the user's config
     for (const [key, val] of Object.entries(config)) {
       switch (key) {
-        case 'client_id':
-        case 'client_secret':
+        case 'clientId':
+        case 'clientSecret':
         case 'password':
         case 'username':
           if (typeof val !== 'string' || val === '') {
@@ -161,8 +161,8 @@ class FlumePlatform {
       if (
         !this.config.username ||
         !this.config.password ||
-        !this.config.client_id ||
-        !this.config.client_secret
+        !this.config.clientId ||
+        !this.config.clientSecret
       ) {
         throw new Error(this.lang.noCreds)
       }
@@ -174,9 +174,11 @@ class FlumePlatform {
 
       // Check we have devices we can work with
       if (!Array.isArray(deviceList) || deviceList.length === 0) {
+        this.devicesInHB.forEach(accessory => this.removeAccessory(accessory))
         throw new Error(this.lang.noDevices)
       }
 
+      // Initialise each device into Homebridge
       deviceList.forEach(device => {
         if (!device.bridge_id) {
           return
@@ -184,6 +186,13 @@ class FlumePlatform {
         this.initialiseDevice(device)
       })
 
+      // Remove any stale accessories that don't appear in the device list
+      this.devicesInHB.forEach(accessory => {
+        if (!deviceList.find(el => accessory.context.deviceId === el.id)) {
+          this.removeAccessory(accessory)
+        }
+      })
+
       // Set up an initial last sync time
       this.lastSync = new Date(Date.now() - this.config.refreshInterval * 60000)
 
@@ -235,7 +244,7 @@ class FlumePlatform {
           accessory.control.externalUpdate(res)
         } catch (err) {
           const eText = this.funcs.parseError(err)
-          this.log.warn(eText)
+          this.log.warn('[%s] %s %s.', accessory.displayName, this.lang.devNotRef, eText)
         }
       })
 

package/lib/utils/constants.js

@@ -7,8 +7,8 @@ module.exports = {
     name: 'Flume',
     username: '',
     password: '',
-    client_id: '',
-    client_secret: '',
+    clientId: '',
+    clientSecret: '',
     refreshInterval: 1,
     threshold: 0,
     disableDeviceLogging: false,

package/lib/utils/lang-en.js

@@ -4,7 +4,6 @@
 
 module.exports = {
   accNotFound: 'accessory not found',
-  accNotReady: 'cannot currently be controlled, see plugin startup logs for any error',
   brand: 'Flume',
   cfgDef: 'is not a valid number so using default of',
   cfgDup: 'will be ignored since another entry with this ID already exists',
@@ -15,10 +14,6 @@ module.exports = {
   cfgRmv: 'is unused and can be removed',
   cfgQts: 'should not have quotes around its entry',
   complete: '✓ Setup complete',
-  curHeat: 'current heating',
-  curState: 'current state',
-  curTarg: 'current target',
-  curTemp: 'current temperature',
   devAdd: 'has been added to Homebridge',
   devInit: 'initialised with id',
   devNotAdd: 'could not be added to Homebridge as',
@@ -29,36 +24,28 @@ module.exports = {
   devNotUpdated: 'could not be updated as',
   devRemove: 'has been removed from Homebridge',
   disabled: 'To change this, set disablePlugin to false',
-  disableHTTP: 'Disabling HTTP client as',
   disabling: 'Disabling plugin',
   hbVersionFail: 'Your version of Homebridge is too low - please update to v1.3',
-  httpRetry: 'Unable to reach Thermobit, retrying in 30 seconds',
+  httpRetry: 'Unable to reach Flume, retrying in 30 seconds',
   initialised: 'Plugin initialised. Setting up accessories...',
   initialising: 'Initialising plugin',
-  labelHeating: 'heating',
-  labelIdle: 'idle',
-  labelMan: 'manual',
-  labelSch: 'schedule',
-  noCreds: 'Thermobit username and/or password not configured',
-  noDevices: 'no data received from Thermobit server whilst obtaining device list',
-  noTokenExists: 'no Thermobit account token exists',
+  noCreds: 'Flume username and/or password and/or client id/secret not configured',
+  noDataReceived: 'No data received from request',
+  noRefreshToken: 'No refresh token has been retrieved',
+  noUserId: 'No user id has been retrieved',
   pluginNotConf: 'Plugin has not been configured',
-  receivingUpdate: 'receiving update',
-  scheduleFailed: 'Program schedule could not be updated as',
-  scheduleInvalid: 'Not updating program schedule as configuration is invalid or incomplete',
-  scheduleUpdated: 'Program schedule successfully updated',
   syncFailed: 'Sync process failed as',
   updateFail: 'could not be updated as',
   zWelcome: [
     "Don't forget to ☆ this plugin on GitHub if you're finding it useful!",
-    'Have a feature request? Visit https://bit.ly/hb-thermobit-issues to ask!',
+    'Have a feature request? Visit https://bit.ly/hb-flume-issues to ask!',
     'Interested in sponsoring this plugin? https://github.com/sponsors/bwp91',
     "Join the plugin's Discord community! https://discord.gg/cMGhNtZ3tW",
     'Thanks for using this plugin, I hope you find it helpful!',
     'This plugin has been made with ♥ by bwp91 from the UK!',
     'Check out my other Homebridge plugins! https://github.com/bwp91',
-    'Have time to give this plugin a review? https://bit.ly/hb-thermobit-review',
-    "This plugin needs it's first ☆ rating on HOOBS! https://bit.ly/hb-thermobit-review",
+    'Have time to give this plugin a review? https://bit.ly/hb-flume-review',
+    "This plugin needs it's first ☆ rating on HOOBS! https://bit.ly/hb-flume-review",
     'Want to see this plugin in your own language? Let me know!'
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-flume",
   "alias": "Flume",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "author": {
     "name": "Ben Potter",
     "email": "bwp91@icloud.com"
@@ -33,6 +33,24 @@
   "bugs": {
     "url": "https://github.com/bwp91/homebridge-flume/issues"
   },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/bwp91"
+    },
+    {
+      "type": "kofi",
+      "url": "https://ko-fi.com/bwp91"
+    },
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/bwp91"
+    },
+    {
+      "type": "paypal",
+      "url": "https://www.paypal.me/BenPotter"
+    }
+  ],
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^0.0.19",
     "axios": "^0.24.0",