JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 35
  • Score
    100M100P100Q102584F
  • License ISC

The AirNow plugin allows you to monitor the current AirQuality for your Zip Code from HomeKit and Siri.

Package Exports

  • @homebridge-plugins/homebridge-air
  • @homebridge-plugins/homebridge-air/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@homebridge-plugins/homebridge-air) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

homebridge-verified

Homebridge Air

The Homebridge Air plugin allows you monitor the current AirQuality for your Zip Code from HomeKit and Siri.

Installation

  1. Search for "Air" on the plugin screen of Homebridge Config UI X.
  2. Click Install.

Configuration

  1. Login / create an account at https://www.airnow.gov/ or at https://aqicn.org/api/ as applicable for your location

  1. Select your Provider: AirNow or Apicn
  2. Enter your AirNow.gov or Aqicn API Key
  3. Enter your City and Latitude / Longitude (4 decimal places is sufficient). Note that City may be ambiguous, so you should always enter Latitude and Longitude for location accuracy
  4. Click Save
  5. Restart Homebridge

Supported Air Quality Providers

Currently supports AQI Services:

Depending on where exactly you would like to monitor AQI, one service may be more appropriate than the other.

Supported Air Quality Features

This plugin will create an AirQualitySensor element. The Home app works well, but the Eve app seems to show more measurements. Measurements retrieved are PM2.5, PM10, & O3 for AirNow. Aqicn adds NO2, SO2, CO...

Architecture

This plugin implements a dual-platform architecture with shared helpers to keep code clean and behavior consistent across protocols:

  • HAP Platform (HomeKit via HAP)

    • File: src/platform-hap.ts
    • Devices: src/devices-hap/
    • Uses shared AirQualityApiService for fetching/caching data

  • Matter Platform (HomeKit via Matter)

    • File: src/platform-matter.ts
    • Devices: src/devices-matter/
    • Prefers native Matter AirQuality device type when available; falls back to OccupancySensing otherwise
    • On Homebridge >= 2.0.0-beta.43, exposes ConcentrationMeasurement clusters (PM2.5, PM10, O3, NO2, SO2, CO) when supported by the Homebridge Matter API

  • Shared Helpers

    • API Service: src/services/air-quality-api.ts provides provider-agnostic fetching, parsing, caching, and rate-limiting
    • Utilities: src/utils.ts includes AQI mapping and logging/name helpers

Notes

  • HAP and Matter platforms are registered separately via a small proxy in src/index.ts.
  • The Matter platform polls devices using the shared service and updates both AirQuality and pollutant clusters when available.
  • Reverse-geocoding fallback is implemented in the HAP device to resolve ZIP codes when AirNow’s lat/lon endpoint has no data.

Contributing

We welcome contributions! Please note our beta branch strategy:

  • All PRs must target a beta branch first (format: beta-X.Y.Z)
  • Issues must have semantic versioning labels (patch, minor, major) before assignment
  • Use our helper script to create beta branches: ./scripts/create-beta-branch.sh
  • See our Contributing Guide for detailed instructions

For GitHub Copilot users, please review our Copilot Instructions.

Thanks

Thank you to ToddGreenfield for the the work done on the accesorry based plugin homebridge-airnow.