homebridge-flume 0.3.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to homebridge-flume will be documented in this file.
 
+## 0.7.0 (2021-11-24)
+
+### Added
+
+- `StatusFault` and `StatusLowBattery` characteristics to the `LeakSensor` service
+
+## 0.6.0 (2021-11-24)
+
+### Added
+
+- Leak sensor service
+
+### Changed
+
+- Minimum refresh interval increased to two minutes
+
+## 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
@@ -18,4 +50,4 @@ Converted from accessory plugin to platform plugin
 
 ## 0.1.0 (2021-11-22)
 
-Initial release
+Initial release

package/README.md

@@ -40,7 +40,7 @@
 
 ### Credits
 
-- This is a forked rewrite of the [homebridge-flume-water-sensor](https://www.npmjs.com/package/homebridge-flume-water-sensor) plugin by @weallknowwhoisatfaulthere
+- 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

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."
+        "placeholder": 2,
+        "description": "Number of minutes between updates. Must be 2 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 {
@@ -182,7 +202,37 @@ module.exports = class connectionHTTP {
     }
   }
 
-  async getDeviceInfo (deviceId, fromWhen) {
+  async getDeviceInfo (deviceId) {
+    // Refresh the access token if it has expired already
+    if (Date.now() > this.expiresIn) {
+      await this.renewToken()
+    }
+
+    // Send the request
+    const res = await axios.get(
+      'https://api.flumetech.com/users/' + this.userId + '/devices/' + deviceId,
+      {
+        headers: {
+          Authorization: 'Bearer ' + this.accessToken
+        }
+      }
+    )
+
+    // 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 getDeviceInfo()] %s.', JSON.stringify(res.data))
+    }
+
+    // Parse the response
+    return res.data.data[0]
+  }
+
+  async getWaterInfo (deviceId, fromWhen) {
     // Refresh the access token if it has expired already
     if (Date.now() > this.expiresIn) {
       await this.renewToken()
@@ -212,6 +262,46 @@ 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 getWaterInfo()] %s.', JSON.stringify(res.data))
+    }
+
+    // Parse the response
+    return res.data.data[0]
+  }
+
+  async getLeakInfo (deviceId) {
+    // Refresh the access token if it has expired already
+    if (Date.now() > this.expiresIn) {
+      await this.renewToken()
+    }
+
+    // Send the request
+    const res = await axios.get(
+      'https://api.flumetech.com/users/' + this.userId + '/devices/' + deviceId + '/leaks/active',
+      {
+        headers: {
+          Authorization: 'Bearer ' + this.accessToken
+        }
+      }
+    )
+
+    // 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 getLeakInfo()] %s.', JSON.stringify(res.data))
+    }
+
     // Parse the response
     return res.data.data[0]
   }

package/lib/device/valve.js

@@ -6,30 +6,68 @@ 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
+
+    // Add the leak sensor service if it doesn't exist already
+    this.leakService =
+      this.accessory.getService(this.hapServ.LeakSensor) ||
+      this.accessory.addService(this.hapServ.LeakSensor)
+
+    this.cacheLeak = !!this.leakService.getCharacteristic(this.hapChar.LeakDetected).value
+    this.cacheBatt = !this.leakService.getCharacteristic(this.hapChar.StatusLowBattery).value
+    this.cacheStatus = !this.leakService.getCharacteristic(this.hapChar.StatusFault).value
   }
 
   externalUpdate (params) {
-    // Here we deal with the incoming data
+    // Check the data for leak detection
+    if (
+      this.funcs.hasProperty(params.leakInfo, 'active') &&
+      params.leakInfo.active !== this.cacheLeak
+    ) {
+      this.cacheLeak = params.leakInfo.active
+      this.leakService.updateCharacteristic(this.hapChar.LeakDetected, this.cacheLeak ? 1 : 0)
+      this.log('[%s] current leak status [%sdetected].', this.name, this.cacheLeak ? '' : 'not ')
+    }
+
+    // Check the data for battery level, cacheBatt is true for OK and false for LOW
+    if (
+      this.funcs.hasProperty(params.devInfo, 'battery_level') &&
+      (params.devInfo.battery_level !== 'low') !== this.cacheBatt
+    ) {
+      this.cacheBatt = params.devInfo.battery_level !== 'low'
+      this.leakService.updateCharacteristic(this.hapChar.StatusLowBattery, this.cacheBatt ? 0 : 1)
+      this.log('[%s] current battery [%s].', this.name, this.cacheBatt ? 'ok' : 'low')
+    }
+
+    // Check the data for connectivity, cacheStatus is true for OK and false for NOT CONNECTED
+    if (
+      this.funcs.hasProperty(params.devInfo, 'connected') &&
+      params.devInfo.connected !== this.cacheStatus
+    ) {
+      this.cacheStatus = params.devInfo.connected
+      this.leakService.updateCharacteristic(this.hapChar.StatusFault, this.cacheStatus ? 0 : 1)
+      this.log('[%s] current status [%sconnected].', this.name, this.cacheStatus ? '' : 'not ')
+    }
+
     const usage =
-      params.currentusage && params.currentusage[0] && params.currentusage[0].value
-        ? params.currentusage[0].value
+      params.waterInfo.currentusage &&
+      params.waterInfo.currentusage[0] &&
+      params.waterInfo.currentusage[0].value
+        ? params.waterInfo.currentusage[0].value
         : 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

@@ -77,7 +77,11 @@
   <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
+      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

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)
 
@@ -224,18 +233,23 @@ class FlumePlatform {
 
   async flumeSync () {
     try {
-      const fromWhen = this.lastSync
+      const since = this.lastSync
         .toISOString()
         .substring(0, 19)
         .replace('T', ' ')
       this.devicesInHB.forEach(async accessory => {
         try {
-          const res = await this.httpClient.getDeviceInfo(accessory.context.deviceId, fromWhen)
-          res.fromWhen = fromWhen
-          accessory.control.externalUpdate(res)
+          const toReturn = { since }
+          const devInfo = await this.httpClient.getDeviceInfo(accessory.context.deviceId)
+          toReturn.devInfo = devInfo
+          const waterInfo = await this.httpClient.getWaterInfo(accessory.context.deviceId, since)
+          toReturn.waterInfo = waterInfo
+          const leakInfo = await this.httpClient.getLeakInfo(accessory.context.deviceId)
+          toReturn.leakInfo = leakInfo
+          accessory.control.externalUpdate(toReturn)
         } 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,
@@ -18,12 +18,12 @@ module.exports = {
   },
 
   defaultValues: {
-    refreshInterval: 1,
+    refreshInterval: 2,
     threshold: 0
   },
 
   minValues: {
-    refreshInterval: 1,
+    refreshInterval: 2,
     threshold: 0
   },
 

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 Flume, retrying in 30 seconds',
   initialised: 'Plugin initialised. Setting up accessories...',
   initialising: 'Initialising plugin',
-  labelHeating: 'heating',
-  labelIdle: 'idle',
-  labelMan: 'manual',
-  labelSch: 'schedule',
-  noCreds: 'Flume username and/or password not configured',
-  noDevices: 'no data received from Flume server whilst obtaining device list',
-  noTokenExists: 'no Flume 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.1",
+  "version": "0.7.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",