Skip to content
Tomasz WyderkaTomasz Wyderka
PL/EN
Back to projects

Homebridge Airly 2

Active

A plugin that brings Airly air quality data into HomeKit via Homebridge. Monitor air quality in the Home app.

HomebridgeAirlyHomeKitIoTSmart HomeNode.js
GitHubnpm
Homebridge Airly 2 - HomeKit integration

About

Homebridge Airly 2 is a plugin for the Homebridge platform that fetches air quality data from the Airly sensor network and exposes it as a native sensor in the Home app (HomeKit) on iPhone, iPad, and Mac.

The project was born out of the need to monitor air quality without buying additional hardware. All you need is a free Airly API key and a working Homebridge installation.

Key Features

  • Real-time measurements - PM2.5, PM10, and AIRLY_CAQI index
  • Zero dependencies - no external libraries, only built-in Node.js modules
  • HomeKit integration - full support for the Home app and automations
  • UI configuration - Homebridge Config UI X support
  • Input validation - coordinate and parameter validation
  • Unit tests - 53 tests, 88% code coverage

Version 0.2.0 (December 2025)

The latest version introduces several improvements:

Security

  • Geographic coordinate validation with range checking
  • MaxDistance parameter validation (50 km limit)
  • Safe URL building with URLSearchParams
  • HTTP request timeout (30 seconds)

New Features

  • Configurable refresh interval (default 15 min)
  • Unique serial number for each location
  • Polling error logging for easier debugging

Code Quality

  • Complete unit test suite (Jest)
  • Local testing documentation
  • Updated requirements (Homebridge 1.6+, Node.js 20.7+)

Requirements

Installation

npm install -g homebridge-airly2

or via hb-service:

hb-service add homebridge-airly2

Configuration

Add to your Homebridge config.json:

{
  "accessories": [
    {
      "accessory": "Air2",
      "name": "Air Quality",
      "apikey": "YOUR_API_KEY",
      "latitude": "52.2297",
      "longitude": "21.0122",
      "maxdistance": 5,
      "refreshinterval": 15
    }
  ]
}

Field Description

Field Description Required
accessory Always “Air2” Yes
name Name displayed in HomeKit Yes
apikey Airly API key Yes
latitude Geographic latitude Yes
longitude Geographic longitude Yes
maxdistance Max distance from sensor (km), default 3, max 50 No
refreshinterval Refresh interval (minutes), min. 15 No

License

Released under the GPL-3.0 license.