Homebridge Airly 2

O projekcie

Homebridge Airly 2 to plugin dla platformy Homebridge, który pobiera dane o jakości powietrza z sieci czujników Airly i udostępnia je jako natywny czujnik w aplikacji Dom (HomeKit) na iPhone, iPad i Mac.

Projekt powstał z potrzeby monitorowania jakości powietrza bez konieczności kupowania dodatkowych urządzeń. Wystarczy klucz API Airly (darmowy) i działająca instalacja Homebridge.

Najważniejsze funkcje

• Pomiary w czasie rzeczywistym - PM2.5, PM10 oraz indeks AIRLY_CAQI
• Zero zależności - brak zewnętrznych bibliotek, tylko wbudowane moduły Node.js
• Integracja z HomeKit - pełna obsługa aplikacji Dom i automatyzacji
• Konfiguracja przez UI - wsparcie dla Homebridge Config UI X
• Walidacja danych - sprawdzanie poprawności współrzędnych i parametrów
• Testy jednostkowe - 53 testy, 88% pokrycia kodu

Wersja 0.2.0 (grudzień 2025)

Najnowsza wersja wprowadza szereg ulepszeń:

Bezpieczeństwo

• Walidacja współrzędnych geograficznych z kontrolą zakresu
• Walidacja parametru maxDistance (limit 50 km)
• Bezpieczne budowanie URL-i z URLSearchParams
• Timeout dla żądań HTTP (30 sekund)

Nowe funkcje

• Konfigurowalny interwał odświeżania (domyślnie 15 min)
• Unikalny numer seryjny dla każdej lokalizacji
• Logowanie błędów pollingu dla łatwiejszego debugowania

Jakość kodu

• Kompletny zestaw testów jednostkowych (Jest)
• Dokumentacja testowania lokalnego
• Zaktualizowane wymagania (Homebridge 1.6+, Node.js 20.7+)

Wymagania

• Homebridge 1.6+ lub 2.0-beta+
• Node.js 20.7+
• Klucz API Airly (darmowy na developer.airly.eu)

Instalacja

npm install -g homebridge-airly2

lub przez hb-service:

hb-service add homebridge-airly2

Konfiguracja

Dodaj do config.json Homebridge:

{
  "accessories": [
    {
      "accessory": "Air2",
      "name": "Jakość powietrza",
      "apikey": "TWÓJ_KLUCZ_API",
      "latitude": "52.2297",
      "longitude": "21.0122",
      "maxdistance": 5,
      "refreshinterval": 15
    }
  ]
}

Opis pól

Pole	Opis	Wymagane
accessory	Zawsze “Air2”	Tak
name	Nazwa wyświetlana w HomeKit	Tak
apikey	Klucz API Airly	Tak
latitude	Szerokość geograficzna	Tak
longitude	Długość geograficzna	Tak
maxdistance	Maks. odległość od czujnika (km), domyślnie 3, max 50	Nie
refreshinterval	Interwał odświeżania (minuty), min. 15	Nie

Licencja

Projekt udostępniony na licencji GPL-3.0.