Merge pull request #250 from DMBlakeley/beta

Add binary limit switches for VOC and PM2.5

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/).
 
+## v5.9.2
+* [Housekeeping] Added explicit return types for all functions. Added explicit `return` to close all functions as appropriate.
+* [Improvement] Refactored `updateAirQualityData` function for cleaner operation. Updated `axios.get` syntax.
+* [Bug] Corrected syntax of `voc` and `pm25` cases in `updateAirQualityData` function to correctly use `getCharacteristic` for current `value`.
+
+## v5.9.1
+* [Housekeeping] Update node_module dependencies to latest versions.
+* [Security] Update `follow-redirects` to version 1.14.7 to address CVE-2022-0155 security advisory.
+
+## v5.9.0
+* [Enhancement] Add binary limit switches for VOC and PM2.5. The switches are implemented as dummy `occupancy sensors` and can be used to trigger HomeKit automations.
+* <b><u>NOTE</u>:</b> Awair device(s) need to be deleted from Homebridge cache followed by Homebridge restart in order to add VOC and PM2.5 limit switch capability. This also will require that the Awair device(s) be reconfigured in HomeKit including room location and automations.
+* [Housekeeping] Typescript syntax and readability improvements.
+
 ## v5.8.14
 * Updates to `index.ts`, `package.json`, and `package-lock.json` for compatibility with `eslint v8.50` and `@typescript-eslint v5.7.0`.
 

README.md

@@ -13,18 +13,24 @@ This is a second generation Homebridge Dynamic Platform plugin for the Awair fam
 ---
 
 <u><h3 align=center>NOTE:</h3></u>
-When migrating from `homebridge-awair` to `homebridge-awair2` or from `v5.6.4` to `v5.7.x` please first uninstall `homebridge-awair` (copy your Developer Token first), restart Homebridge to clear 'homebridge-awair2' cached accessories, install `homebridge-awair2`, add your Developer Token to configuration, and finally restart Homebridge one more time.
+When migrating from `homebridge-awair` to `homebridge-awair2` or from `v5.8.14` to `v5.9.x` please first uninstall `homebridge-awair` (copy your Developer Token first), restart Homebridge to clear 'homebridge-awair2' cached accessories, install `homebridge-awair2`, add your Developer Token to configuration, and finally restart Homebridge one more time. 
+
+Alternately you may remove your Awair accessory from the Homebridge single device cache found in Homebridge Settings followed by Homebridge restart. Display and LED mode accessories do not need to be removed.
+
+With either method you will need to check that your Awair device is assigned to the correct HomeKit room and verify that HomeKit Automations which use your Awair device are correct.
 
 ---
 
