homebridge-luftdaten 1.0.0

package/INSTALL.md

@@ -0,0 +1,210 @@
+# Installation guide — homebridge-luftdaten
+
+A step-by-step walkthrough, from nothing to a working air-quality sensor in the
+Apple **Home** app. Assumes you already have a running Homebridge instance.
+
+---
+
+## 1. Collect what you need
+
+Before you start, prepare three things:
+
+| Data | What it is | How to get it |
+|---|---|---|
+| **name** | the name shown in HomeKit | anything, e.g. `Living Room Air` |
+| **localUrl / IP** | the sensor's local address with the `/data.json` path | see below |
+| **sensorId** | the sensor's ID on Sensor.Community (for the cloud fallback) | see below |
+
+### Finding the local IP address (localUrl)
+
+1. The airrohr device, once on your Wi-Fi, is reachable on your LAN. Find its
+   address via:
+   - your router's DHCP client list (the hostname starts with `airrohr-…` /
+     `feinstaubsensor-…`), or
+   - a network-scanning app (e.g. *Fing*).
+2. Open `http://<SENSOR_IP>/` in a browser — you'll see the airrohr panel.
+3. The raw data lives at **`http://<SENSOR_IP>/data.json`**. Open it and confirm
+   you see `sensordatavalues` with `SDS_P1`, `SDS_P2`, etc.
+   That is your **localUrl**, e.g. `http://192.168.1.50/data.json`.
+
+> Tip: give the sensor a **DHCP reservation** (static IP) in your router so the
+> `localUrl` doesn't change after a reboot.
+
+### Finding the sensorId (cloud)
+
+1. Go to <https://devices.sensor.community/> and sign in to the account the
+   sensor is registered to (or find it on the map at
+   <https://maps.sensor.community/>).
+2. The **sensorId** is the numeric ID of the **SDS011** (particulate) sensor.
+   Verify it by opening:
+   `https://data.sensor.community/airrohr/v1/sensor/<sensorId>/`
+   It should return a JSON array of recent measurements.
+
+> `sensorId` is optional — it's only a backup for when the sensor is temporarily
+> unreachable on the local network. If you omit it, the plugin uses `localUrl`
+> only.
+
+---
+
+## 2. Install the plugin
+
+### Option A — Homebridge UI (recommended)
+
+1. Open **Homebridge Config UI X** in your browser.
+2. **Plugins** tab → search for `homebridge-luftdaten`.
+3. Click **Install** and wait for it to finish.
+
+### Option B — manually via npm
+
+On the Homebridge host:
+
+```bash
+sudo npm install -g homebridge-luftdaten
+```
+
+(on a containerised / `hb-service` install, drop `sudo` as appropriate for your
+setup).
+
+### Option C — from a local file (e.g. before publishing to npm)
+
+Copy the packed tarball to the Homebridge host and install it. Using
+`hb-service` (the standard Homebridge install on Debian / Proxmox / Raspberry Pi)
+puts it in the correct plugin directory:
+
+```bash
+# 1) On your machine: build the tarball
+npm pack                       # produces homebridge-luftdaten-<version>.tgz
+
+# 2) Copy it to the Homebridge host
+scp homebridge-luftdaten-*.tgz <USER>@<HOMEBRIDGE_IP>:/tmp/
+
+# 3) On the Homebridge host: install
+sudo hb-service add /tmp/homebridge-luftdaten-*.tgz
+# fallback if your install doesn't use hb-service:
+# sudo npm install -g /tmp/homebridge-luftdaten-*.tgz
+```
+
+You can also install straight from GitHub:
+
+```bash
+sudo hb-service add https://github.com/<YOUR_LOGIN>/homebridge-luftdaten
+```
+
+---
+
+## 3. Configure config.json
+
+### Via the UI
+
+In the **Plugins** tab click **Settings** next to homebridge-luftdaten and fill
+in the fields, or edit the raw JSON in the **Config** tab.
+
+### Manually
+
+Add an entry to the `accessories` array in `config.json`:
+
+```json
+{
+  "accessories": [
+    {
+      "accessory": "Luftdaten",
+      "name": "Living Room Air",
+      "localUrl": "http://192.168.1.50/data.json",
+      "sensorId": "12345",
+      "pollInterval": 120,
+      "requestTimeout": 10,
+      "hasTempSensor": true
+    }
+  ]
+}
+```
+
+See [README.md](README.md) for the full option reference. The essentials:
+
+- `localUrl` — the priority local source.
+- `sensorId` — the cloud backup (optional).
+- `hasTempSensor` — `true` if you have an SHT3X/BME280; `false` for an SDS011
+  alone. (The legacy `hasBME280` flag still works.)
+
+Save the config and **restart Homebridge**.
+
+---
+
+## 4. Pair the bridge with the Home app (only for a new bridge)
+
+> If your Homebridge bridge is already added to HomeKit, skip this — the new
+> accessory appears automatically.
+
+1. In the Homebridge UI **Status** screen, find the bridge **QR code** (and the
+   PIN, default `031-45-154`).
+2. On your iPhone/iPad open the **Home** app → **+** → **Add Accessory**.
+3. Scan the QR code from the Homebridge screen.
+4. Confirm adding the bridge (if you see "Uncertified Accessory", choose **Add
+   Anyway**).
+5. Assign the accessory to a room and name the tiles.
+
+After pairing you'll see the air-quality sensor plus (if `hasTempSensor`)
+separate temperature and humidity tiles.
+
+---
+
+## 5. Verify in the logs
+
+In the Homebridge UI open **Logs**. On startup and on each poll you'll see a
+line like:
+
+```
+[Living Room Air] [local] PM2.5=4.63 PM10=6.95 temp=21.4°C hum=45.33% airQuality=1
+```
+
+- `[local]` — data read from the sensor on the local network.
+- `[cloud]` — the Sensor.Community fallback kicked in.
+- `airQuality=1..5` — 1 = excellent, 5 = poor.
+
+If you only see warnings (`Local read failed`, `No sensor data available`), see
+the section below.
+
+---
+
+## 6. Troubleshooting
+
+### No data / "Local read failed"
+
+- **VLANs / segmented networks**: Homebridge must be able to reach the sensor.
+  If the sensor lives on a separate IoT VLAN/network, allow traffic from the
+  Homebridge host to the sensor's IP (port 80). Test from the Homebridge host:
+  ```bash
+  curl -m 10 http://192.168.1.50/data.json
+  ```
+  If `curl` doesn't return JSON, the problem is network/firewall, not the plugin.
+- **Firewall**: make sure your firewall (router, host, Docker) isn't blocking
+  outbound HTTP to the sensor or HTTPS to `data.sensor.community`.
+- **Wrong address**: confirm `localUrl` ends with `/data.json` and the IP is
+  current (see the DHCP reservation tip in step 1).
+- **Timeout**: if the sensor responds slowly, raise `requestTimeout` (e.g. `20`).
+
+### Cloud fallback is used instead of local
+
+You see `[cloud]` instead of `[local]` — the sensor is unreachable locally.
+Start with the `curl` test above. Remember the cloud updates with a delay and may
+return older readings than a direct local read.
+
+### No PM values (PM2.5 / PM10 = n/a)
+
+- The **SDS011** has a warm-up phase — wait ~1–2 min after startup.
+- In power-saving (sleep) mode the SDS011 measures in cycles; between cycles
+  `data.json` may not contain fresh `SDS_P1` / `SDS_P2`. Align `pollInterval`
+  with the sensor's measurement cycle.
+- Check `http://<SENSOR_IP>/data.json` to confirm the `SDS_P1`/`SDS_P2` keys are
+  present at all.
+
+### SHT3X vs BME280 — temperature/humidity is "n/a"
+
+- The plugin recognises both automatically (`SHT3X_*`, `BME280_*`, plus
+  `BMP280_*`, `DHT_*` and generic `temperature`/`humidity`).
+- If data is still missing: check which exact `value_type` your firmware reports
+  in `data.json`, and that `hasTempSensor` is `true`.
+- **BMP280** measures only temperature and pressure (no humidity) — in that case
+  humidity stays empty, which is expected.
+- Pressure is not shown in HomeKit (no such characteristic exists) — you'll only
+  see it in the logs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafał Rudecki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# homebridge-luftdaten
+
+Bring your [Luftdaten / Sensor.Community](https://sensor.community/) air-quality
+sensor into Apple HomeKit — local-first, with an automatic cloud fallback.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%E2%89%A5%2018-339933.svg)
+![Homebridge](https://img.shields.io/badge/homebridge-%E2%89%A5%201.6-491F59.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-none-blue.svg)
+
+![How the sensor looks in the iOS Home app](docs/home-app-preview.svg)
+
+---
+
+A Homebridge **accessory** plugin that exposes a Luftdaten / Sensor.Community
+sensor (airrohr firmware — typically an **SDS011** particulate sensor plus an
+**SHT3X** or **BME280** temperature/humidity sensor) to Apple HomeKit.
+
+It reads **locally first** from the sensor's own `data.json` endpoint and
+**falls back to the Sensor.Community cloud** when the local device is
+unreachable. Zero external dependencies — it uses the built-in `fetch` (Node 18+)
+and `AbortController` for timeouts.
+
+## Features
+
+- 🏠 Local-first reading (`http://<ip>/data.json`), cloud fallback via the
+  Sensor.Community API.
+- 🌫️ Air quality (1–5) derived from PM2.5 using WHO/EU thresholds, plus raw
+  PM2.5 and PM10 density.
+- 🌡️ Temperature and humidity (optional, on by default).
+- 🔄 Configurable polling interval and request timeout.
+- 📦 No runtime dependencies.
+
+## Exposed HomeKit services & characteristics
+
+| Service | Characteristic | Source | Notes |
+|---|---|---|---|
+| AirQualitySensor | `AirQuality` (1–5) | derived from PM2.5 | see thresholds below |
+| AirQualitySensor | `PM2_5Density` | `SDS_P2` / `P2` | µg/m³ |
+| AirQualitySensor | `PM10Density` | `SDS_P1` / `P1` | µg/m³ |
+| TemperatureSensor | `CurrentTemperature` | `*_temperature` | name `"<name> Temp"`, range −50…100 °C |
+| HumiditySensor | `CurrentRelativeHumidity` | `*_humidity` | name `"<name> Humidity"` |
+| AccessoryInformation | `Manufacturer` | — | `Sensor.Community` |
+| AccessoryInformation | `Model` | — | `SDS011 + SHT3X/BME280` |
+| AccessoryInformation | `SerialNumber` | — | `sensorId` (or `localUrl`) |
+
+Temperature and humidity services are only added when `hasTempSensor` is `true`
+(the default).
+
+Atmospheric **pressure** (`BME280_pressure` / `BMP280_pressure`, converted Pa → hPa)
+is parsed and written to the Homebridge log, but **not** exposed to HomeKit —
+there is no native HomeKit characteristic for barometric pressure.
+
+### value_type variants understood by the parser
+
+- PM: `SDS_P1` → PM10, `SDS_P2` → PM2.5 (local); `P1` → PM10, `P2` → PM2.5 (cloud API)
+- Temperature: `SHT3X_temperature`, `BME280_temperature`, `BMP280_temperature`,
+  `DHT_temperature`, generic `temperature`
+- Humidity: `SHT3X_humidity`, `BME280_humidity`, `DHT_humidity`, generic `humidity`
+- Pressure: `BME280_pressure`, `BMP280_pressure` (÷100 → hPa)
+
+## PM2.5 → AirQuality mapping (µg/m³)
+
+| PM2.5 | AirQuality |
+|---|---|
+| ≤ 10 | 1 — EXCELLENT |
+| ≤ 20 | 2 — GOOD |
+| ≤ 25 | 3 — FAIR |
+| ≤ 50 | 4 — INFERIOR |
+| > 50 | 5 — POOR |
+| missing / NaN | 0 — UNKNOWN |
+
+## Installation
+
+Via the Homebridge UI: search for **homebridge-luftdaten** on the Plugins tab
+and install it. Or from the command line:
+
+```bash
+npm install -g homebridge-luftdaten
+```
+
+A full, step-by-step walkthrough is in **[INSTALL.md](INSTALL.md)**.
+
+## Configuration
+
+Add an entry to the `accessories` array of your Homebridge `config.json`:
+
+```json
+{
+  "accessories": [
+    {
+      "accessory": "Luftdaten",
+      "name": "Living Room Air",
+      "localUrl": "http://192.168.1.50/data.json",
+      "sensorId": "12345",
+      "pollInterval": 120,
+      "requestTimeout": 10,
+      "hasTempSensor": true
+    }
+  ]
+}
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `accessory` | string | — | Must be `"Luftdaten"`. |
+| `name` | string | `"Luftdaten"` | Name shown in the Home app. |
+| `localUrl` | string | — | Local sensor endpoint, e.g. `http://192.168.1.50/data.json`. Tried first. |
+| `sensorId` | string/number | — | Sensor.Community sensor ID, used for the cloud fallback. |
+| `pollInterval` | number | `120` | Seconds between reads (min 10). |
+| `requestTimeout` | number | `10` | Per-request timeout in seconds (min 1). |
+| `hasTempSensor` | boolean | `true` | Add temperature + humidity services. |
+| `hasBME280` | boolean | — | **Deprecated** alias for `hasTempSensor`, kept for backward compatibility. |
+
+At least one of `localUrl` or `sensorId` must be set. If both are present, the
+local URL is used and the cloud is only contacted when the local read fails.
+
+## How it works
+
+```
+        ┌──────────────────────────┐
+poll →  │  GET localUrl (priority)  │ ── ok ──►  parse  ─┐
+        └──────────────────────────┘                    │
+                     │ fail/timeout                      ▼
+                     ▼                          update HomeKit
+        ┌──────────────────────────┐           characteristics
+        │ GET cloud API (fallback) │ ── ok ──►  parse  ─┘
+        │  …/v1/sensor/<id>/       │
+        └──────────────────────────┘
+```
+
+## Development
+
+```bash
+npm run check   # node --check src/index.js
+npm test        # node --test
+```
+
+## License
+
+[MIT](LICENSE) © Rafał Rudecki

package/config.sample.json

@@ -0,0 +1,13 @@
+{
+  "accessories": [
+    {
+      "accessory": "Luftdaten",
+      "name": "<NAME_IN_HOMEKIT>",
+      "localUrl": "http://192.168.1.50/data.json",
+      "sensorId": "<SDS011_SENSOR_ID>",
+      "pollInterval": 120,
+      "requestTimeout": 10,
+      "hasTempSensor": true
+    }
+  ]
+}

package/config.schema.json

@@ -0,0 +1,64 @@
+{
+  "pluginAlias": "Luftdaten",
+  "pluginType": "accessory",
+  "singular": false,
+  "headerDisplay": "Reads a Luftdaten / Sensor.Community (airrohr) sensor — local-first, with a cloud fallback. Provide a **Local URL** and/or a **Sensor ID** (at least one is required).",
+  "footerDisplay": "See the [README](https://github.com/rafalr100/homebridge-luftdaten) for details. Pressure is logged but not exposed to HomeKit.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Luftdaten",
+        "required": true,
+        "description": "Name shown in the Home app."
+      },
+      "localUrl": {
+        "title": "Local URL",
+        "type": "string",
+        "format": "uri",
+        "placeholder": "http://192.168.1.50/data.json",
+        "description": "The sensor's local data endpoint. Tried first."
+      },
+      "sensorId": {
+        "title": "Sensor.Community Sensor ID",
+        "type": "string",
+        "placeholder": "12345",
+        "description": "Numeric ID of the SDS011 sensor, used for the cloud fallback when the local read fails."
+      },
+      "pollInterval": {
+        "title": "Poll interval (seconds)",
+        "type": "integer",
+        "default": 120,
+        "minimum": 10,
+        "description": "How often to read the sensor."
+      },
+      "requestTimeout": {
+        "title": "Request timeout (seconds)",
+        "type": "integer",
+        "default": 10,
+        "minimum": 1,
+        "description": "Per-request timeout."
+      },
+      "hasTempSensor": {
+        "title": "Has temperature / humidity sensor",
+        "type": "boolean",
+        "default": true,
+        "description": "Add temperature and humidity services (SHT3X / BME280). Turn off for an SDS011-only sensor."
+      }
+    }
+  },
+  "layout": [
+    "name",
+    "localUrl",
+    "sensorId",
+    {
+      "type": "fieldset",
+      "title": "Advanced",
+      "expandable": true,
+      "expanded": false,
+      "items": ["pollInterval", "requestTimeout", "hasTempSensor"]
+    }
+  ]
+}

