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