Add Omni auto occupancy support

* Update build.yml to only include even numbered releases of node.js [10.x, 12.x, 14.x]
* Update README.MD to provide additional details on adding 'test' devices to 'exclude' list.
* Add experimental support for Omni auto occupancy detection base on minimum sound level detected.

.github/workflows/build.yml

@@ -8,8 +8,8 @@ jobs:
 
     strategy:
       matrix:
-        # the Node.js versions to build on
-        node-version: [10.x, 12.x, 13.x, 14.x]
+        # the Node.js versions to build on (homebridge only supports even-numbered releases)
+        node-version: [10.x, 12.x, 14.x]
 
     steps:
       - uses: actions/checkout@v2

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/).
 
+## v5.5.3
+  * Update build.yml to only include even numbered releases of node.js [10.x, 12.x, 14.x]
+  * Update README.MD to provide additional details on adding 'test' devices to 'exclude' list.
+  * Add experimental support for Omni auto occupancy detection base on minimum sound level detected.
+
 ## v5.5.1 & v5.5.2
   * Update to address build error TS6059: File 'package.json' is not under 'rootDir' '/homebridge-awair2/src'. 'rootDir' is expected to contain all source files.
 

README.md

@@ -1,7 +1,7 @@
 # homebridge-awair2
 This is a second generation Homebridge Dynamic Platform plugin for the Awair family of air quality sensors implemented in TypeScript for Nfarina's [Homebridge project](https://github.com/nfarina/homebridge). The Awair2 plugin is based on the [homebridge-awair](https://github.com/deanlyoung/homebridge-awair#readme) plugin developed by Dean L. Young.
 
-The Awair2 plugin will query your Awair account using a Developer Token to determine your registered Awair devices 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 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 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).
 
@@ -25,7 +25,7 @@ Acknowledgment to @Sunoo for the homebridge-philips-air plugin which was used as
 2. Install this plugin using: `[sudo] npm install -g homebridge-awair2`
 3. Update your configuration file. See the sample below.
 
-The Awair2 plugin queries your Awair account to determine devices that you have registered. This is the same informaton that you have entered via the Awair app on your iOS dev ice.
+The Awair2 plugin queries your Awair account to determine devices that you have registered. This is the same informaton that you have entered via the Awair app on your iOS device.
 
 You will need to request access to the [Awair Developer Console](https://developer.getawair.com) to obtain your Developer Token (`token`).
 
@@ -53,6 +53,7 @@ See [config-sample.json](https://github.com/DMBlakeley/homebridge-awair2/blob/ma
     "carbonDioxideThreshold": 1200,
     "carbonDioxideThresholdOff": 800,
     "vocMw": 72.66578273019740,
+    "autoOccupancy": false,
     "occupancyDetectedLevel": 60,
     "occupancyNotDetectedLevel": 55,
     "logging": false,
@@ -77,13 +78,14 @@ Parameter | Description
 `limit` | Number of consecutive data points returned per request, used for custom averaging of sensor values (OPTIONAL, default = `1` i.e. one `15-min-avg`). Defaults to 1 for  `latest`.
 `carbonDioxideThreshold` | (OPTIONAL, default = `0` [i.e. OFF], the level at which HomeKit will trigger an alert for the CO2 in ppm)
 `carbonDioxideThresholdOff` | (OPTIONAL, default = `0` [i.e. `carbonDioxideThreshold`], 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 lower than `carbonDioxideThreshold`)
-`vocMw` | The Molecular Weight (g/mol) of a reference gas or mixture that you use to convert from ppb to ug/m^3 (OPTIONAL, default = `72.66578273019740`)
-`occupancyDetectedLevel` | (OPTIONAL - Omni only, default = `60`, the level at which HomeKit will indicate room Occupancy is detected based on room sound level in dBA)
-`occupancyDetectedNotLevel` | (OPTIONAL - Omni only, default = `55`, the level at which HomeKit will indicate room Occupancy is not detected based on room sound level in dBA)
+`vocMw` | (OPTIONAL, default = `72.66578273019740`) The Molecular Weight (g/mol) of a reference gas or mixture that you use to convert from ppb to ug/m^3
+`autoOccupancy` | (OPTIONAL - Omni only, default = `false`) Whether to enable Omni auto Occupancy detection based on minimum sound level detected. If enabled, `occupancyDetectedLevel` and `occupancyDetectedNotLevel`are initial values for the detection algorithm.
+`occupancyDetectedLevel` | (OPTIONAL - Omni only, default = `60`) The initial level at which HomeKit will indicate room Occupancy is detected based on room sound level in dBA)
+`occupancyDetectedNotLevel` | (OPTIONAL - Omni only, default = `55`) The initial level at which HomeKit will indicate room Occupancy is not detected based on room sound level in dBA)
 `logging` | Whether to output logs to the Homebridge logs (OPTIONAL, default = `false`)
 `verbose` | Whether to log results from API data calls (OPTIONAL, default = `false`). Requires `logging` to be `true`.