package/docs/home-app-preview.svg

@@ -0,0 +1,86 @@
+<svg width="720" height="460" viewBox="0 0 720 460" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <linearGradient id="wall" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4b4bd6"/>
+      <stop offset="0.55" stop-color="#7a5cc8"/>
+      <stop offset="1" stop-color="#c065c4"/>
+    </linearGradient>
+    <linearGradient id="green" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#34d27b"/>
+      <stop offset="1" stop-color="#2bb673"/>
+    </linearGradient>
+    <filter id="soft" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="6" stdDeviation="10" flood-color="#000" flood-opacity="0.18"/>
+    </filter>
+  </defs>
+
+  <!-- wallpaper -->
+  <rect width="720" height="460" rx="28" fill="url(#wall)"/>
+  <rect width="720" height="460" rx="28" fill="#ffffff" opacity="0.04"/>
+
+  <!-- header -->
+  <text x="40" y="56" fill="#ffffff" font-size="27" font-weight="700">My Home</text>
+  <text x="40" y="80" fill="#ffffff" opacity="0.75" font-size="14" font-weight="500">Living Room · Air Quality Sensor</text>
+
+  <!-- ===== tiles row ===== -->
+  <!-- Tile 1: Air Quality -->
+  <g filter="url(#soft)">
+    <rect x="40" y="104" width="200" height="128" rx="22" fill="#ffffff" opacity="0.16"/>
+  </g>
+  <rect x="40" y="104" width="200" height="128" rx="22" fill="none" stroke="#ffffff" stroke-opacity="0.2"/>
+  <circle cx="74" cy="142" r="20" fill="url(#green)"/>
+  <g stroke="#ffffff" stroke-width="2.6" stroke-linecap="round" fill="none" opacity="0.95">
+    <path d="M65 137 h14 a4 4 0 1 0 -4 -4"/>
+    <path d="M65 143 h18 a4 4 0 1 1 -4 4"/>
+    <path d="M65 149 h11"/>
+  </g>
+  <text x="64" y="194" fill="#ffffff" font-size="25" font-weight="700">Excellent</text>
+  <text x="64" y="216" fill="#ffffff" opacity="0.78" font-size="13" font-weight="500">Air Quality</text>
+
+  <!-- Tile 2: Temperature -->
+  <g filter="url(#soft)">
+    <rect x="260" y="104" width="200" height="128" rx="22" fill="#ffffff" opacity="0.16"/>
+  </g>
+  <rect x="260" y="104" width="200" height="128" rx="22" fill="none" stroke="#ffffff" stroke-opacity="0.2"/>
+  <circle cx="294" cy="142" r="20" fill="#ff8a3d"/>
+  <g fill="none" stroke="#ffffff" stroke-width="2.6" stroke-linecap="round">
+    <path d="M294 133 v12"/>
+  </g>
+  <rect x="290.5" y="131" width="7" height="14" rx="3.5" fill="#ffffff"/>
+  <circle cx="294" cy="150" r="5.5" fill="#ffffff"/>
+  <text x="284" y="194" fill="#ffffff" font-size="27" font-weight="700">21.4°</text>
+  <text x="284" y="216" fill="#ffffff" opacity="0.78" font-size="13" font-weight="500">Temperature</text>
+
+  <!-- Tile 3: Humidity -->
+  <g filter="url(#soft)">
+    <rect x="480" y="104" width="200" height="128" rx="22" fill="#ffffff" opacity="0.16"/>
+  </g>
+  <rect x="480" y="104" width="200" height="128" rx="22" fill="none" stroke="#ffffff" stroke-opacity="0.2"/>
+  <circle cx="514" cy="142" r="20" fill="#3aa0ff"/>
+  <path d="M514 130 C520 138 524 143 524 148 a10 10 0 1 1 -20 0 c0 -5 4 -10 10 -18 Z" fill="#ffffff"/>
+  <text x="504" y="194" fill="#ffffff" font-size="27" font-weight="700">46%</text>
+  <text x="504" y="216" fill="#ffffff" opacity="0.78" font-size="13" font-weight="500">Humidity</text>
+
+  <!-- ===== detail card ===== -->
+  <g filter="url(#soft)">
+    <rect x="40" y="256" width="640" height="160" rx="26" fill="#ffffff" opacity="0.16"/>
+  </g>
+  <rect x="40" y="256" width="640" height="160" rx="26" fill="none" stroke="#ffffff" stroke-opacity="0.2"/>
+
+  <text x="64" y="290" fill="#ffffff" opacity="0.7" font-size="13" font-weight="600" letter-spacing="0.5">AIR QUALITY SENSOR</text>
+  <circle cx="70" cy="318" r="7" fill="url(#green)"/>
+  <text x="86" y="324" fill="#ffffff" font-size="22" font-weight="700">Excellent</text>
+  <text x="616" y="324" fill="#ffffff" opacity="0.7" font-size="12" font-weight="500" text-anchor="end">WHO / EU thresholds</text>
+
+  <!-- PM2.5 row -->
+  <text x="64" y="362" fill="#ffffff" font-size="14" font-weight="600">PM2.5</text>
+  <rect x="150" y="354" width="390" height="9" rx="4.5" fill="#ffffff" opacity="0.2"/>
+  <rect x="150" y="354" width="62" height="9" rx="4.5" fill="url(#green)"/>
+  <text x="616" y="363" fill="#ffffff" font-size="14" font-weight="600" text-anchor="end">8 µg/m³</text>
+
+  <!-- PM10 row -->
+  <text x="64" y="394" fill="#ffffff" font-size="14" font-weight="600">PM10</text>
+  <rect x="150" y="386" width="390" height="9" rx="4.5" fill="#ffffff" opacity="0.2"/>
+  <rect x="150" y="386" width="94" height="9" rx="4.5" fill="url(#green)"/>
+  <text x="616" y="395" fill="#ffffff" font-size="14" font-weight="600" text-anchor="end">12 µg/m³</text>
+</svg>

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "homebridge-luftdaten",
+  "version": "1.0.0",
+  "description": "Homebridge accessory plugin for Luftdaten / Sensor.Community (airrohr) air quality sensors, with local-first reading and cloud fallback.",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "luftdaten",
+    "sensor.community",
+    "airrohr",
+    "air-quality",
+    "sds011",
+    "sht3x",
+    "bme280",
+    "particulate-matter",
+    "homekit"
+  ],
+  "engines": {
+    "homebridge": ">=1.6.0",
+    "node": ">=18.0.0"
+  },
+  "author": "Rafał Rudecki",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafalr100/homebridge-luftdaten.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rafalr100/homebridge-luftdaten/issues"
+  },
+  "homepage": "https://github.com/rafalr100/homebridge-luftdaten#readme",
+  "files": [
+    "src/",
+    "docs/",
+    "config.schema.json",
+    "config.sample.json",
+    "README.md",
+    "INSTALL.md",
+    "LICENSE"
+  ]
+}