-The Awair2 plugin will query your Awair account using a Developer Token to determine your registered Awair devices which were setup through the Awair app on your iOS device. While running, the plugin will fetch current sensor conditions for each Awair device (e.g. Awair 1st Edition, Awair Glow, Awair Mint, Awair Omni, Awair 2nd Edition, Awair Glow C, or Awair Element) and provide sensor status and value (e.g. temperature, humidity, carbon dioxide, TVOC, dust/PM2.5/PM10, Omni lux, and Omni battery) to HomeKit. You can look at the current Awair information via HomeKit enabled Apps on your iOS device or even ask Siri for them.
+The Awair2 plugin will query your Awair account using a Developer Token to determine registered Awair devices which were setup through the Awair app on your iOS device. While running, the plugin will fetch current sensor conditions for each Awair device (e.g. Awair 1st Edition, Awair Glow, Awair Mint, Awair Omni, Awair 2nd Edition, Awair Glow C, or Awair Element) and provide sensor status and value (e.g. temperature, humidity, carbon dioxide, TVOC, dust/PM2.5/PM10, Omni lux, and Omni battery) to HomeKit. You can look at the current Awair information via HomeKit enabled Apps on your iOS device or even ask Siri for them.
 
 The plugin will fetch new data based on selected `endpoint` and User Account tier. For 'Hobbyist' tier, `15-min-avg` endpoint samples every 15 minutes, `5-min-avg` every 5 minutes, `latest` every 5 minutes and `raw` every 3.3 minutes (200 seconds). The main difference between the `latest` and `raw` endpoints is that you can define a `limit` (i.e. number of consecutive data points) for the `raw` endpoint, in order to create your own averaging (e.g. `.../raw?limit=12` for a 2 minute average.
 
-v5.7.x of the plugin introduces control of the Awair device display for Awair Omni, Awair r2, and Awair Element. Reference Wiki for details and examples of HomeKit automations for this feature.
+v5.7.x of the plugin introduced control of the Awair device display for Awair Omni, Awair r2, and Awair Element. Reference Wiki for details and examples of HomeKit automations for this feature.
+
+v5.9.x of the plugin introduced binary limit switches for VOC and PM2.5. The switches are implemented as dummy `occupancy sensors` and can be used to trigger HomeKit automations.
 
 With iOS14, the icons and status have been refined in the iOS/iPadOS/macOS Home app. 
-, temperature and humidity are grouped under a single "climate" status icon at the top of the HomeKit screen (first screenshots below). If you touch this icon a screen opens with all of the Climate devices in your HomeKit home (second screenshot).
+, temperature and humidity are grouped under a single "climate" status icon at the top of the HomeKit screen (first screenshots below). If you select this icon a screen opens with all of the Climate devices in your HomeKit home (second screenshot).
 
 ![iOS14 Screenshots](https://github.com/DMBlakeley/homebridge-awair2/blob/master/screenshots/Image.png)
 
@@ -61,40 +67,14 @@ Changelog is available [here](https://github.com/DMBlakeley/homebridge-awair2/bl
 
 # Plugin Configuration
 
-Configuration sample:
-
-See [config-sample.json](https://github.com/DMBlakeley/homebridge-awair2/blob/master/config-sample.json)
-
-```
-"platforms": [
-  {
-    "platform": "Awair2",
-    "token": "AAA.AAA.AAA",
-    "userType": "users/self",
-    "airQualityMethod": "awair-aqi",
-    "endpoint": "15-min-avg",
-    "limit": 1,
-    "carbonDioxideThreshold": 1000,
-    "carbonDioxideThresholdOff": 800,
-    "vocMw": 72.66578273019740,
-    "occupancyDetection": false,
-    "occupancyOffset": 2,
-    "occupancyRestart": false,
-    "enableModes": false,
-    "logging": false,
-    "verbose": false,
-    "development": false,
-    "ignoredDevices": [
-      "70886Bxxxxxx"
-    ]
-  }
-]
-```
+Configuration sample: [config-sample.json](https://github.com/DMBlakeley/homebridge-awair2/blob/master/config-sample.json)
 
 ## Descriptions
 
 Reference [Wiki Chapter 3](https://github.com/DMBlakeley/homebridge-awair2/wiki/3.-Awair2-Configuration-Options) for additional details.
 
+(*) Introduced with v5.9.0.
+
 Parameter | Optional? | Description
 :-- | :----: | :---
 `platform` |  | The Homebridge Accessory (REQUIRED, must be exactly: `Awair2`)
@@ -104,7 +84,11 @@ Parameter | Optional? | Description
 `endpoint` | Y | The `/air-data/` endpoint to use (Default = `15-min-avg`, options: `15-min-avg`, `5-min-avg`, `raw` or `latest`)
 `limit` | Y | Number of consecutive data points returned per request, used for custom averaging of sensor values (Default = `1` i.e. one `15-min-avg`). Defaults to 1 for  `latest`.
 `carbonDioxideThreshold` | Y | The level at which HomeKit will trigger an alert for the CO2 in ppm. (Default = `1000`)
-`carbonDioxideThresholdOff` | Y | The level at which HomeKit will turn off the trigger alert for the CO2 in ppm, to ensure that it doesn't trigger on/off too frequently choose a number less than `carbonDioxideThreshold`. (Default = `800`)
+`carbonDioxideThresholdOff` | Y | The level at which HomeKit will turn off the trigger alert for the CO2 in ppm, to ensure that it doesn't trigger on/off too frequently. Choose a number less than `carbonDioxideThreshold`. (Default = `800`)
+`tvocThreshold`(*) | Y | Total VOC level at which HomeKit will trigger an alert in &micro;g/m&sup3;. (Default = `1000`)
+`tvocThresholdOff`(*) | Y | Total VOC level at which HomeKit will turn off the trigger alert in &micro;g/m&sup3; to ensure that it doesn't trigger on/off too frequently. Choose a number less than `tvocThreshold`. (Default = `800`)
+`pm25Threshold`(*) | Y | The level at which HomeKit will trigger an alert for PM2.5 in &micro;g/m&sup3;. (Default = `35`)
+`pm25ThresholdOff`(*) | Y | The level at which HomeKit will turn off the trigger alert for pm2.5 in &micro;g/m&sup3; to ensure that it doesn't trigger on/off too frequently. Choose a number less than `pm25Threshold`. (Default = `20`)
 `vocMw` | Y | The Molecular Weight (g/mol) of a reference gas or mixture that you use to convert from ppb to &micro;g/m&sup3;. (Default = `72.66578273019740`)
 `occupancyDetection` | Y | Omni Only - Enables Omni occupancy detection based on minimum environmental sound level detected. (Default = `false`)
 `occupancyOffset` | Y | Omni Only - Used when `occupancy detection` enabled. Offset value in dBA above background sound level to set `not occupied` level, `occupied` is 0.5dBA higher. (Default = `2`) 

config-sample.json

@@ -18,6 +18,10 @@
 			"limit": 1,
 			"carbonDioxideThreshold": 1000,
 			"carbonDioxideThresholdOff": 800,
+			"tvocThreshold": 1000,
+			"tvocThresholdOff": 800,
+			"pm25Threshold": 35,
+			"pm25ThresholdOff": 20,
 			"vocMw": 72.66578273019740,
 			"occupancyDetection": false,
 			"occupancyOffset": 2,

config.schema.json

@@ -2,7 +2,7 @@
   "pluginAlias": "Awair2",
   "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "Awair plug-in for [Homebridge](https://github.com/nfarina/homebridge) using the native Awair API.",
+  "headerDisplay": "Awair plug-in for [Homebridge](https://github.com/nfarina/homebridge) using the native Awair Cloud and Local APIs.",
   "footerDisplay": "Reference [Installation Instructions](https://github.com/DMBlakeley/homebridge-awair2#readme) for details on determining 'Developer Token'.",
   "schema": {
     "type": "object",
@@ -50,13 +50,37 @@
         "title": "Carbon Dioxide Threshold - On",
         "type": "integer",
         "placeholder": 1000,
-        "description": "The CO2 level at which HomeKit will turn ON the trigger alert for the CO2 in ppm. Default = '1000'."
+        "description": "The CO2 level in ppm at which HomeKit will turn ON the trigger alert for the CO2. Default = '1000'."
       },
       "carbonDioxideThresholdOff": {
         "title": "Carbon Dioxide Threshold - Off",
         "type": "integer",
         "placeholder": 800,
-        "description": "The CO2 level at which HomeKit will turn OFF the trigger alert for the CO2 in ppm, to ensure that it doesn't trigger on/off too frequently. Must be a number lower than 'carbonDioxideThreshold'. Default = '800'."
+        "description": "The CO2 level in ppm at which HomeKit will turn OFF the trigger alert for the CO2 to ensure that it doesn't trigger on/off too frequently. Must be a number lower than 'carbonDioxideThreshold'. Default = '800'."
+      },
+      "tvocThreshold": {
+        "title": "Total VOC Threshold - On",
+        "type": "integer",
+        "placeholder": 1000,
+        "description": "Total VOC level in µg/m³ at which HomeKit will turn ON the trigger alert for Total VOC. Default = '1000'."
+      },
+      "tvocThresholdOff": {
+        "title": "Total VOC Threshold - Off",
+        "type": "integer",
+        "placeholder": 800,
+        "description": "Total VOC level in µg/m³ at which HomeKit will turn OFF the trigger alert for the Total VOC to ensure that it doesn't trigger on/off too frequently. Must be a number lower than 'tvocThreshold'. Default = '800'."
+      },
+      "pm25Threshold": {
+        "title": "PM2.5 Threshold - On",
+        "type": "integer",
+        "placeholder": 35,
+        "description": "The PM2.5 level in µg/m³ at which HomeKit will turn ON the trigger alert for the PM2.5. Default = '35'."
+      },
+      "pm25ThresholdOff": {
+        "title": "PM2.5 Threshold - Off",
+        "type": "integer",
+        "placeholder": 20,
+        "description": "The PM2.5 level in µg/m³ at which HomeKit will turn OFF the trigger alert for the PM2.5 to ensure that it doesn't trigger on/off too frequently. Must be a number lower than 'pm25Threshold'. Default = '20'."
       },
       "vocMw": {
         "title": "Reference Gas Molecular Weight",
@@ -73,7 +97,7 @@
       "occupancyOffset": {
         "title": "Omni Occupancy decibels Offset - used when occupancyDetection enabled.",
         "type": "number",
-        "default": 2.0,
+        "placeholder": 2.0,
         "multipleOf": 0.5,
         "description": "Omni only - used when `occupancy detection` enabled. Offset value in dBA above detected background sound level to set upper level for `not occupied`. The lower level for `occupied` is an additional 0.5dBA higher. See Wiki for further explanation. Default = '2'.",
         "condition": {
@@ -84,7 +108,7 @@
         "title": "Omni Reset Occupancy Status - reinitialize Occupancy detection measurement on Homebridge reboot.",
         "type": "boolean",
         "default": false,
-        "description": "Omni only - reinitialize Occupancy detection measurement to determine unoccupied sound level on Homebridge reboot.",
+        "description": "Omni only - reinitialize Occupancy detection measurement to determine unoccupied sound level on Homebridge boot or restart.",
         "condition": {
           "functionBody": "return model.occupancyDetection === true;"
         }
@@ -145,6 +169,10 @@
         "limit",
         "carbonDioxideThreshold",
         "carbonDioxideThresholdOff",
+        "tvocThreshold",
+        "tvocThresholdOff",
+        "pm25Threshold",
+        "pm25ThresholdOff",
         "vocMw",
         "occupancyDetection",
         "occupancyOffset",

package.json

@@ -2,7 +2,7 @@
   "private": false,
   "displayName": "Homebridge Awair2",
   "name": "homebridge-awair2",
-  "version": "5.8.14",
+  "version": "5.9.2",
   "description": "HomeKit integration of Awair air quality monitor as Dynamic Platform.",
   "main": "dist/index.js",
   "scripts": {
@@ -62,6 +62,7 @@
     "typescript": "^4.0.2"
   },
   "dependencies": {
-    "axios": "^0.24.0"
+    "axios": "^0.24.0",
+    "follow-redirects": "^1.14.7"
   }
 }

src/configTypes.ts

@@ -8,6 +8,10 @@ export type AwairPlatformConfig = {
   limit: number;
   carbonDioxideThreshold: number;
   carbonDioxideThresholdOff: number;
+  tvocThreshold: number;
+  tvocThresholdOff: number;
+  pm25Threshold: number;
+  pm25ThresholdOff: number;
   vocMw: number;
   occupancyDetection: boolean;
   occupancyOffset: number;