homebridge-flume 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,10 +2,26 @@
 
 All notable changes to homebridge-flume will be documented in this file.
 
+## 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
+
 ## 0.2.0 (2021-11-22)
 
 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",
-  "polling_minutes": 1,
-  "handicap": 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)
-- "polling_minutes": Number of minutes between updates. Defaults to 1 minute. API has a cap of 120 calls per hour. (optional)
-- "handicap": 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

@@ -39,18 +39,47 @@
         "required": true,
         "description": "Your Client Secret for API access, found in Settings on the Flume site"
       },
-      "polling_minutes": {
-        "title": "Update Interval",
+      "refreshInterval": {
+        "title": "Refresh interval",
         "type": "integer",
         "placeholder": 1,
         "description": "Number of minutes between updates. API has a cap of 120 calls per hour."
       },
-      "handicap": {
+      "threshold": {
         "title": "Adjustment for False Positives",
         "type": "number",
         "placeholder": 0,
         "description": "Set to ignore a steady water draw below this value (gallons)."
+      },
+      "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."
       }
     }
-  }
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Required Settings",
+      "items": ["username", "password", "client_id", "client_secret"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Optional Settings",
+      "description": "Optional settings for the plugin, including global logging settings.",
+      "expandable": true,
+      "items": ["refreshInterval", "threshold", "disableDeviceLogging", "debug", "disablePlugin"]
+    }
+  ]
 }

package/lib/connection/http.js

@@ -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)
       }
 
       /*
@@ -84,7 +84,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 {
@@ -111,7 +111,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)
       }
 
       /*
@@ -142,11 +142,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)
       }
     }
   }
@@ -155,7 +155,7 @@ module.exports = class connectionHTTP {
     try {
       // Check we have a user id
       if (!this.userId) {
-        throw new Error('No user id has been retrieved')
+        throw new Error(this.lang.noUserId)
       }
 
       // Perform the HTTP request
@@ -166,14 +166,14 @@ 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)
       }
 
       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 +212,11 @@ module.exports = class connectionHTTP {
       }
     )
 
+    // Check to see we got a response
+    if (!res.data) {
+      throw new Error(this.lang.noDataReceived)
+    }
+
     // Parse the response
     return res.data.data[0]
   }

package/lib/device/valve.js

@@ -8,7 +8,7 @@ module.exports = class deviceValve {
     this.accessory = accessory
     this.disableDeviceLogging = platform.config.disableDeviceLogging
     this.funcs = platform.funcs
-    this.handicap = platform.config.handicap
+    this.threshold = platform.config.threshold
     this.hapChar = platform.api.hap.Characteristic
     this.hapErr = platform.api.hap.HapStatusError
     this.hapServ = platform.api.hap.Service
@@ -16,7 +16,7 @@ module.exports = class deviceValve {
     this.log = platform.log
     this.name = accessory.displayName
     this.platform = platform
-    this.polling_minutes = platform.config.polling_minutes
+    this.refreshInterval = platform.config.refreshInterval
   }
 
   externalUpdate (params) {
@@ -25,13 +25,12 @@ module.exports = class deviceValve {
       params.currentusage && params.currentusage[0] && params.currentusage[0].value
         ? params.currentusage[0].value
         : 0
-    if (usage > this.handicap) {
+    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.polling_minutes
+        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

@@ -106,7 +106,7 @@ class FlumePlatform {
           }
           this.config[key] = val === 'false' ? false : !!val
           break
-        case 'handicap': {
+        case 'threshold': {
           if (typeof v === 'string') {
             logQuotes(key)
           }
@@ -122,7 +122,7 @@ class FlumePlatform {
         case 'platform':
         case 'plugin_map':
           break
-        case 'polling_minutes': {
+        case 'refreshInterval': {
           if (typeof val === 'string') {
             logQuotes(key)
           }
@@ -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,14 +186,21 @@ 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.polling_minutes * 60000)
+      this.lastSync = new Date(Date.now() - this.config.refreshInterval * 60000)
 
       // Perform a first sync and setup the refresh interval
       this.flumeSync()
       this.refreshInterval = setInterval(
         () => this.flumeSync(),
-        this.config.polling_minutes * 60000
+        this.config.refreshInterval * 60000
       )
 
       // Log that the plugin setup has been successful with a welcome message
@@ -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

@@ -9,8 +9,8 @@ module.exports = {
     password: '',
     client_id: '',
     client_secret: '',
-    polling_minutes: 1,
-    handicap: 0,
+    refreshInterval: 1,
+    threshold: 0,
     disableDeviceLogging: false,
     debug: false,
     disablePlugin: false,
@@ -18,13 +18,13 @@ module.exports = {
   },
 
   defaultValues: {
-    polling_minutes: 1,
-    handicap: 0
+    refreshInterval: 1,
+    threshold: 0
   },
 
   minValues: {
-    polling_minutes: 1,
-    handicap: 0
+    refreshInterval: 1,
+    threshold: 0
   },
 
   httpRetryCodes: ['ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'ECONNABORTED']

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,27 @@ 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',
+  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.2.0",
+  "version": "0.4.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",