homebridge-airvisual-2
Version:
Homebridge plugin for AirVisual API
110 lines (76 loc) • 4.69 kB
Markdown
# homebridge-airvisual-2
Homebridge plugin for the AirVisual API which allows access to outdoor air quality, humidity, and temperature.
It differs from `homebridge-airvisual` in the following ways:
* Data is fetched and stored on a fixed interval instead of making HTTP requests on demand.
* Added logic to infer PM2.5 density based on AQI (free API plan only)
* Updated to modern ES syntax (requires node 10.18 or newer)
## Installation
1. Install homebridge using the instructions at https://github.com/nfarina/homebridge#installation
2. Install this plugin using: `npm install -g homebridge-airvisual-2`
3. Register for an account and get an API key at https://www.airvisual.com/api
4. Update the Homebridge configuration file
## Configuration
Example config.json:
```js
"accessories": [
{
"accessory": "AirVisual",
"name": "AirVisual",
"api_key": "",
"sensor": "air_quality",
"aqi_standard": "us",
"latitude": ,
"longitude": ,
"city": "",
"state": "",
"country": "",
"ppb_units": ["no2", "o3", "so2"],
"interval": 30,
}
],
```
## Details
Field | Required | Default | Description
:--- | :---: | :---: | :---
`accessory` | yes | `AirVisual` | Must always be `AirVisual`
`name` | yes | `AirVisual` | Can be specified by user
`api_key` | yes | | Obtain from https://www.airvisual.com/api
`sensor` | no | `air_quality` | Must be `air_quality`, `humidity`, or `temperature`
`aqi_standard` | no | `us` | Only applicable if `sensor` is set to `air_quality`, must be `cn` (for China) or `us` (for United States)
`latitude` | no | | See [**Location**](#location) notes below
`longitude` | no | | See [**Location**](#location) notes below
`city` | no | | See [**Location**](#location) notes below
`state` | no | | See [**Location**](#location) notes below
`country` | no | | See [**Location**](#location) notes below
`ppb_units` | no | | See [**Units**](#units) notes below
`interval` | no | `30` | Set the polling interval in minutes
## Location
By default, AirVisual will use IP geolocation to determine the nearest station to get data from (no configuration needed).
Alternatively, GPS coordinates (`latitude` and `longitude`) or a specific city (`city`, `state`, and `country`) can be used.
* GPS coordinates can be found using https://www.latlong.net
* Coordinates must be entered as numbers, not strings
* A specific city, state, and country can be found using https://www.airvisual.com/world
* Browse to the desired city
* Format will be shown as *City > State > Country*
* If both `latitude`, `longitude` and `city`, `state`, `country` are specified; the GPS coordinates will be used.
## Units
If a "Startup" or "Enterprise" API key is used, then AirVisual should return concentration for individual pollutants in units of µg/m3. However, various locations appear to report some pollutants in units of ppb.
These pollutants can be converted to µg/m3, which is required for HomeKit, with the following steps:
1. Use the AirVisual app or website to see the reported units of each pollutant for the desired location.
2. Then use the `ppb_units` configuration option to indicate which pollutants should be converted from ppb to µg/m3.
Only `no2`, `o3`, and `so2` are supported for conversion.
## Miscellaneous
* Homebridge supports multiple instances for accessories; the configuration entry can be duplicated for each location and/or sensor type desired.
* This plugin supports additional characteristics for air quality sensors if a "Startup" or "Enterprise" API key from AirVisual is used.
* The free tier of the API does not provide particle densities, however this plugin will infer the PM2.5 density based on the AQI according to [this table](https://en.wikipedia.org/wiki/Air_quality_index#Computing_the_AQI).
Note that according to API documentation, a city's AQI is based on the "main pollutant" which may or may not be PM2.5. Upgrade your API plan to get correct pollutant data.
* By default the API is queried once every 30 minutes, which is half of AirVisual's station update frequency of once per hour.
* AQI categories are mapped to HomeKit categories as follows. Note that HomeKit will show visual cues on the dashboard for categories "Inferior" and "Poor".
AQI | AQI Category | HomeKit
--------|--------------------------------|-----------
0-50 | Good | Excellent
51-100 | Moderate | Good
101-150 | Unhealthy for Sensitive Groups | Fair
151-200 | Unhealthy | Inferior
201-300 | Very Unhealthy | Poor
301-500 | Hazardous | Poor