A month after the last update, I’m releasing version 0.2.0 of the homebridge-airly2 plugin. This is the biggest update in years, focused on security, code quality, and stability.

What’s New in v0.2.0?

Security and Validation

The previous version trusted configuration data without verification. Now all parameters are thoroughly validated:

Geographic coordinate validation:

// Latitude: -90 to 90
// Longitude: -180 to 180
if (latitude < -90 || latitude > 90) {
    throw new Error('Invalid latitude');
}

MaxDistance validation:

  • Values <= 0 or invalid → defaults to 3 km
  • Values > 50 km → automatically capped to 50 km with a warning log

Safe URL building:

// Before (vulnerable to injection):
const url = `...?lat=${latitude}&lng=${longitude}`;

// Now (safe):
const params = new URLSearchParams({
    lat: String(latitude),
    lng: String(longitude)
});

HTTP Timeout: Added a 30-second timeout for Airly API requests. Prevents “hanging” connections that could block Homebridge.

New Features

Configurable refresh interval:

Airly allows 100 requests per day. The default 15-minute interval (~96 requests/day) respects this limit, but now you can customize it:

{
    "refreshinterval": 30
}

Unique serial number:

Each plugin instance now generates a unique serial number based on coordinates. This makes it easier to identify multiple sensors in HomeKit:

AIR2-A1B2C3D4

Error logging:

Polling errors are now logged (in debug mode), making it easier to diagnose connection issues.

Unit Tests

This is the most important change for me. The plugin now has 53 unit tests with 88% code coverage.

npm test

PASS ./index.test.js
  ✓ transformAQI (6 tests)
  ✓ validateCoordinates (7 tests)
  ✓ validateMaxDistance (4 tests)
  ✓ normalizeMeasurement (5 tests)
  ✓ getSensorValue (4 tests)
  ...

Tests: 53 passed

Tests use Jest and mock both the Homebridge API and the https module. This allows me to safely make changes without regression risk.

Documentation

  • CHANGELOG.md - full change history
  • TESTS.md - step-by-step local testing guide
  • README.md - updated documentation with Development section

Why These Changes?

The homebridge-airly2 plugin is used by users worldwide. As the sole maintainer, I feel responsible for:

  1. Stability - the plugin must work reliably 24/7
  2. Security - the code runs on home networks, close to IoT devices
  3. Quality - tests enable safe development

How to Update?

npm update -g homebridge-airly2

Or via Homebridge Config UI X → Plugins → Update.

Compatibility

Version 0.2.0 requires:

  • Homebridge 1.6+ or 2.0-beta+
  • Node.js 20.7+

Configuration remains backward compatible.

What’s Next?

Plans include:

  • Notifications for pollution threshold breaches
  • Better integration with HomeKit automations
  • Perhaps support for other air quality APIs

Source code: github.com/ximot/homebridge-airly2

Questions or suggestions? Open an issue on GitHub or reach out!