package/src/index.js

@@ -0,0 +1,358 @@
+'use strict';
+
+/**
+ * homebridge-luftdaten
+ *
+ * Accessory plugin reading air-quality data from a Luftdaten / Sensor.Community
+ * (airrohr firmware) sensor. Reads locally first (e.g. http://<ip>/data.json)
+ * and falls back to the Sensor.Community cloud API.
+ *
+ * Zero external dependencies — uses the built-in global `fetch` (Node 18+)
+ * together with AbortController for request timeouts.
+ */
+
+const PLUGIN_NAME = 'homebridge-luftdaten';
+const ACCESSORY_NAME = 'Luftdaten';
+
+// HomeKit AirQuality characteristic values (HAP enum).
+const AIR_QUALITY = {
+  UNKNOWN: 0,
+  EXCELLENT: 1,
+  GOOD: 2,
+  FAIR: 3,
+  INFERIOR: 4,
+  POOR: 5,
+};
+
+// HomeKit PM density characteristics have a valid range of 0..1000 µg/m³.
+const DENSITY_MIN = 0;
+const DENSITY_MAX = 1000;
+
+/**
+ * Parse a single airrohr-style payload (an object with a `sensordatavalues`
+ * array) into normalised numeric readings. Handles every firmware variant of
+ * the temperature/humidity/pressure value_type names.
+ *
+ * @param {object} data raw payload (a single sensor record, not the cloud array)
+ * @returns {{pm25:?number, pm10:?number, temperature:?number, humidity:?number, pressure:?number}}
+ */
+function parseSensorData(data) {
+  const result = {
+    pm25: null,
+    pm10: null,
+    temperature: null,
+    humidity: null,
+    pressure: null, // hPa — read & logged, but not exposed to HomeKit
+  };
+
+  const values =
+    data && Array.isArray(data.sensordatavalues) ? data.sensordatavalues : [];
+
+  for (const entry of values) {
+    if (!entry || typeof entry.value_type !== 'string') continue;
+    const num = parseFloat(entry.value);
+    if (Number.isNaN(num)) continue;
+
+    switch (entry.value_type) {
+      // PM10 — local firmware uses SDS_P1, the Sensor.Community cloud API uses P1.
+      case 'SDS_P1':
+      case 'P1':
+        result.pm10 = num;
+        break;
+      // PM2.5 — local firmware uses SDS_P2, the cloud API uses P2.
+      case 'SDS_P2':
+      case 'P2':
+        result.pm25 = num;
+        break;
+
+      // Temperature — all known firmware variants.
+      case 'SHT3X_temperature':
+      case 'BME280_temperature':
+      case 'BMP280_temperature':
+      case 'DHT_temperature':
+      case 'temperature':
+        result.temperature = num;
+        break;
+
+      // Humidity — all known firmware variants.
+      case 'SHT3X_humidity':
+      case 'BME280_humidity':
+      case 'DHT_humidity':
+      case 'humidity':
+        result.humidity = num;
+        break;
+
+      // Pressure reported in Pa — convert to hPa.
+      case 'BME280_pressure':
+      case 'BMP280_pressure':
+        result.pressure = num / 100;
+        break;
+
+      default:
+        // signal, samples, min_micro, etc. — ignored.
+        break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Map a PM2.5 reading (µg/m³) to a HomeKit AirQuality value using WHO/EU
+ * thresholds.
+ *   <=10 EXCELLENT, <=20 GOOD, <=25 FAIR, <=50 INFERIOR, >50 POOR, missing UNKNOWN
+ *
+ * @param {?number} pm25
+ * @returns {number} HomeKit AirQuality value (0..5)
+ */
+function pm25ToAirQuality(pm25) {
+  if (pm25 === null || pm25 === undefined || Number.isNaN(pm25)) {
+    return AIR_QUALITY.UNKNOWN;
+  }
+  if (pm25 <= 10) return AIR_QUALITY.EXCELLENT;
+  if (pm25 <= 20) return AIR_QUALITY.GOOD;
+  if (pm25 <= 25) return AIR_QUALITY.FAIR;
+  if (pm25 <= 50) return AIR_QUALITY.INFERIOR;
+  return AIR_QUALITY.POOR;
+}
+
+/** Clamp a density value into the HomeKit-valid 0..1000 range. */
+function clampDensity(value) {
+  if (value === null || value === undefined || Number.isNaN(value)) return 0;
+  return Math.min(DENSITY_MAX, Math.max(DENSITY_MIN, value));
+}
+
+class LuftdatenAccessory {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+
+    this.Service = api.hap.Service;
+    this.Characteristic = api.hap.Characteristic;
+
+    this.name = this.config.name || ACCESSORY_NAME;
+    this.localUrl = this.config.localUrl || null;
+    this.sensorId =
+      this.config.sensorId !== undefined && this.config.sensorId !== null
+        ? String(this.config.sensorId)
+        : null;
+
+    this.pollInterval = Math.max(10, Number(this.config.pollInterval) || 120) * 1000;
+    this.requestTimeout =
+      Math.max(1, Number(this.config.requestTimeout) || 10) * 1000;
+
+    // hasTempSensor decides whether temperature + humidity services are added.
+    // Backward compatible with the old `hasBME280` flag.
+    if (this.config.hasTempSensor !== undefined) {
+      this.hasTempSensor = Boolean(this.config.hasTempSensor);
+    } else if (this.config.hasBME280 !== undefined) {
+      this.hasTempSensor = Boolean(this.config.hasBME280);
+    } else {
+      this.hasTempSensor = true;
+    }
+
+    // Last known readings (served by onGet handlers between polls).
+    this.latest = {
+      pm25: null,
+      pm10: null,
+      temperature: null,
+      humidity: null,
+      pressure: null,
+    };
+
+    if (!this.localUrl && !this.sensorId) {
+      this.log.warn(
+        'Neither "localUrl" nor "sensorId" configured — no data source available.'
+      );
+    }
+
+    this._setupServices();
+    this._startPolling();
+  }
+
+  _setupServices() {
+    const { Service, Characteristic } = this;
+
+    // Accessory information.
+    this.informationService = new Service.AccessoryInformation()
+      .setCharacteristic(Characteristic.Manufacturer, 'Sensor.Community')
+      .setCharacteristic(Characteristic.Model, 'SDS011 + SHT3X/BME280')
+      .setCharacteristic(
+        Characteristic.SerialNumber,
+        this.sensorId || this.localUrl || 'luftdaten'
+      );
+
+    // Air quality.
+    this.airQualityService = new Service.AirQualitySensor(this.name);
+    this.airQualityService
+      .getCharacteristic(Characteristic.AirQuality)
+      .onGet(() => pm25ToAirQuality(this.latest.pm25));
+    this.airQualityService
+      .getCharacteristic(Characteristic.PM2_5Density)
+      .onGet(() => clampDensity(this.latest.pm25));
+    this.airQualityService
+      .getCharacteristic(Characteristic.PM10Density)
+      .onGet(() => clampDensity(this.latest.pm10));
+
+    this.services = [this.informationService, this.airQualityService];
+
+    if (this.hasTempSensor) {
+      this.temperatureService = new Service.TemperatureSensor(
+        `${this.name} Temp`,
+        'temperature'
+      );
+      this.temperatureService
+        .getCharacteristic(Characteristic.CurrentTemperature)
+        .setProps({ minValue: -50, maxValue: 100 })
+        .onGet(() =>
+          this.latest.temperature === null ? 0 : this.latest.temperature
+        );
+
+      this.humidityService = new Service.HumiditySensor(
+        `${this.name} Humidity`,
+        'humidity'
+      );
+      this.humidityService
+        .getCharacteristic(Characteristic.CurrentRelativeHumidity)
+        .onGet(() => (this.latest.humidity === null ? 0 : this.latest.humidity));
+
+      this.services.push(this.temperatureService, this.humidityService);
+    }
+  }
+
+  _startPolling() {
+    // Kick off immediately, then on the configured interval.
+    this.poll();
+    this._timer = setInterval(() => this.poll(), this.pollInterval);
+    if (this._timer.unref) this._timer.unref();
+  }
+
+  /** Fetch JSON from a URL with an AbortController-based timeout. */
+  async _fetchJson(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.requestTimeout);
+    try {
+      const res = await fetch(url, {
+        signal: controller.signal,
+        headers: { Accept: 'application/json' },
+      });
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Poll the sensor: local first, cloud as fallback. */
+  async poll() {
+    let raw = null;
+    let source = null;
+
+    // 1. Local read — priority.
+    if (this.localUrl) {
+      try {
+        raw = await this._fetchJson(this.localUrl);
+        source = 'local';
+      } catch (err) {
+        this.log.warn(
+          `Local read failed (${this.localUrl}): ${err.message}` +
+            (this.sensorId ? ' — trying cloud fallback.' : '')
+        );
+      }
+    }
+
+    // 2. Cloud fallback.
+    if (!raw && this.sensorId) {
+      const cloudUrl = `https://data.sensor.community/airrohr/v1/sensor/${this.sensorId}/`;
+      try {
+        const data = await this._fetchJson(cloudUrl);
+        // Cloud returns an array of records; the newest is the last element.
+        raw = Array.isArray(data) ? data[data.length - 1] : data;
+        source = 'cloud';
+      } catch (err) {
+        this.log.warn(`Cloud read failed (sensor ${this.sensorId}): ${err.message}`);
+      }
+    }
+
+    if (!raw) {
+      this.log.warn('No sensor data available from any source this cycle.');
+      return;
+    }
+
+    const parsed = parseSensorData(raw);
+    this.latest = parsed;
+    this._publish(parsed, source);
+  }
+
+  /** Push parsed readings into the HomeKit characteristics and log them. */
+  _publish(parsed, source) {
+    const { Characteristic } = this;
+
+    const aq = pm25ToAirQuality(parsed.pm25);
+    this.airQualityService.updateCharacteristic(Characteristic.AirQuality, aq);
+    if (parsed.pm25 !== null) {
+      this.airQualityService.updateCharacteristic(
+        Characteristic.PM2_5Density,
+        clampDensity(parsed.pm25)
+      );
+    }
+    if (parsed.pm10 !== null) {
+      this.airQualityService.updateCharacteristic(
+        Characteristic.PM10Density,
+        clampDensity(parsed.pm10)
+      );
+    }
+
+    if (this.hasTempSensor) {
+      if (parsed.temperature !== null && this.temperatureService) {
+        this.temperatureService.updateCharacteristic(
+          Characteristic.CurrentTemperature,
+          parsed.temperature
+        );
+      }
+      if (parsed.humidity !== null && this.humidityService) {
+        this.humidityService.updateCharacteristic(
+          Characteristic.CurrentRelativeHumidity,
+          parsed.humidity
+        );
+      }
+    }
+
+    const parts = [];
+    parts.push(`PM2.5=${fmt(parsed.pm25)}`);
+    parts.push(`PM10=${fmt(parsed.pm10)}`);
+    if (this.hasTempSensor) {
+      parts.push(`temp=${fmt(parsed.temperature)}°C`);
+      parts.push(`hum=${fmt(parsed.humidity)}%`);
+    }
+    if (parsed.pressure !== null) {
+      parts.push(`pressure=${fmt(parsed.pressure)}hPa`);
+    }
+    parts.push(`airQuality=${aq}`);
+    this.log.info(`[${source}] ${parts.join(' ')}`);
+  }
+
+  getServices() {
+    return this.services;
+  }
+}
+
+function fmt(value) {
+  return value === null || value === undefined || Number.isNaN(value)
+    ? 'n/a'
+    : value;
+}
+
+module.exports = (api) => {
+  api.registerAccessory(PLUGIN_NAME, ACCESSORY_NAME, LuftdatenAccessory);
+};
+
+// Exposed for unit tests (does not affect Homebridge registration).
+module.exports.parseSensorData = parseSensorData;
+module.exports.pm25ToAirQuality = pm25ToAirQuality;
+module.exports.clampDensity = clampDensity;
+module.exports.AIR_QUALITY = AIR_QUALITY;
+module.exports.LuftdatenAccessory = LuftdatenAccessory;