@pellebot/homebridge-fritz-platform-hb2 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Vielen Dank dass du zu `@pellebot/homebridge-fritz-platform-hb2` beitragen willst. Dieser Fork wird **LLM-unterstützt** gepflegt (siehe [`CONCEPT.md`](./CONCEPT.md)) — die Workflow-Erwartungen sind dadurch etwas anders als bei klassischen Open-Source-Projekten.
+
+## Issues melden
+
+Bevor du ein Issue öffnest, **bitte prüfe**:
+
+1. **Ist das Issue schon offen oder gelöst?** Suche in [bestehenden Issues](https://github.com/PelleBot/homebridge-fritz-platform-ng/issues?q=is%3Aissue).
+2. **Ist dein Anliegen im Scope?** Wenn es um Callmonitor, Presence, Network-Watcher, WoL, Childlock oder Telegram-Notifications geht — diese Subsysteme sind aus diesem Fork entfernt (siehe README). Issues dazu werden geschlossen mit Verweis auf den Original-Repo oder alternative Plugins.
+3. **Hast du minimale Infos?** Ein Issue ohne Versions-Angaben + Logs + Config-Auszug ist schwer zu beantworten. Bitte das Issue-Template nutzen.
+
+### Was ein guter Bug-Report enthält
+
+- **Homebridge-Version**: `homebridge --version`
+- **Node-Version**: `node --version`
+- **Plugin-Version**: `npm ls -g @pellebot/homebridge-fritz-platform-hb2`
+- **FritzBox-Modell** + **FRITZ!OS-Version** (siehe FritzBox-UI → System → Übersicht)
+- **Konkretes Verhalten**: was hast du erwartet, was passiert stattdessen?
+- **Reproduktionsschritte**: wie kann ich (oder ein anderer Tester) das Problem nachstellen?
+- **Logs**: idealerweise mit `"debug": true` in der Plugin-Config, der relevante Ausschnitt (nicht 10.000 Zeilen)
+- **Config-Auszug**: nur die relevante Plugin-Sektion, **ohne Passwort!**
+
+## Pull Requests
+
+**Vor dem PR**: bitte ein Issue öffnen (oder kommentieren), das die Änderung beschreibt. So vermeidest du Aufwand für Patches, die nicht in den Scope passen oder anders gelöst werden sollten.
+
+### PR-Checkliste
+
+- [ ] Eine Sache pro PR (kleine, fokussierte Änderungen)
+- [ ] Commit-Messages folgen [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
+- [ ] Beschreibung im PR: Was ändert sich, warum, wie getestet
+- [ ] Tests (falls anwendbar) — siehe `__tests__/` Verzeichnis
+- [ ] Lint passt (`npm run lint`)
+- [ ] `node --check` auf allen geänderten Dateien
+- [ ] Bei Code-Änderungen am Plugin: idealerweise mit einer echten FritzBox getestet (oder gegen die Mocks falls vorhanden)
+- [ ] CHANGELOG.md-Entry nicht selbst hinzufügen — das macht der Maintainer beim Release
+
+### Was wir gerne hätten
+
+Hohe Priorität (siehe [`ROADMAP.md`](./ROADMAP.md)):
+
+- Test-Suite ausbauen (Mock-Layer für AHA-API)
+- FRITZ!Smart Energy 250 OBIS-Reader-Verbesserungen (Phase 2.3)
+- `config.schema.json` Field-Hilfetexte verbessern (Phase 2.1 noch nicht ganz fertig)
+- energy-meter accType ins Schema aufnehmen (Phase 2.1)
+- Doku-Verbesserungen, vor allem zur Migration vom Original
+- Sauberere Logging-Strukturen
+
+Niedrige Priorität / wahrscheinlich abgelehnt:
+
+- Wiederherstellung der entfernten Subsysteme (Callmonitor, Presence, etc.) — siehe README
+- Große Refactors ohne klaren Mehrwert (CommonJS → ESM im src/-Tree)
+- Features für Geräte die der Maintainer nicht im Testbestand hat (z.B. Rollläden) — können angenommen werden, aber langsamere Iteration
+
+## Code-Konventionen
+
+- **CommonJS** im `src/`-Baum (intentional, minimal-patch-Prinzip)
+- **ESM** nur im `index.mjs`-Entrypoint (HB 2.0 Anforderung)
+- **HAP-Charakteristiken** über String-Literale (`'uint32'`, `'pr'`, etc.), nicht über `Characteristic.Formats.X`-Statics (siehe Eve-Types-Port)
+- **ES6-Klassen** für neue Custom-Characteristics (siehe `eve.types.js` als Vorlage)
+- **Keine** direkte Veränderung der HAP-Standard-Services (kein `Service.X = function() {...}`)
+
+## Maintenance-Workflow
+
+Wenn du ein PR öffnest:
+
+1. CI läuft automatisch (Lint + Build + Tests).
+2. Der Maintainer reviewed in den nächsten 1-7 Tagen.
+3. Bei Bedarf wird der Maintainer den Patch in einer LLM-Session diskutieren (das ist intern, du siehst nur das Review-Ergebnis).
+4. Bei Approval: Merge in `main`, Aufnahme in den nächsten Release.
+
+**Du wirst niemals automatische Bot-Antworten von uns bekommen.** Wenn 7 Tage keine Reaktion kommt, gerne nachfragen — manchmal ist Realität schneller als Github-Notifications.
+
+## Credits
+
+Dieser Fork baut auf der jahrelangen Arbeit von **Seyit Bayraktar (SeydX)** auf — siehe Original [`SeydX/homebridge-fritz-platform`](https://github.com/SeydX/homebridge-fritz-platform). Weitere Credits:
+
+- [@ulfalfa](https://github.com/ulfalfa) für das modifizierte **TR064**-Modul
+- [@simont77](https://github.com/simont77/fakegato-history) für **FakeGato** (im Fork als No-Op gestubbt)
+- [@tbasse](https://github.com/tbasse/fritzbox-callmonitor) für die ursprüngliche **Callmonitor**-Implementierung (im Fork nicht enthalten)
+- AVM für DECT-Hardware + AHA-HTTP-Interface-Doku
+- Alle Beta-Tester und Issue-Reporter aus dem Original-Repo

package/DEBUG.md

@@ -0,0 +1,72 @@
+# Debugging
+
+Wenn das Plugin sich nicht so verhält wie erwartet, gibt es zwei nützliche Debug-Mechanismen.
+
+## 1. Plugin-Debug-Mode
+
+In deiner `config.json` im FritzPlatform-Block:
+
+```json
+{
+  "platform": "FritzPlatform",
+  "debug": true,
+  ...
+}
+```
+
+Anschließend Homebridge neu starten. Die Logs zeigen jetzt detaillierte Informationen zu jedem Polling-Zyklus, AHA-API-Antworten, und Accessory-State-Übergängen.
+
+**Wichtig beim Posten von Debug-Logs in Issues:**
+- FritzBox-Passwort entfernen (steht zwar nicht direkt im Log, aber sicherheitshalber prüfen)
+- FritzBox-IP entfernen (z.B. `192.168.x.x` ersetzen durch `192.168.X.X`)
+- AINs können stehen bleiben (sind nicht sensibel)
+- Bridge-PIN nicht mitposten
+
+## 2. VS Code Debugger
+
+Wenn du den Plugin-Code lokal weiterentwickelst:
+
+`.vscode/launch.json` im Repo-Root anlegen:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Launch Homebridge with Plugin",
+      "program": "${env:HOME}/homebridge-test/node_modules/homebridge/bin/homebridge",
+      "args": [
+        "-U", "${env:HOME}/homebridge-test",
+        "--plugin-path", "${env:HOME}/homebridge-test/node_modules"
+      ],
+      "request": "launch",
+      "skipFiles": ["<node_internals>/**"],
+      "type": "pwa-node"
+    }
+  ]
+}
+```
+
+Vorausgesetzt du hast ein Test-Homebridge-Setup unter `~/homebridge-test/` und das Plugin per `npm link` reingezogen.
+
+## 3. Plugin-Files direkt anschauen
+
+Logs-Pfad bei einem hb-service-Setup (Homebridge UI X):
+
+- macOS: `~/Library/Logs/homebridge/`
+- Linux: `/var/log/homebridge/`
+- Via CLI: `hb-service logs`
+
+Häufige Fehlerbilder:
+
+| Symptom | Wahrscheinliche Ursache |
+|---|---|
+| `Can not find switch data` | Gerät hat keinen schaltbaren Relais-Ausgang (z.B. Energy 250) — falscher `accType` in Config |
+| `Can not find device with AIN: ...` | AIN-Tippfehler in Config, oder Gerät ist beim Plugin-Start offline an der FritzBox |
+| `TypeError: Cannot read properties of undefined (reading 'UUID')` | Custom-Characteristic nicht registriert — sollte mit v6.1.0-hb2patch.1+ nicht mehr auftreten. Falls doch: Plugin-Version prüfen (`npm ls -g @pellebot/homebridge-fritz-platform-hb2`), ggf. neu installieren |
+| `ECONNREFUSED` / TLS-Fehler beim Start | FritzBox-IP, Port (49443 für TR-064 SSL), oder TR-064-Zugriff in FritzBox-UI nicht aktiviert |
+| Polling läuft, aber Werte aktualisieren nicht | FritzBox-User hat keine "Smart Home"-Berechtigung → in FritzBox-UI prüfen |
+
+## Issues mit reproduzierbarem Debug-Output melden
+
+Wenn du nach diesen Schritten weiter Probleme hast, [öffne ein Issue](https://github.com/PelleBot/homebridge-fritz-platform-ng/issues/new/choose) und füge den relevanten Debug-Log-Auszug an. Bitte das Issue-Template nutzen — es führt durch alle nötigen Informationen.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Seyit Bayraktar <seydx@outlook.de>
+Copyright (c) 2026 PelleBot <pelle-bot@we-success.de>
+
+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,240 @@
+# @pellebot/homebridge-fritz-platform-hb2
+
+<p align="center">
+  <img src="branding/Icon.png" alt="Plugin Logo" width="160">
+</p>
+
+> Homebridge 2.0 plugin für AVM FRITZ!DECT Geräte und FRITZ!Box Router-Switches. Fokus: produktiver Betrieb auf Homebridge 2.0 mit Node 22 / 24.
+
+[![npm version](https://img.shields.io/npm/v/@pellebot/homebridge-fritz-platform-hb2.svg?style=flat-square)](https://www.npmjs.com/package/@pellebot/homebridge-fritz-platform-hb2)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Homebridge](https://img.shields.io/badge/homebridge-2.0%20%7C%201.8%2B-purple?style=flat-square)](https://github.com/homebridge/homebridge)
+[![Node](https://img.shields.io/badge/node-22%20%7C%2024-green?style=flat-square)](https://nodejs.org/)
+
+## Status
+
+Production: läuft produktiv beim Maintainer mit 12 DECT-Thermostaten, 1 DECT-Lampe, 2 Temperatursensoren, einem FRITZ!Smart Energy 250 OBIS-Reader an einem ISKRA-Stromzähler, sowie aktiven Router-Switches für Gast-WLAN und WPS — alles auf Homebridge 2.0.2 + Node 24 + FRITZ!OS 8.x.
+
+## Unterstützte Geräte
+
+| Gerätetyp | accType | Was wird in HomeKit angezeigt |
+|---|---|---|
+| FRITZ!DECT 301 / Comet DECT (Heizkörper-Thermostat) | `thermostat` | Soll-/Ist-Temperatur, Batterie, Fenster-offen-Erkennung |
+| FRITZ!Smart Light 500 / FRITZ!DECT 500 (DECT-Lampe) | `lightbulb` | An/Aus, Helligkeit, Farbe |
+| FRITZ!Smart Control 440 (Temperatursensor) | `temperature` | Temperatur, Batterie |
+| FRITZ!DECT 200 / 210 (schaltbare Steckdose) | `switch` | An/Aus + optional Energiemessung |
+| FRITZ!Smart Energy 250 (OBIS-Reader, an ISKRA o.ä.) | `energy-temperature` | Aktuelle Leistung in W, kumulierte Energie in kWh — als TemperatureSensor exposed, von Apple Home nativ als Zahlen-Tile dargestellt |
+| FRITZ!Box Router (Master) | (via `options`) | Gast-WLAN-Switch, WPS-Switch, optional weitere Toggles |
+
+## Architektur
+
+Das Plugin nutzt zwei AVM-Schnittstellen:
+
+- **TR-064** initialisiert die FritzBox-Verbindung (für AHA-API-Authentifizierung und Router-Steuerung). Konfiguration über `devices[]` mit `master: true`.
+- **AHA-HTTP-API** liest und steuert DECT-Geräte. Konfiguration über `smarthome[]` mit jeweils einer AIN pro Gerät.
+
+Das **Router-Accessory** (Master FritzBox) wird per default mit `hide: true` ausgeblendet. Wer Gast-WLAN und WPS als HomeKit-Tile haben will, konfiguriert das über das `options`-Objekt des Master-Devices (`wifi_guest: 'switch'`, `wps: 'switch'`).
+
+## Scope-Grenzen
+
+Aus dem ursprünglichen Code-Baum entfernt oder nicht migriert — wer eine dieser Funktionen braucht, ist hier nicht richtig:
+
+- **Callmonitor** (Anrufüberwachung)
+- **Presence** (WLAN-Anwesenheit)
+- **Network-Watcher**
+- **Wake-on-LAN**
+- **Child Lock** (Internet-Sperren)
+- **Extras-Subsysteme** (DNS-Switch, Fallback-Internet, Phonebook, Telegram-Notifications) — die WiFi/WPS-Switches der Extras-Datei sind ausgenommen und voll funktional
+- **`fakegato-history`** (Eve-App History-Graphen — als No-Op gestubbt weil HAP-v2-inkompatibel)
+
+## Voraussetzungen
+
+- **Homebridge** ≥ 1.8.5 oder ≥ 2.0.0
+- **Node.js** ≥ 22.12.0 oder ≥ 24.0.0
+- **FRITZ!Box** mit aktiviertem **TR-064-Zugriff** + dediziertem User mit "Smart Home"-Berechtigung (FRITZ!OS 7.x oder neuer)
+- Optional: **homebridge-config-ui-x** für die Web-UI-Konfiguration
+
+## Installation
+
+```bash
+npm install -g @pellebot/homebridge-fritz-platform-hb2
+```
+
+Vor der Veröffentlichung auf npm — direkt aus dem Git-Repo:
+
+```bash
+git clone https://github.com/PelleBot/homebridge-fritz-platform-ng.git
+cd homebridge-fritz-platform-ng
+npm pack
+sudo npm install -g ./pellebot-homebridge-fritz-platform-hb2-1.0.0.tgz
+```
+
+Anschließend Homebridge neu starten (z.B. via Config UI X "Restart"-Button oder `sudo hb-service restart`).
+
+## Konfiguration
+
+Minimal-Config (`~/.homebridge/config.json`):
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "FritzPlatform",
+      "name": "FritzBox",
+      "devices": [
+        {
+          "active": true,
+          "name": "FritzBox",
+          "host": "192.168.178.1",
+          "username": "homebridge-user",
+          "password": "DEIN_TR064_PASSWORT",
+          "ssl": true,
+          "tr064": true,
+          "master": true,
+          "hide": true,
+          "options": {
+            "wifi_guest": "switch",
+            "wps": "switch"
+          }
+        }
+      ],
+      "smarthome": [
+        {
+          "active": true,
+          "name": "Bad-Thermostat",
+          "ain": "099950870710",
+          "accType": "thermostat",
+          "temperature": true,
+          "window": true,
+          "battery": true
+        }
+      ],
+      "options": {
+        "polling": {
+          "timer": 30
+        }
+      }
+    }
+  ]
+}
+```
+
+Vollständige Optionen über das **Homebridge Config UI X** Plugin grafisch unterstützt.
+
+### Router-Switches (Gast-WLAN + WPS)
+
+Im Master-Device-Block die `options` ergänzen:
+
+```json
+{
+  "options": {
+    "wifi_guest": "switch",
+    "wps": "switch"
+  }
+}
+```
+
+Damit erscheinen zwei zusätzliche Tiles in HomeKit. Empfehlung: in der Home-App umbenennen ("Gast-WLAN", "WPS") für klarere Beschriftung als der vom Plugin generierte Default `<Master-Name> Wifi guest` / `<Master-Name> Wps`.
+
+### FRITZ!Smart Energy 250 (OBIS-Reader)
+
+Die Smart Energy 250 ist ein HAN-FUN-Gateway, der einen externen Stromzähler (ISKRA o.ä.) per OBIS-Reader anbindet. AVM stellt zwei Sub-AINs bereit:
+
+- `<base-AIN>-1` → OBIS 1.8 (Verbrauch / Bezug)
+- `<base-AIN>-2` → OBIS 2.8 (Einspeisung)
+
+Für ein typisches PV-Setup mit Bezug + Einspeisung legst du **vier `smarthome[]`-Einträge** an — je AIN ein aktueller Watt-Wert und ein kumulierter kWh-Wert:
+
+```json
+{
+  "smarthome": [
+    {
+      "active": true,
+      "name": "Aktueller Verbrauch",
+      "ain": "152820924403-1",
+      "accType": "energy-temperature",
+      "obisChannel": "current_power"
+    },
+    {
+      "active": true,
+      "name": "Gesamt Verbrauch",
+      "ain": "152820924403-1",
+      "accType": "energy-temperature",
+      "obisChannel": "total_energy"
+    },
+    {
+      "active": true,
+      "name": "Aktuelle Einspeisung",
+      "ain": "152820924403-2",
+      "accType": "energy-temperature",
+      "obisChannel": "current_power"
+    },
+    {
+      "active": true,
+      "name": "Gesamt Einspeisung",
+      "ain": "152820924403-2",
+      "accType": "energy-temperature",
+      "obisChannel": "total_energy"
+    }
+  ]
+}
+```
+
+**Wieso TemperatureSensor?** HomeKit hat keinen nativen Service für Leistung oder Energie. TemperatureSensor wird hier als Anzeige-Vehikel "missbraucht": Apple Home rendert den Wert nativ als Zahl, plottet Verlaufsgraphen, und ist auf allen HomeKit-Clients ohne Eve-App-Abhängigkeit sichtbar. **Trade-off:** die Einheit zeigt `°C` an, gemeint sind aber `W` oder `kWh`. In der Home-App das Tile umbenennen ("Aktueller Verbrauch (W)", "Gesamt Einspeisung (kWh)") macht's eindeutig.
+
+**Richtungs-Trennung:** AVM spiegelt den NET-Power-Wert auf beiden Sub-AINs (gleiche Zahl mit Vorzeichen). Das Plugin trennt das anhand des AIN-Suffixes — `-1` zeigt den Wert nur wenn `power > 0` (Bezug), `-2` zeigt `|power|` nur wenn `power < 0` (Einspeisung). Im Ruhe-/Inverse-Zustand zeigt die jeweils andere Kachel `0`.
+
+## Migration vom Original-Plugin
+
+Wenn du bisher das unmaintained Original `homebridge-fritz-platform@6.0.19` eingesetzt hast:
+
+1. **Backup** dein `~/.homebridge/` Verzeichnis: `cp -R ~/.homebridge ~/.homebridge.backup`
+2. **Update Homebridge auf 2.x**: `sudo npm install -g homebridge@latest`
+3. **Original-Plugin entfernen**: `sudo npm uninstall -g homebridge-fritz-platform`
+4. **Dieses Plugin installieren**: `sudo npm install -g @pellebot/homebridge-fritz-platform-hb2`
+5. **Config anpassen**: nicht-mehr-unterstützte Subsysteme aus der Config entfernen (`presence`, `callmonitor`, `wol`, `childLock`, `network`, `extras`, `telegram` — werden eh ignoriert, aber sauberer wenn weg).
+6. **Homebridge neu starten**
+
+Accessory-UUIDs basieren auf AIN + Name. Wer Device-Namen unverändert lässt, behält das HomeKit-Pairing bei und muss nichts in der Home-App neu zuordnen.
+
+## Troubleshooting
+
+Siehe [`DEBUG.md`](./DEBUG.md) für:
+- Plugin-Debug-Mode aktivieren
+- VS Code Debugger Setup
+- Häufige Fehlerbilder + Lösungen
+- Log-Pfade auf macOS / Linux
+
+## Issues melden
+
+Bevor du ein Issue öffnest, bitte zusammenstellen:
+
+- Homebridge-Version (`homebridge --version`)
+- Node-Version (`node --version`)
+- Plugin-Version (`npm ls -g @pellebot/homebridge-fritz-platform-hb2`)
+- FritzBox-Modell + FRITZ!OS-Version
+- Relevante Log-Auszüge (idealerweise mit `"debug": true` in der Plugin-Config)
+- Config-Auszug (ohne Passwort!)
+
+Issue-Template im Repo führt durch alle Punkte.
+
+## Maintenance-Modell
+
+Dieser Plugin wird **LLM-unterstützt** gepflegt (siehe [`CONCEPT.md`](./CONCEPT.md)):
+
+- PelleBot ist menschlicher Maintainer, Repo-Owner, Final-Reviewer
+- Code-Patches, Doc-Updates und Issue-Antworten werden mit Hilfe eines LLM (Claude) entworfen
+- Jede Änderung wird vom menschlichen Maintainer geprüft, bevor sie committed wird
+- Es gibt **keine automatischen Bot-Antworten** auf Issues — Reaktionszeit kann daher etwas länger sein, dafür ist Qualität konsistent
+
+Pull Requests willkommen. Issues mit Label `discussion` für offene Architektur-Themen.
+
+## Lineage
+
+Dieses Plugin baut auf der Code-Basis des [`homebridge-fritz-platform`](https://github.com/SeydX/homebridge-fritz-platform) Projekts von Seyit Bayraktar (SeydX) auf. Ohne seine jahrelange Vorarbeit (2020-2022) wäre die HB-2.0-Migration nicht in dieser Zeit machbar gewesen.
+
+Lizenz: MIT — siehe [`LICENSE`](./LICENSE), Copyright-Halter sind dort beide aufgeführt.
+
+## Disclaimer
+
+Alle Produkt- und Firmennamen (FRITZ!Box®, AVM®, HomeKit™, etc.) sind Marken ihrer jeweiligen Eigentümer. Die Verwendung impliziert keine Affiliation oder Empfehlung. Dieses Plugin ist **kein offizielles AVM- oder Apple-Produkt**.