-`development` | Enables Development mode to allow use of 'test' Awair devices lacking production/Awair OUI formatted Serial numbers.
-`ignoredDevices` | Array of Awair device macAddresses to be excluded from HomeKit (OPTIONAL).
+`development` | Enables Development mode to allow use of `test` Awair devices lacking `end user`/Awair OUI formatted Serial numbers.
+`ignoredDevices` | (OPTIONAL) Array of Awair device macAddresses (12 characters in length) to be excluded from HomeKit (OPTIONAL). `End user` devices with begin with Awair OUI "70886B", `test` devices are concatnation of right 12 characters of '00000000000' + deviceId.
 
 
 # Resources

config-sample.json

@@ -19,6 +19,7 @@
 			"carbonDioxideThreshold": 1200,
 			"carbonDioxideThresholdOff": 800,
 			"vocMw": 72.66578273019740,
+			"autoOccupancy": false,
 			"occupancyDetectedLevel": 60,
 			"occupancyNotDetectedLevel": 55,
 			"logging": false,

config.schema.json

@@ -58,17 +58,22 @@
 				"placeholder": 72.66578273019740,
 				"description": "The Molecular Weight (g/mol) of a reference gas or mixture that you use to convert from ppb to ug/m^3."
 			},
+      "autoOccupancy": {
+        "title": "Whether to enable auto Occupancy detection based on minimum sound level.",
+        "type": "boolean",
+        "default": false
+      },
       "occupancyDetectedLevel": {
 				"title": "Omni - Occupancy Threshold",
 				"type": "number",
 				"placeholder": 60,
-				"description": "Omni only - sound pressure level that indicates occupancy."
+				"description": "Omni only - initial sound pressure level that indicates occupancy."
 			},
       "occupancyNotDetectedLevel": {
 				"title": "Omni - Occupancy Threshold Off",
 				"type": "number",
 				"placeholder": 55,
-				"description": "Omni only - sound pressure level that indicates unoccupied."
+				"description": "Omni only - initial sound pressure level that indicates unoccupied."
 			},
       "logging": {
         "title": "Whether to output logs to the Homebridge logs.",
@@ -119,6 +124,7 @@
         "carbonDioxideThreshold",
         "carbonDioxideThresholdOff",
         "vocMw",
+        "autoOccupancy",
         "occupancyDetectedLevel",
         "occupancyNotDetectedLevel",
         "logging",

package.json

@@ -2,7 +2,7 @@
   "private": false,
   "displayName": "Homebridge Awair2",
   "name": "homebridge-awair2",
-  "version": "5.5.2",
+  "version": "5.5.3",
   "description": "HomeKit integration of Awair air purifier as Dynamic Platform.",
   "main": "dist/index.js",
   "scripts": {

src/configTypes.ts

@@ -9,6 +9,7 @@ export type AwairPlatformConfig = {
   carbonDioxideThreshold: number;
   carbonDioxideThresholdOff: number;
   vocMw: number;
+  autoOccupancy: boolean;
   occupancyDetectedLevel: number;
   occupancyNotDetectedLevel: number;
   logging: boolean;

src/index.ts

@@ -401,6 +401,7 @@ class AwairPlatform implements DynamicPlatformPlugin {
 	      accessory.addService(hap.Service.BatteryService, data.name + ' Battery');
 	      accessory.addService(hap.Service.OccupancySensor, data.name + ' Occupancy');
 	      this.omniDetected = true; // set flag for Occupancy detected loop
+	      accessory.context.minsoundlevel = this.occupancyNotDetectedLevel; // context value to track minimum sound level detected
 	    }
 
 	    this.addServices(accessory);
@@ -415,6 +416,7 @@ class AwairPlatform implements DynamicPlatformPlugin {
 	    accessory.context.deviceType = data.deviceType;
 	    if (data.deviceType === 'awair-omni') {
 	      this.omniDetected = true; // set flag for Occupancy detected loop
+	      accessory.context.minsoundlevel = this.occupancyNotDetectedLevel; // context value to track minimum sound level detected
 	    }
 	    accessory.context.deviceUUID = data.deviceUUID;
 	    accessory.context.deviceId = data.deviceId;
@@ -794,6 +796,16 @@ class AwairPlatform implements DynamicPlatformPlugin {
 	      if(this.config.logging && this.config.verbose) {	
 	        this.log('[' + accessory.context.serial + '] spl_a: ' + omniSpl_a);
 	      }
+
+	      if((omniSpl_a < accessory.context.minsoundlevel) && this.config.autoOccupancy) {
+	        accessory.context.minsoundlevel = omniSpl_a;
+	        this.occupancyDetectedLevel = accessory.context.minsoundlevel + 1;
+	        this.occupancyNotDetectedLevel = accessory.context.minsoundlevel + 0.5;
+	        if(this.config.logging) {
+	          this.log('[' + accessory.context.serial + '] notDetectedLevel: ' + this.occupancyNotDetectedLevel 
+							+ 'dBA, DetectedLevel: ' + this.occupancyDetectedLevel + 'dBA');
+	        }
+	      }
 
 	      const occupancyService = accessory.getService(hap.Service.OccupancySensor);