 |
 |
This is a second generation Homebridge Dynamic Platform plugin for the Awair family of air quality monitors implemented in TypeScript for Nfarina's Homebridge project. The Awair2 plugin is based on the homebridge-awair plugin developed by Dean L. Young.
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 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 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 select this icon a screen opens with all of the Climate devices in your HomeKit home (second screenshot).
For those with multiple Awair devices, you can optionally list the macAddress of the device (found on the back or bottom of the device) which you want to exclude from HomeKit.
For Awair Omni, battery charge level, charging status, low battery, light level and occupancy detection based on ambient sound level [experimental] are also provided using the Local Sensors capability which is configured in the Awair App (reference screenshot below). Battery Status does not appear as a separate tile in the HomeKit interface. Battery charge level and status will be found in the Status menu for each of the sensors. A low battery indication will be identified as an alert in the HomeKit status section (see third and fourth screenshots).
If you are setting up an Awair unit for the first time, it is recommended that you allow a couple of hours after adding to the iOS Awair App for the unit to calibrate, update firmware if necessary and establish connection to the Awair Cloud. Initially the accessories may show up in Homebridge and HomeKit, however, the data field may be blank. This will correct after the data stream has been established between your Awair device and the Awair Cloud.
Acknowledgment to @Sunoo for the homebridge-philips-air plugin which was used as a reference for implementation of the Awair Dynamic Platform TypeScript plugin.
- Install homebridge, reference Homebridge Wiki
- Install this plugin using:
[sudo] npm install -g homebridge-awair2 - 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 device.
You will need to request access to the Awair Developer Console to obtain your Developer Token (token). You can also request your Developer Token directly through the Awair App on your iPhone. From the App, select 'Awair+' in the lower right hand corner, then select 'Awair APIs', select 'Cloud API' and finally 'Get API Token'.
The Awair Developer API Documentation explains the inner workings of the Awair Developer API, but for the most part is not necessary to use this plugin.
Changelog is available here.
Configuration sample: config-sample.json
Reference Wiki Chapter 3 for additional details.
(*) Introduced with v5.9.0.
| Parameter | Optional? | Description |
|---|---|---|
platform |
The Homebridge Accessory (REQUIRED, must be exactly: Awair2) |
|
token |
Developer Token (REQUIRED, see Installation) above. | |
userType |
Y | The type of user account (Eefault = users/self, options: users/self or orgs/###, where ### is the Awair Organization orgId) |
airQualityMethod |
Y | Air quality calculation method used to define the Air Quality Chracteristic (Default = awair-aqi, options: awair-aqi, awair-pm, awair-score or nowcast-aqi) |
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) |
enableTvocPm25 |
Y | Whether to enable Total VOC and PM2.5 threshold binary sensors. |
tvocThreshold(*) |
Y | Total VOC level at which HomeKit will trigger an alert in µg/m³. (Default = 1000) |
tvocThresholdOff(*) |
Y | Total VOC level at which HomeKit will turn off the trigger alert in µg/m³ 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 µg/m³. (Default = 35) |
pm25ThresholdOff(*) |
Y | The level at which HomeKit will turn off the trigger alert for pm2.5 in µg/m³ 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 µg/m³. (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) |
occupancyRestart |
Y | Omni only - Reinitialize Occupancy detection measurement to determine unoccupied sound level on Homebridge reboot. (Default = false, use historical data) |
enableModes |
Y | Applies to Omni, Awair-r2 & Element - Enables creation of Display Mode and LED Mode accessories. (Default = false) |
logging |
Y | Whether to output logs to the Homebridge logs. (Default = false) |
verbose |
Y | Whether to log results from API data calls. Requires logging to be true. (Default = false) |
development |
Y | Enables Development mode to allow use of test Awair devices lacking end user/Awair OUI formatted Serial numbers. (Default = false) |
ignoredDevices |
Y | 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. |
Reference Wiki for detailed description of Configurion Options.
Reference Wiki for complete list of Resources.