homebridge-flume 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Change Log
+
+All notable changes to homebridge-flume will be documented in this file.
+
+## 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

package/README.md

@@ -1,36 +1,49 @@
-# homebridge-flume
-
-# Configuration
-
-Configuration sample:
-
-```
-"accessories": [
-  {
-    "accessory": "Flume",
-    "name": "Flume Water Monitor",
-    "username": "user@domain.com",
-    "password": "password",
-    "client_id": "12345678901234567890",
-    "client_secret": "1234567890",
-    "polling_minutes": 1,
-    "handicap": 0.1,
-    "valveType": 3
-  }
-]
-```
-
-Fields:
-
-- "accessory": Must always be "Flume" (required)
-- "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

@@ -1,58 +1,91 @@
 {
   "pluginAlias": "Flume",
-  "pluginType": "accessory",
+  "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "[Flume Water Monitor](https://flumetech.com) plugin for Homebridge.",
+  "customUi": true,
+  "customUiPath": "./lib/homebridge-ui",
+  "headerDisplay": "<p align=\"center\">For help and support please visit our <a href=\"https://github.com/bwp91/homebridge-flume/wiki\">GitHub Wiki</a>. We hope you find this plugin useful!</p>",
   "schema": {
     "type": "object",
     "properties": {
       "name": {
-        "title": "Accessory Name",
+        "title": "Plugin Name",
         "type": "string",
-        "required": true,
-        "default": "Flume Water Monitor",
-        "description": "The name used for the Flume water monitor in HomeKit"
+        "default": "Flume"
       },
       "username": {
         "title": "Username",
         "type": "string",
         "required": true,
-        "description": "Your username for acessing the Flume site at https://portal.flumetech.com/ (required)"
+        "description": "Your username for accessing the Flume site at https://portal.flumetech.com"
       },
       "password": {
         "title": "Password",
         "type": "string",
         "required": true,
-        "description": "Your password for acessing the Flume site (required)"
+        "description": "Your password for accessing the Flume site"
       },
       "client_id": {
         "title": "Client ID",
         "type": "string",
         "placeholder": "12345678901234567890",
         "required": true,
-        "description": "Your Client ID for API access, found in Settings on the Flume site (required)"
+        "description": "Your Client ID for API access, found in Settings on the Flume site"
       },
       "client_secret": {
         "title": "Client Secret",
         "type": "string",
         "placeholder": "1234567890",
         "required": true,
-        "description": "Your Client Secret for API access, found in Settings on the Flume site (required)"
+        "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",
-        "default": "1",
-        "required": false,
-        "description": "Number of minutes between updates. Defaults to 1 minute. API has a cap of 120 calls per hour. (optional)"
+        "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": "float",
-        "default": "0.0",
-        "required": false,
-        "description": "Set to ignore a steady water draw below this value. Defaults to zero (0.0) gallons. (optional)"
-      }
+        "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

@@ -0,0 +1,218 @@
+/* jshint node: true, esversion: 10, -W014, -W033 */
+/* eslint-disable new-cap */
+'use strict'
+
+const axios = require('axios')
+const jwtDecode = require('jwt-decode')
+
+module.exports = class connectionHTTP {
+  constructor (platform) {
+    // Create variables usable by the class
+    this.consts = platform.consts
+    this.debug = platform.config.debug
+    this.funcs = platform.funcs
+    this.lang = platform.lang
+    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
+  }
+
+  async obtainToken () {
+    try {
+      // Generate the JSON data to send
+      const body = {
+        grant_type: 'password',
+        client_id: this.client_id,
+        client_secret: this.client_secret,
+        username: this.username,
+        password: this.password
+      }
+      const now = Date.now()
+
+      // Perform the HTTP request
+      const res = await axios.post('https://api.flumetech.com/oauth/token', body, {
+        timeout: 10000
+      })
+
+      // Check to see we got a response
+      if (!res.data) {
+        throw new Error(this.lang.noToken)
+      }
+
+      /*
+        {
+          success: true,
+          code: 602,
+          message: 'Request OK',
+          http_code: 200,
+          http_message: 'OK',
+          detailed: null,
+          data: [
+            {
+              token_type: 'bearer',
+              access_token: '',
+              expires_in: 604800,
+              refresh_token: ''
+            }
+          ],
+          count: 1,
+          pagination: null
+        }
+      */
+
+      // Make the token available in other functions
+      this.accessToken = res.data.data[0].access_token
+      this.refreshToken = res.data.data[0].refresh_token
+      this.expiresIn = now + res.data.data[0].expires_in
+
+      // Obtain the user ID
+      this.userId = jwtDecode(this.accessToken).user_id
+
+      /*
+        {
+          user_id: 0000,
+          type: 'USER',
+          scope: [ 'read:personal', 'update:personal', 'query:personal' ],
+          iat: 0000000000,
+          exp: 0000000000,
+          iss: 'flume_oauth',
+          sub: ''
+        }
+      */
+    } 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)
+        await this.funcs.sleep(30000)
+        return await this.login()
+      } else {
+        throw new Error('[HTTP obtainToken()] ' + err.message)
+      }
+    }
+  }
+
+  async renewToken () {
+    try {
+      // Generate the JSON data to send
+      const body = {
+        grant_type: 'refresh_token',
+        client_id: this.client_id,
+        client_secret: this.client_secret,
+        refresh_token: this.refreshToken
+      }
+      const now = Date.now()
+
+      // Perform the HTTP request
+      const res = await axios.post('https://api.flumetech.com/oauth/token', body, {
+        timeout: 10000
+      })
+
+      // Check to see we got a response
+      if (!res.data) {
+        throw new Error(this.lang.noToken)
+      }
+
+      /*
+          {
+            success: true,
+            code: 602,
+            message: 'Request OK',
+            http_code: 200,
+            http_message: 'OK',
+            detailed: null,
+            data: [
+              {
+                token_type: 'bearer',
+                access_token: '',
+                expires_in: 604800,
+                refresh_token: ''
+              }
+            ],
+            count: 1,
+            pagination: null
+          }
+        */
+
+      // Make the token available in other functions
+      this.accessToken = res.data.data[0].access_token
+      this.refreshToken = res.data.data[0].refresh_token
+      this.expiresIn = now + res.data.data[0].expires_in
+    } 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)
+        await this.funcs.sleep(30000)
+        return await this.login()
+      } else {
+        throw new Error('[HTTP refreshToken()] ' + err.message)
+      }
+    }
+  }
+
+  async getDevices () {
+    try {
+      // Check we have a user id
+      if (!this.userId) {
+        throw new Error('No user id has been retrieved')
+      }
+
+      // Perform the HTTP request
+      const res = await axios.get('https://api.flumetech.com/users/' + this.userId + '/devices', {
+        headers: { Authorization: 'Bearer ' + this.accessToken },
+        timeout: 10000
+      })
+
+      // Check to see we got a response
+      if (!res.data) {
+        throw new Error('No data received')
+      }
+
+      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)
+        await this.funcs.sleep(30000)
+        return await this.login()
+      } else {
+        throw new Error('[HTTP getDevices()] ' + err.message)
+      }
+    }
+  }
+
+  async getDeviceInfo (deviceId, fromWhen) {
+    // Refresh the access token if it has expired already
+    if (Date.now() > this.expiresIn) {
+      await this.renewToken()
+    }
+
+    // Generate the JSON data to send
+    const body = {
+      queries: [
+        {
+          request_id: 'currentusage',
+          bucket: 'MIN',
+          since_datetime: fromWhen,
+          operation: 'SUM',
+          units: 'GALLONS'
+        }
+      ]
+    }
+
+    // Send the request
+    const res = await axios.post(
+      'https://api.flumetech.com/users/' + this.userId + '/devices/' + deviceId + '/query',
+      body,
+      {
+        headers: {
+          Authorization: 'Bearer ' + this.accessToken
+        }
+      }
+    )
+
+    // Parse the response
+    return res.data.data[0]
+  }
+}

