homebridge-airvisual-2

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:

"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 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	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. 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