homebridge-airvisual
Homebridge plugin for the AirVisual API which allows access to outdoor air quality, humidity, and temperature.
Installation
- Install homebridge using the instructions at https://github.com/nfarina/homebridge#installation
- Install this plugin using:
npm install -g homebridge-airvisual-2
- Register for an account and get an API key at https://www.airvisual.com/api
- Update the Homebridge configuration file
Configuration
Example config.json:
"accessories": [
{
"accessory": "AirVisual",
"name": "AirVisual",
"api_key": "",
"sensor": "air_quality",
"aqi_standard": "us",
"latitude": ,
"longitude": ,
"city": "",
"state": "",
"country": "",
"ppb_units": ["no2", "o3", "so2"],
"interval": 60,
}
],
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 notes below |
longitude | no | | See Location notes below |
city | no | | See Location notes below |
state | no | | See Location notes below |
country | no | | See Location notes below |
ppb_units | no | | See Units notes below |
interval | no | 60 | 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
-
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:
-
Use the AirVisual app or website to see the reported units of each pollutant for the desired location.
-
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 and PM10 densities based on the AQI according to this table.
-
By default the API is queried once per hour. A 10 minute interval would result in ~5000 requests per month, while the free tier includes 10.000 requests per month.
-
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 |