package/lib/device/valve.js

@@ -0,0 +1,38 @@
+/* jshint node: true, esversion: 10, -W014, -W033 */
+/* eslint-disable new-cap */
+'use strict'
+
+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.name = accessory.displayName
+    this.platform = platform
+    this.refreshInterval = platform.config.refreshInterval
+  }
+
+  externalUpdate (params) {
+    // Here we deal with the incoming data
+    const usage =
+      params.currentusage && params.currentusage[0] && params.currentusage[0].value
+        ? params.currentusage[0].value
+        : 0
+    if (usage > this.threshold) {
+      this.log(
+        '[%s] %s - [%s] gallons within the last [%s] minutes.',
+        this.name,
+        'usage detected',
+        usage,
+        this.refreshInterval
+      )
+    }
+  }
+}

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

@@ -0,0 +1,162 @@
+<div id="pageIntro" class="text-center" style="display: none;">
+  <p class="lead">Thank you for installing <strong>homebridge-flume</strong></p>
+  <p>
+    You will need your Flume username, password, client ID and secret to continue
+  </p>
+  <button type="button" class="btn btn-primary" id="introContinue">Continue &rarr;</button>
+</div>
+<div
+  id="menuWrapper"
+  class="btn-group w-100 mb-0"
+  role="group"
+  aria-label="UI Menu"
+  style="display: none;"
+>
+  <button type="button" class="btn btn-primary ml-0" id="menuSettings">Settings</button>
+  <button type="button" class="btn btn-primary mr-0" id="menuHome">Support</button>
+</div>
+<div
+  id="disabledBanner"
+  class="alert alert-secondary mb-0 mt-3"
+  role="alert"
+  style="display: none;"
+>
+  Plugin is currently disabled
+  <button id="disabledEnable" type="button" class="btn btn-link p-0 m-0 float-right">Enable</button>
+</div>
+<div id="pageSupport" class="mt-4" style="display: none;">
+  <p class="text-center lead">Thank you for using <strong>homebridge-flume</strong></p>
+  <p class="text-center">The links below will take you to our GitHub wiki</p>
+  <h4>Setup</h4>
+  <ul>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/wiki/Installation" target="_blank"
+        >Installation</a
+      >
+    </li>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/wiki/Configuration" target="_blank"
+        >Configuration</a
+      >
+    </li>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/wiki/Beta-Version" target="_blank"
+        >Beta Version</a
+      >
+    </li>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/wiki/Node-Version" target="_blank"
+        >Node Version</a
+      >
+    </li>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/wiki/Uninstallation" target="_blank"
+        >Uninstallation</a
+      >
+    </li>
+  </ul>
+  <h4>Help/About</h4>
+  <ul>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/wiki/Common-Errors" target="_blank"
+        >Common Errors</a
+      >
+    </li>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/issues/new/choose" target="_blank"
+        >Support Request</a
+      >
+    </li>
+    <li>
+      <a href="https://github.com/bwp91/homebridge-flume/blob/latest/CHANGELOG.md" target="_blank"
+        >Changelog</a
+      >
+    </li>
+    <li><a href="https://github.com/sponsors/bwp91" target="_blank">About Me</a></li>
+  </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.
+    </li>
+  </ul>
+  <h4>Disclaimer</h4>
+  <ul>
+    <li>
+      I am in no way affiliated with Flume and this plugin is a personal project that I maintain in
+      my free time.
+    </li>
+    <li>Use this plugin entirely at your own risk - please see licence for more information.</li>
+  </ul>
+</div>
+<script>
+  ;(async () => {
+    try {
+      const currentConfig = await homebridge.getPluginConfig()
+      showIntro = () => {
+        const introContinue = document.getElementById('introContinue')
+        introContinue.addEventListener('click', () => {
+          homebridge.showSpinner()
+          document.getElementById('pageIntro').style.display = 'none'
+          document.getElementById('menuWrapper').style.display = 'inline-flex'
+          showSettings()
+          homebridge.hideSpinner()
+        })
+        document.getElementById('pageIntro').style.display = 'block'
+      }
+      showSupport = () => {
+        homebridge.showSpinner()
+        homebridge.hideSchemaForm()
+        document.getElementById('menuHome').classList.add('btn-elegant')
+        document.getElementById('menuHome').classList.remove('btn-primary')
+        document.getElementById('menuSettings').classList.remove('btn-elegant')
+        document.getElementById('menuSettings').classList.add('btn-primary')
+        document.getElementById('pageSupport').style.display = 'block'
+        homebridge.hideSpinner()
+      }
+      showSettings = () => {
+        homebridge.showSpinner()
+        document.getElementById('menuHome').classList.remove('btn-elegant')
+        document.getElementById('menuHome').classList.add('btn-primary')
+        document.getElementById('menuSettings').classList.add('btn-elegant')
+        document.getElementById('menuSettings').classList.remove('btn-primary')
+        document.getElementById('pageSupport').style.display = 'none'
+        homebridge.showSchemaForm()
+        homebridge.hideSpinner()
+      }
+      showDisabledBanner = () => {
+        document.getElementById('disabledBanner').style.display = 'block'
+      }
+      enablePlugin = async () => {
+        homebridge.showSpinner()
+        document.getElementById('disabledBanner').style.display = 'none'
+        currentConfig[0].disablePlugin = false
+        await homebridge.updatePluginConfig(currentConfig)
+        await homebridge.savePluginConfig()
+        homebridge.hideSpinner()
+      }
+      menuHome.addEventListener('click', () => showSupport())
+      menuSettings.addEventListener('click', () => showSettings())
+      disabledEnable.addEventListener('click', () => enablePlugin())
+      if (currentConfig.length) {
+        document.getElementById('menuWrapper').style.display = 'inline-flex'
+        showSettings()
+        if (currentConfig[0].disablePlugin) {
+          showDisabledBanner()
+        }
+      } else {
+        currentConfig.push({ name: 'Flume' })
+        await homebridge.updatePluginConfig(currentConfig)
+        showIntro()
+      }
+    } catch (err) {
+      homebridge.toast.error(err.message, 'Error')
+    } finally {
+      homebridge.hideSpinner()
+    }
+  })()
+</script>

package/lib/homebridge-ui/server.js

@@ -0,0 +1,14 @@
+/* jshint node: true, esversion: 10, -W014, -W033 */
+/* eslint-disable new-cap */
+'use strict'
+
+const { HomebridgePluginUiServer } = require('@homebridge/plugin-ui-utils')
+
+class PluginUiServer extends HomebridgePluginUiServer {
+  constructor () {
+    super()
+    this.ready()
+  }
+}
+
+;(() => new PluginUiServer())()