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
- Homebridge 1.6+ or 2.0-beta+
- Node.js 20.7+
- Airly API key (free at developer.airly.eu)
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 |
Links
License
Released under the GPL-3.0 license.
Using the plugin? Have ideas for improvements? Let me know on GitHub or reach out directly!