@impact0815/node-red-contrib-home-connect 0.0.0-stage → 0.2.0

package/docs/MESSAGE-API.md

@@ -0,0 +1,111 @@
+# Message API
+
+All functional nodes preserve unrelated incoming properties. Output 2 contains a structured error in `msg.payload`. Confirmation values are removed from success and error output.
+
+## Normalized health envelope
+
+Every functional output includes:
+
+```js
+msg.health = 'ok'; // ok | running | info | warning | action_required | offline | error
+msg.warnings = [{
+  source: 'status',       // status | event | connection | api | oauth
+  code: 'HC_...',         // stable integration code
+  severity: 'warning',    // info | warning | error | critical
+  text: { de: '...', en: '...' },
+  transient: false
+}];
+msg.homeConnect.health = msg.health;
+msg.homeConnect.warnings = msg.warnings;
+msg.homeConnect.healthSchema = 'home-connect-health/v1';
+msg.homeConnect.healthAt = '...';
+```
+
+Snapshots and discovery entries also carry `payload.health`, `payload.warnings`, `payload.healthSchema`, and `payload.healthAt`. Raw API status and event values are retained. Transient notices are deduplicated and expire; disconnected/offline state remains until a later connection or snapshot confirms recovery. Errors are assessed for that error output and do not poison later successful messages.
+
+## discover
+
+```js
+msg.haId = '...';   // single mode
+msg.force = true;   // bypass five-minute capability cache
+```
+
+No real appliance ID, name, program or capability is built into the package. The editor's **Load devices** button and discovery output use the appliances returned by the connected account or protected local profiles. For local connections, Host/IP and the optional Auto/AES/TLS choice exist only in `home-connect-config`; Read and Events nodes store only a selected appliance/profile ID.
+
+Documented appliance fields such as `name`, `brand`, `type`, `vib` and `connected` remain available under `appliance`. Firmware version/history/update is not part of the public API and has no message operation.
+
+## read
+
+```js
+msg.haId = '...';
+msg.operation = 'snapshot';
+msg.key = '...';       // resource key, map ID or cleaning-summary counter
+msg.subKey = '...';    // detected object, room or zone ID
+```
+
+Operations:
+
+- `snapshot`, `capabilities`, `appliances`, `appliance`
+- `status`, `status-item`, `settings`, `setting`
+- `all-programs`, `programs`, `program`
+- `active-program`, `active-options`, `active-option`
+- `selected-program`, `selected-options`, `selected-option`
+- `commands`, `images`, `image`
+- `maps`, `map`, `map-occupancy-grid`, `map-layout`, `map-cleaning-status`
+- `map-detected-objects`, `map-detected-object`, `map-rooms`, `map-room`, `map-zones`, `map-zone`
+- `map-robot-position`, `map-config-restrictions`, `map-cleaning-summaries`, `map-cleaning-summary`
+
+`image` returns:
+
+```js
+msg.payload = {
+  contentType: 'image/jpeg',
+  data: Buffer.from(/* JPEG bytes */)
+};
+```
+
+The operation may select only a predefined resource; it cannot provide a URL or HTTP method. Local connections support appliance/snapshot/status/settings/program reads derived from `/ro/*` values. Cloud-only image/map operations return `LOCAL_READ_UNSUPPORTED` locally.
+
+## events
+
+An input message with `msg.haId` restarts the stream for that appliance. Use `*` for all configured appliances. The cloud client reconnects SSE with bounded exponential backoff and sends `Last-Event-ID` when supplied. The local client maintains per-appliance WebSockets and emits `STATUS`. Both emit synthetic `CONNECTED` and `DISCONNECTED` lifecycle events. Local event envelopes include `connection.local: true` and `connection.readOnly: true`.
+
+## write
+
+A request can be supplied in `msg.payload`; top-level `msg.haId`, `msg.action`, `msg.program`, `msg.key`, `msg.value` and `msg.options` take precedence.
+
+### Start a program
+
+```js
+msg.payload = {
+  action: 'start-program',
+  haId: '...',
+  program: 'Cooking.Oven.Program.HeatingMode.HotAir',
+  options: [{ key: 'Cooking.Oven.Option.SetpointTemperature', value: 180 }],
+  confirm: 'CONFIRM'
+};
+```
+
+### Other actions
+
+```js
+msg.payload = { action: 'stop-program', haId: '...', confirm: 'CONFIRM' };
+msg.payload = { action: 'select-program', haId: '...', program: '...', options: [], confirm: 'CONFIRM' };
+msg.payload = { action: 'set-setting', haId: '...', key: 'BSH.Common.Setting.PowerState', value: 'BSH.Common.EnumType.PowerState.Standby', confirm: 'CONFIRM' };
+msg.payload = { action: 'command', haId: '...', key: 'BSH.Common.Command.PauseProgram', value: true, confirm: 'CONFIRM' };
+msg.payload = { action: 'set-active-option', haId: '...', key: 'BSH.Common.Option.Duration', value: 600, confirm: 'CONFIRM' };
+msg.payload = { action: 'set-selected-option', haId: '...', key: '...', value: '...', confirm: 'CONFIRM' };
+```
+
+Options may also be an object shorthand:
+
+```js
+msg.options = {
+  'Cooking.Oven.Option.SetpointTemperature': 180,
+  'BSH.Common.Option.Duration': { value: 1800, unit: 'seconds' }
+};
+```
+
+Arbitrary methods, paths, body envelopes and bulk writes are intentionally unsupported. The confirmation token is stored in Node-RED credentials rather than in the flow JSON.
+
+Local configurations reject every write with `LOCAL_READ_ONLY` before capability validation or network I/O. This cannot be overridden by `msg`, editor fields, or `allowWrite`.

package/docs/RELEASE.md

@@ -0,0 +1,78 @@
+# Release procedure for 0.2.0
+
+The feature set is frozen at build `hc-0.2.0-final`. Do not add features after this point; only release-blocking corrections are allowed, followed by the complete validation sequence.
+
+## Required release inputs
+
+- `docs/images/dashboard-overview-en.png`
+- `docs/images/dashboard-details-en.png`
+- `examples/demo-home-connect-flowfuse-1.34.1-scriptless.json`
+
+The screenshots must come from the isolated simulated Demo and must be visually reviewed for browser/account context, hostnames, addresses, real appliance IDs, tokens, QR codes, profiles, unrelated tabs, and notifications.
+
+## Final local checks
+
+```bash
+npm ci --ignore-scripts
+npm run release:check
+npm run validate
+npm pack --json
+sha256sum node-red-contrib-home-connect-0.2.0.tgz
+```
+
+Inspect the exact package payload:
+
+```bash
+tar -tzf node-red-contrib-home-connect-0.2.0.tgz | sort
+npm publish --dry-run ./node-red-contrib-home-connect-0.2.0.tgz --access public
+```
+
+## First GitHub publication
+
+Create `impact0815/node-red-contrib-home-connect` as an empty public repository, without generated README, license, or `.gitignore`, then run:
+
+```bash
+git init -b main
+git add .
+git status --short
+git commit -m "Release node-red-contrib-home-connect 0.2.0"
+git remote add origin https://github.com/impact0815/node-red-contrib-home-connect.git
+git push -u origin main
+```
+
+After GitHub Actions CI succeeds on `main`:
+
+```bash
+git tag -a v0.2.0 -m "node-red-contrib-home-connect 0.2.0"
+git push origin v0.2.0
+gh release create v0.2.0 \
+  ./node-red-contrib-home-connect-0.2.0.tgz \
+  ./SHA256SUMS.txt \
+  --title "node-red-contrib-home-connect 0.2.0" \
+  --notes-file RELEASE_NOTES.md
+```
+
+## npm publication
+
+Confirm the account and package name before publishing:
+
+```bash
+npm whoami
+npm view node-red-contrib-home-connect versions --json
+npm publish ./node-red-contrib-home-connect-0.2.0.tgz --access public
+npm view node-red-contrib-home-connect@0.2.0 version dist.integrity dist.tarball
+```
+
+If the unscoped npm name is not controlled by the publisher, stop. Do not silently rename or publish under a different scope; update package metadata, documentation, lockfile, and release plan as one reviewed change.
+
+## Post-publication smoke test
+
+```bash
+TMPDIR="$(mktemp -d)"
+cd "$TMPDIR"
+npm init -y
+npm install node-red-contrib-home-connect@0.2.0
+node -p "require('node-red-contrib-home-connect/BUILD-INFO.json')"
+```
+
+The build ID must be `hc-0.2.0-final`.

package/docs/TROUBLESHOOTING.de.md

@@ -0,0 +1,230 @@
+# Home Connect: Troubleshooting und FAQ
+
+Zurück zur [deutschen README](../README.de.md).
+
+Diese Anleitung beginnt beim sichtbaren Symptom. Zugangsdaten, Hostnamen, Geräte-IDs und OAuth-Codes gehören nie in Fehlerberichte.
+
+## 1. Vorprüfung in zwei Minuten
+
+1. Läuft wirklich der erwartete Build?
+   ```bash
+   cd ~/.node-red
+   node -p "require('./node_modules/node-red-contrib-home-connect/BUILD-INFO.json')"
+   ```
+   Erwartet: Version `0.2.0`, Build `hc-0.2.0-final`, `pkce: false`.
+2. Ist die richtige Connection ausgewählt und eindeutig benannt?
+3. Wurde nach der letzten Änderung **Fertig → Deploy** ausgeführt?
+4. Sind Redirect URI im Developer Portal und in Node-RED exakt gleich?
+5. Ist die Node-RED-Adresse vom verwendeten Browser erreichbar?
+6. Wurde OAuth bis zur Seite **Home Connect authorized** abgeschlossen?
+7. Enthalten die Scopes mindestens `IdentifyAppliance` und die benötigten gerätespezifischen Rechte?
+
+## 2. Autorisieren ist deaktiviert
+
+Das ist Absicht: Die Config-Node prüft, ob genau diese gespeicherte Konfiguration bereits in der laufenden Node-RED-Runtime existiert.
+
+- **Neue/änderte Verbindung:** Fertig klicken, deployen, Verbindung erneut öffnen.
+- **Integrierter Simulator:** OAuth ist nicht erforderlich.
+- **Weiterhin deaktiviert:** Node-RED vollständig neu starten und Browser hart neu laden. Prüfen, ob eine zweite/alte Paketinstallation existiert.
+
+## 3. `CONFIG_NOT_FOUND`
+
+**Bedeutung:** Die URL enthält die ID einer Config-Node, welche die laufende Runtime nicht kennt.
+
+Typische Ursachen:
+
+- Beispiel- oder Simulator-Config wurde referenziert.
+- Verbindung wurde zwar im Editor angelegt, aber nicht deployt.
+- Alter Browser-Tab enthält eine Autorisierungs-URL einer gelöschten Config.
+- Nach Paket-/Flow-Wechsel läuft noch eine andere Runtime-Instanz.
+
+**Behebung:**
+
+1. Alten Auth-Tab schließen.
+2. Im verwendeten Home-Connect-Node die richtige Connection wählen.
+3. Connection eindeutig benennen.
+4. Fertig → Deploy.
+5. Connection erneut öffnen.
+6. Autorisierung über den dortigen Knopf neu starten.
+
+## 4. Falsche oder irreführende Verbindungsbezeichnung
+
+Technisch steuert das Feld **Umgebung** den API-Host, nicht der Name. Ein Name wie `Simulator` bei Umgebung `Production` erhöht aber das Fehlerrisiko. Die Oberfläche zeigt deshalb eine Warnung. Name korrigieren, speichern und deployen.
+
+## 5. Redirect URI: exakter Vergleich
+
+Folgende Teile müssen identisch sein:
+
+| Teil | Häufiger Fehler |
+|---|---|
+| Protokoll | `http` im Portal, `https` in Node-RED |
+| Host | DNS-Name im Portal, IP-Adresse in Node-RED |
+| Port | Port fehlt auf einer Seite |
+| Pfad | Tippfehler in `/home-connect/oauth/callback` |
+| Ende | zusätzlicher Slash `/callback/` |
+| Groß-/Kleinschreibung | abweichende Zeichen im Pfad |
+
+Am sichersten die vollständige URI aus einem Feld kopieren und im anderen einfügen.
+
+## 6. Nach Login: localhost, `ERR_EMPTY_RESPONSE`, Verbindung fehlgeschlagen
+
+`localhost` zeigt aus Sicht des Browsers auf das Browser-Gerät. Läuft Node-RED auf NAS, Server, Raspberry Pi, Home Assistant, ioBroker oder in einem anderen Rechner/Container, erreicht der Browser dort nicht Node-RED.
+
+1. Einen vom Browser erreichbaren Hostnamen oder eine erreichbare IP-Adresse für Node-RED wählen.
+2. Callback-Pfad anhängen: `/home-connect/oauth/callback`.
+3. URI im Developer Portal ändern.
+4. Dieselbe URI in Node-RED eintragen.
+5. Fertig → Deploy.
+6. OAuth neu starten.
+
+## 7. `unauthorized_client` / `client or redirection URI not authorized`
+
+Prüfreihenfolge:
+
+1. Wurde Client ID aus der richtigen Developer-Portal-Application kopiert?
+2. Stimmt die Redirect URI Zeichen für Zeichen?
+3. Verwendet die Application den Authorization Code Grant?
+4. Ist PKCE in dieser Application deaktiviert?
+5. Läuft der Build `hc-0.2.0-final`?
+6. Wurde nach jeder Änderung eine neue Autorisierung gestartet?
+
+Wurde das Client Secret sichtbar, nicht weiter testen: Secret regenerieren, in Node-RED ersetzen, deployen und neu autorisieren.
+
+## 8. Nach Update läuft alter Code
+
+Ein Flow-Deploy lädt keinen neuen Node.js-Runtime-Code. Zusätzlich zur npm-Version BUILD-INFO prüfen, um doppelte Installationen zu erkennen.
+
+```bash
+cd ~/.node-red
+npm uninstall node-red-contrib-home-connect
+rm -rf node_modules/node-red-contrib-home-connect
+npm install --force /absoluter/pfad/node-red-contrib-home-connect-0.2.0.tgz
+node -p "require('./node_modules/node-red-contrib-home-connect/BUILD-INFO.json')"
+```
+
+Danach Node-RED/Container vollständig neu starten, Browser hart neu laden und OAuth neu beginnen. Authorization Codes und State-Links sind kurzlebig/einmalig und dürfen nicht wiederverwendet werden.
+
+## 9. `No refresh token is stored. Complete OAuth authorization first.`
+
+Der Refresh Token wird erst beim erfolgreichen Callback gespeichert.
+
+- Autorisierung aus der deployten Connection starten.
+- Login und Zustimmung abschließen.
+- Auf **Home Connect authorized** warten.
+- Erst dann Test/Discover/Read/Events ausführen.
+
+Bleibt der Fehler, den Fehler auf der Callback-Seite notieren, aber keine Codes/Tokens veröffentlichen.
+
+## 10. `insufficient_scope`
+
+Der Token darf die angeforderte Ressource nicht lesen oder steuern.
+
+1. `IdentifyAppliance` beibehalten.
+2. Passenden gerätespezifischen Scope ergänzen, etwa `Dishwasher-Monitor`, `Washer-Monitor` oder `Oven-Monitor`.
+3. Für Aktionen zusätzlich nur benötigtes `*-Control` und/oder `*-Settings` ergänzen.
+4. Fertig → Deploy.
+5. Neu autorisieren; ein alter Refresh Token erhält nicht automatisch neue Rechte.
+
+Der allgemeine Scope `Monitor` kann je nach Application/Konto unzureichend sein.
+
+## 11. Events zeigt dauerhaft `reconnecting`
+
+`reconnecting` ist ein Folgezustand, nicht die eigentliche Ursache. Den zweiten Ausgang des Events-Nodes mit Debug verbinden.
+
+Häufig:
+
+- kein Refresh Token
+- fehlender Monitor-Scope
+- abgelaufene/entzogene Autorisierung
+- Netzwerk-/Proxy-Unterbrechung des SSE-Streams
+- zu viele parallele Event-Streams
+
+Zuerst Geräteliste/Test reparieren, dann einen einzigen Events-Node mit Appliance ID `*` verwenden.
+
+## 12. Erfolgsbild
+
+Die Einrichtung ist abgeschlossen, wenn:
+
+1. die Browserseite **Home Connect authorized** anzeigt,
+2. Test ohne Fehler eine Geräteanzahl meldet,
+3. **Geräte laden** die Auswahl befüllt,
+4. der Events-Node nach Verbindung Events ausgibt statt dauerhaft zu reconnecten.
+
+## 13. Sicheres Fehlerreporting
+
+Erlaubt:
+
+- Paketversion und Build-ID
+- Node.js- und Node-RED-Version
+- Umgebungstyp (Production/Simulator), ohne privaten Hostnamen
+- Fehlercode und bereinigte Fehlermeldung
+- Schritte zur Reproduktion mit Simulator
+
+Nicht veröffentlichen:
+
+- Client ID oder Client Secret
+- Access-/Refresh-Token
+- Authorization Code oder OAuth-State
+- echte Redirect-URI/Hostname/IP
+- echte `haId`, Serien-/Gerätenummern
+- vollständige Events oder Debug-Ausgaben mit persönlichen Daten
+
+
+## 14. Health- und Warning-Codes verstehen
+
+Jede funktionale Ausgabe enthält das Schema `home-connect-health/v1`:
+
+- `ok`: keine aktuelle Auffälligkeit
+- `running`: Programm läuft
+- `info`: nützlicher, nicht dringender Hinweis
+- `warning`: Einschränkung oder pausierter/abbrechender Zustand
+- `action_required`: Eingriff oder neue Autorisierung erforderlich
+- `offline`: Gerät, Event-Stream oder Netzwerk nicht erreichbar
+- `error`: Geräte-/API-Fehler
+
+`warnings` ist dedupliziert. Jeder Eintrag enthält mindestens `source`, `code`, `severity`, `text.de`, `text.en` und `transient`. Kurzlebige Hinweise besitzen zusätzlich Zeitfelder und verschwinden nach Ablauf. Statusbedingungen bleiben nur so lange bestehen, wie der aktuelle Status sie bestätigt.
+
+Wichtige Codes:
+
+| Code | Bedeutung | Maßnahme |
+|---|---|---|
+| `HC_OPERATION_ACTION_REQUIRED` | Gerät fordert lokalen Eingriff | Gerätedisplay/Tür/Vorräte prüfen |
+| `HC_STREAM_DISCONNECTED` | SSE-Verbindung getrennt | Reconnect abwarten; bei Dauerfehler Ausgang 2 prüfen |
+| `HC_OAUTH_INSUFFICIENT_SCOPE` | Token hat zu wenige Rechte | Scope korrigieren, deployen, neu autorisieren |
+| `HC_OAUTH_AUTHORIZATION_EXPIRED` | Autorisierung fehlt/abgelaufen/widerrufen | neu autorisieren |
+| `HC_API_RATE_LIMITED` | HTTP 429/API-Limit | Polling reduzieren, `retryAfter` beachten |
+| `HC_NETWORK_ERROR` | Netzwerk/Timeout | DNS, Proxy, TLS und Erreichbarkeit prüfen |
+
+Der Events-Node erzeugt zusätzlich synthetische `CONNECTED`-/`DISCONNECTED`-Lebenszyklusereignisse für den tatsächlichen SSE-Stream. Sie enthalten keine Zugangsdaten.
+
+## 15. HTTP 429 / `1000 calls in 1 day`
+
+Der lokale Limiter verhindert standardmäßig, dass dieses Paket mehr als 900 API-Versuche in einem rollierenden 24-Stunden-Fenster sendet. In der Verbindung werden der aktuelle Verbrauch und eine eventuelle Sperrzeit angezeigt. Bei ausgeschöpftem Budget erscheint `LOCAL_RATE_LIMITED`; `retryAfter` und `resetAt` geben die verbleibende Wartezeit an.
+
+Wenn Home Connect bereits HTTP 429 mit einer Meldung wie `remaining period of 75502 seconds` zurückgegeben hat, übernimmt das Paket diese Sperrzeit und sendet bis dahin keine weiteren API-Aufrufe. Der Zustand bleibt über Deploys und Neustarts erhalten. Nicht wiederholt auf **Test** oder Inject-Nodes klicken. Polling deutlich reduzieren, nach Möglichkeit einen All-Appliance-Event-Stream verwenden und Snapshots nicht alle 15 Sekunden abrufen. Andere Rechner oder Programme mit derselben Developer-Portal-Application separat prüfen, da sie nicht vom lokalen Zähler erfasst werden.
+
+## 16. Firmwareversion oder Firmwareupdate fehlt
+
+Das ist kein Konfigurationsfehler. Die öffentlich dokumentierte Home-Connect-API stellt Firmwareversion, Firmwarehistorie und Firmwareupdate nicht bereit. Das Paket verwendet keine undokumentierten Endpunkte und bietet absichtlich keinen Firmware-Button. Sichtbar sind nur dokumentierte Geräteinformationen wie Name, Marke, Typ, `vib`/E-Nummer und Verbindungsstatus, sofern geliefert. Firmware ausschließlich über offizielle Hersteller-/Home-Connect-Kanäle prüfen.
+
+## 17. Lokale LAN-Profile und Verbindungsfehler
+
+Bei lokalen Konfigurationen sind OAuth-, Autorisierungs-, Refresh-Token- und Cloud-Tagesbudget-Bereiche absichtlich ausgeblendet. Erfolgreich ist die Einrichtung, wenn **Verbindung testen** in jeder Gerätekarte eine lokale Read-only-Verbindung meldet und Discover/Read/Events `local: true` sowie `readOnly: true` liefern.
+
+In dieser Reihenfolge prüfen:
+
+1. Prüfen, ob der Profilordner im Node-RED-Host/-Container wirklich unter dem eingetragenen Pfad gemountet und für das Servicekonto lesbar ist. Dann ausdrücklich **Profile suchen / Geräte erkennen** anklicken.
+2. Geräte-JSON, `DeviceDescription.xml` und `FeatureMapping.xml` desselben Profile-Downloader-Exports zusammenlassen. `LOCAL_PROFILE_FILES_INCOMPLETE` nennt die fehlende Datei; `LOCAL_PROFILE_ORPHAN_COMPANION` weist auf unpassende Ordner/Dateinamen hin.
+3. Bei einer doppelten Profil-ID nennt der Scanner die betroffenen Dateien. Keine Zuordnung raten: doppelten/alten Export entfernen und erneut suchen.
+4. Nach erfolgreicher Suche muss zum Beispiel **3 Geräteprofile gefunden** erscheinen. Für jedes vollständige Profil gibt es genau eine Karte. Fehlt eine Karte, die Hinweise direkt unter dem Suchergebnis lesen.
+5. In jeder Karte Host/IP eintragen. Fehlende, formal falsche oder öffentliche IPs werden rot markiert. Hostnamen werden beim Test serverseitig aufgelöst. Nur private/link-lokale Ziele sind erlaubt; Loopback und öffentliche Ziele werden mit `LOCAL_HOST_NOT_PRIVATE` abgewiesen. Ein Einzeltest verwendet sofort die aktuellen Felder genau dieser Karte, benötigt noch kein Fertig/Deploy und wird nicht von leeren Nachbarkarten blockiert.
+6. **Verbindungsart: Auto (empfohlen)** beibehalten. Eine ausdrückliche Profilangabe AES/TLS/PSK hat Vorrang; IV-Anwesenheit ist nur der Fallback. `LOCAL_PROFILE_IV_MISSING` bei AES-Override bedeutet, dass das Original-IV fehlt.
+7. Pro Karte **Verbindung testen** anklicken und die sieben Stufen lesen. `LOCAL_NETWORK_ERROR`/Timeout stoppt bei **IP erreichbar**. `EHOSTUNREACH` ist ein fehlender Netzwerkpfad und kein Protokollfehler: Gerät aus/Standby, IP, WLAN, VLAN-Routing und Firewall prüfen. `LOCAL_TLS_PSK_UNAVAILABLE`/`LOCAL_TRANSPORT_UNSUPPORTED` stoppt bei **Transport erkannt**. `LOCAL_WEBSOCKET_UPGRADE_FAILED` bedeutet: TCP beziehungsweise TLS war erfolgreich, aber das Gerät lehnte den Upgrade auf `/homeconnect` ab. Der Test liest nur lokale Ressourcen.
+8. Erst wenn alle Karten gültig sind: **Fertig → Deployen**. Dabei wird `localDeviceMappings` nochmals gespeichert und nach Deploy wiederhergestellt. Host/IP nie in Read-/Events-Nodes eintragen; dort die verständliche Bezeichnung wählen, während intern die volle ID erhalten bleibt.
+9. `LOCAL_CRYPTO_AUTH_FAILED`, `LOCAL_PROFILE_KEY_REJECTED` oder `LOCAL_PROFILE_AUTHENTICATION_FAILED` bedeutet falsches/unvollständiges Profil; PSK/IV weder bearbeiten noch raten. `LOCAL_PROTOCOL_REJECTED` ist davon getrennt und nennt Ressource, Aktion, ausgehandelte Version und Gerätecode. Einzelne nicht unterstützte `/ro/*`-Pfade sind zulässig, sobald ein anderer Read oder ein Geräte-`NOTIFY` Werte geliefert hat. Werden alle fünf Pfade abgelehnt, enthält `rejectedResources` die komplette Folge. `/ci/services` muss Version 1 ohne leeres `data`-Array verwenden.
+10. Werden nur numerische UIDs angezeigt, die XML-Dateien desselben Downloads wiederherstellen und neu suchen.
+11. Manuelles Profil-JSON ist nur der optionale Bereich **Erweitert**. Bei gesetztem Ordner ist es deaktiviert/ignoriert. Bei Bedarf mit der Schaltfläche aus erkannten Profilen und Zuordnungen erzeugen statt selbst schreiben.
+12. Für reale Firmwareabweichungen unter **Erweitert** den sicheren Protokoll-Mitschnitt kurz aktivieren. Ohne Pfad erscheint nur der begrenzte, bereinigte Speicherpuffer beim Test; ein absoluter Pfad schreibt unter POSIX JSONL mit `0600`. Unter Windows den Mitschnittpfad per NTFS-ACL auf das Node-RED-Dienstkonto beschränken, weil POSIX-Rechte dort nicht zuverlässig sind. PSK, IV, Schlüssel, Nonces sowie Geräte-/Netzwerkkennungen werden entfernt. Vor Weitergabe trotzdem prüfen, danach ausschalten und Datei löschen.
+13. `LOCAL_HEARTBEAT_TIMEOUT` oder `LOCAL_DISCONNECTED` nach zunächst erfolgreicher Verbindung deutet auf Strom/Standby, WLAN-Roaming, VLAN/Firewall oder Paketverlust. Die Runtime baut Transport, Kryptozustand, `sID`, `msgID`, Services und Read-Session mit Backoff vollständig neu auf.
+
+`LOCAL_READ_ONLY` ist kein Verbindungsfehler, sondern die erfolgreiche lokale Schreibsperre. Für abgesicherte Schreibzugriffe eine separate Cloud-Konfiguration verwenden. Siehe [Lokale LAN-Verbindung](LOCAL-LAN.de.md).

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,230 @@
+# Home Connect troubleshooting and FAQ
+
+Back to the [English README](../README.md).
+
+Start with the visible symptom. Never include credentials, hostnames, appliance IDs, or OAuth codes in a bug report.
+
+## 1. Two-minute preflight check
+
+1. Is the expected build installed?
+   ```bash
+   cd ~/.node-red
+   node -p "require('./node_modules/node-red-contrib-home-connect/BUILD-INFO.json')"
+   ```
+   Expect version `0.2.0`, build `hc-0.2.0-final`, and `pkce: false`.
+2. Is the correct connection selected and clearly named?
+3. Did you click **Done → Deploy** after the latest change?
+4. Are the Redirect URIs in the Developer Portal and Node-RED exactly identical?
+5. Can the browser reach the configured Node-RED address?
+6. Did OAuth finish on the **Home Connect authorized** page?
+7. Do scopes include `IdentifyAppliance` and the required appliance-specific permissions?
+
+## 2. Authorize is disabled
+
+This is intentional: the configuration node checks whether this exact saved configuration exists in the running Node-RED runtime.
+
+- **New or changed connection:** click Done, deploy, and reopen the connection.
+- **Built-in simulator:** OAuth is not required.
+- **Still disabled:** restart Node-RED completely and hard-reload the browser. Check for an old or duplicate package installation.
+
+## 3. `CONFIG_NOT_FOUND`
+
+**Meaning:** the URL contains the ID of a configuration node that the running runtime does not know.
+
+Typical causes:
+
+- an example or simulator configuration was referenced;
+- the connection was created in the editor but not deployed;
+- an old browser tab contains an authorization URL for a deleted configuration;
+- another runtime instance is still active after a package or flow change.
+
+**Fix:**
+
+1. Close the old authorization tab.
+2. Select the correct connection in the Home Connect node.
+3. Give it an unambiguous name.
+4. Click Done → Deploy.
+5. Reopen the connection.
+6. Start a new authorization from that connection.
+
+## 4. Misleading connection name
+
+The **Environment** field controls the API host; the name does not. A name such as `Simulator` with the Production environment is still risky. The editor now warns about this combination. Rename, save, and deploy it.
+
+## 5. Exact Redirect URI comparison
+
+These parts must match:
+
+| Part | Common mistake |
+|---|---|
+| Protocol | `http` in the portal, `https` in Node-RED |
+| Host | DNS name in one place, IP address in the other |
+| Port | port omitted in one place |
+| Path | typo in `/home-connect/oauth/callback` |
+| Ending | extra slash `/callback/` |
+| Case | different characters in the path |
+
+Copy the complete URI from one field to the other instead of retyping it.
+
+## 6. After sign-in: localhost, `ERR_EMPTY_RESPONSE`, connection failed
+
+From the browser's perspective, `localhost` is the browser's own computer. If Node-RED runs on a NAS, server, Raspberry Pi, Home Assistant, ioBroker, or another computer/container, the browser cannot reach Node-RED there via localhost.
+
+1. Choose a Node-RED hostname or IP address reachable from the browser.
+2. Append `/home-connect/oauth/callback`.
+3. Change the URI in the Developer Portal.
+4. Enter the identical URI in Node-RED.
+5. Click Done → Deploy.
+6. Start OAuth again.
+
+## 7. `unauthorized_client` / `client or redirection URI not authorized`
+
+Check in this order:
+
+1. Was the Client ID copied from the correct Developer Portal Application?
+2. Does the Redirect URI match character for character?
+3. Does the Application use the Authorization Code Grant?
+4. Is PKCE disabled for that Application?
+5. Is build `hc-0.2.0-final` running?
+6. Did you start a new authorization after each change?
+
+If the Client Secret was exposed, stop troubleshooting with that value: regenerate it, replace it in Node-RED, deploy, and authorize again.
+
+## 8. Old code still runs after an update
+
+A flow deploy does not reload Node.js runtime code. Use BUILD-INFO in addition to the npm version when checking for duplicate installs.
+
+```bash
+cd ~/.node-red
+npm uninstall node-red-contrib-home-connect
+rm -rf node_modules/node-red-contrib-home-connect
+npm install --force /absolute/path/node-red-contrib-home-connect-0.2.0.tgz
+node -p "require('./node_modules/node-red-contrib-home-connect/BUILD-INFO.json')"
+```
+
+Then restart Node-RED or the container completely, hard-reload the browser, and begin OAuth again. Authorization codes and state links are short-lived and single-use.
+
+## 9. `No refresh token is stored. Complete OAuth authorization first.`
+
+The refresh token is saved only after a successful callback.
+
+- Start authorization from the deployed connection.
+- Complete sign-in and consent.
+- Wait for **Home Connect authorized**.
+- Only then use Test, Discover, Read, or Events.
+
+If it still fails, record the callback's error code but never publish codes or tokens.
+
+## 10. `insufficient_scope`
+
+The token may not access the requested resource.
+
+1. Keep `IdentifyAppliance`.
+2. Add the relevant appliance-specific scope, such as `Dishwasher-Monitor`, `Washer-Monitor`, or `Oven-Monitor`.
+3. Add only the required `*-Control` and/or `*-Settings` for actions.
+4. Click Done → Deploy.
+5. Authorize again; an existing refresh token does not gain new permissions automatically.
+
+The generic `Monitor` scope can be insufficient for some Applications/accounts.
+
+## 11. Events stays on `reconnecting`
+
+`reconnecting` is a consequence, not the root cause. Connect the Events node's second output to Debug.
+
+Common causes:
+
+- no refresh token;
+- missing monitor scope;
+- expired or revoked authorization;
+- network/proxy interruption of the SSE stream;
+- too many parallel event streams.
+
+Repair Test/appliance discovery first, then prefer one Events node with appliance ID `*`.
+
+## 12. Successful end state
+
+Setup is complete when:
+
+1. the browser page displays **Home Connect authorized**;
+2. Test reports an appliance count without an error;
+3. **Load appliances** populates the selector;
+4. the Events node emits events instead of reconnecting indefinitely.
+
+## 13. Safe bug reports
+
+Safe to include:
+
+- package version and build ID;
+- Node.js and Node-RED versions;
+- environment type (Production/Simulator), without a private hostname;
+- error code and sanitized message;
+- simulator-based reproduction steps.
+
+Never include:
+
+- Client ID or Client Secret;
+- access or refresh tokens;
+- authorization code or OAuth state;
+- real Redirect URI, hostname, or IP address;
+- real `haId`, serial number, or appliance number;
+- complete events or debug output containing personal data.
+
+
+## 14. Understanding health and warning codes
+
+Every functional output uses schema `home-connect-health/v1`:
+
+- `ok`: no current concern
+- `running`: a program is running
+- `info`: useful, non-urgent notice
+- `warning`: restriction or paused/aborting state
+- `action_required`: local intervention or renewed authorization required
+- `offline`: appliance, event stream, or network unavailable
+- `error`: appliance/API error
+
+`warnings` is deduplicated. Every entry contains at least `source`, `code`, `severity`, `text.de`, `text.en`, and `transient`. Short-lived notices also include timing fields and disappear after expiry. Status conditions remain only while the current status confirms them.
+
+Important codes:
+
+| Code | Meaning | Action |
+|---|---|---|
+| `HC_OPERATION_ACTION_REQUIRED` | appliance requests local intervention | inspect appliance display, door, and supplies |
+| `HC_STREAM_DISCONNECTED` | SSE connection disconnected | wait for reconnect; inspect output 2 if persistent |
+| `HC_OAUTH_INSUFFICIENT_SCOPE` | token has insufficient rights | correct scope, deploy, authorize again |
+| `HC_OAUTH_AUTHORIZATION_EXPIRED` | authorization missing/expired/revoked | authorize again |
+| `HC_API_RATE_LIMITED` | HTTP 429/API limit | reduce polling and observe `retryAfter` |
+| `HC_NETWORK_ERROR` | network/timeout | check DNS, proxy, TLS, and reachability |
+
+The Events node also emits synthetic `CONNECTED`/`DISCONNECTED` lifecycle events for the actual SSE stream. They contain no credentials.
+
+## 15. HTTP 429 / `1000 calls in 1 day`
+
+By default, the local limiter prevents this package from sending more than 900 API attempts in a rolling 24-hour window. The connection editor displays current usage and any active block. When the budget is exhausted, output 2 receives `LOCAL_RATE_LIMITED`; `retryAfter` and `resetAt` state the remaining wait.
+
+If Home Connect has already returned HTTP 429 with text such as `remaining period of 75502 seconds`, the package adopts that block period and sends no further API calls until it expires. The state survives deploys and restarts. Do not repeatedly click **Test** or Inject nodes. Reduce polling substantially, prefer one all-appliance event stream, and do not request snapshots every 15 seconds. Check other computers or programs using the same Developer Portal Application because their calls are outside the local counter.
+
+## 16. Firmware version or update is missing
+
+This is not a configuration error. The publicly documented Home Connect API does not provide firmware version, firmware history, or firmware update. The package does not use undocumented endpoints and intentionally provides no firmware button. It displays only documented appliance information such as name, brand, type, `vib`/E-number, and connection state when supplied. Check firmware only through official manufacturer/Home Connect channels.
+
+## 17. Local LAN profiles and connection failures
+
+For local configurations, OAuth, authorization, refresh-token, and cloud daily-budget sections are intentionally hidden. Setup succeeds when **Test connection** in every device card reports a local read-only connection and Discover/Read/Events return `local: true` and `readOnly: true`.
+
+Check in this order:
+
+1. Confirm the profile folder is mounted at the entered path inside the Node-RED host/container and readable by its service account. Then explicitly click **Scan profiles / Detect devices**.
+2. Keep appliance JSON, `DeviceDescription.xml`, and `FeatureMapping.xml` from the same Profile Downloader export together. `LOCAL_PROFILE_FILES_INCOMPLETE` names a missing file; `LOCAL_PROFILE_ORPHAN_COMPANION` indicates mismatched folders/names.
+3. A duplicate profile ID lists the affected files. Do not guess an assignment: remove the duplicate/old export and scan again.
+4. A successful scan says, for example, **3 device profiles found**, with one card per complete profile. If a card is absent, read the issues directly below the result.
+5. Enter Host/IP in every card. Missing, malformed, or public IPs are marked. Hostnames are resolved server-side during testing. Only private/link-local targets are accepted; loopback/public targets return `LOCAL_HOST_NOT_PRIVATE`. An individual card test uses that card's current fields immediately; it does not require Done/Deploy and is not blocked by empty sibling cards.
+6. Leave **Connection type: Auto (recommended)**. An explicit AES/TLS/PSK profile declaration wins; IV presence is only the fallback. `LOCAL_PROFILE_IV_MISSING` with an AES override means the original IV is absent.
+7. Click **Test connection** and read its seven stages. `LOCAL_NETWORK_ERROR`/timeout stops at **IP reachable**. `EHOSTUNREACH` means no network path and is not a protocol failure: check power/standby, IP, Wi-Fi, VLAN routing, and firewall. `LOCAL_TLS_PSK_UNAVAILABLE`/`LOCAL_TRANSPORT_UNSUPPORTED` stops at **Transport detected**. `LOCAL_WEBSOCKET_UPGRADE_FAILED` means TCP or TLS succeeded but the appliance rejected the upgrade on `/homeconnect`. The test reads local resources only.
+8. After all cards are valid, click **Done → Deploy**. `localDeviceMappings` is saved again on Done and restored after deploy. Never copy Host/IP into Read/Events; select the descriptive label while the full ID remains internal.
+9. `LOCAL_CRYPTO_AUTH_FAILED`, `LOCAL_PROFILE_KEY_REJECTED`, or `LOCAL_PROFILE_AUTHENTICATION_FAILED` points to the wrong/incomplete profile; re-download it and never edit/guess PSK/IV. `LOCAL_PROTOCOL_REJECTED` is separate and identifies resource, action, negotiated version, and device code. An unsupported `/ro/*` path is tolerated once another read or appliance `NOTIFY` delivered data. If all five paths are rejected, `rejectedResources` contains the complete sequence. `/ci/services` must be version 1 without an empty `data` array.
+10. If only numeric UIDs appear, restore the XML files from the same download and scan again.
+11. Manual profile JSON is only the optional **Advanced** fallback. It is disabled/ignored while a folder is set. Generate it from detected profiles and assignments instead of writing it manually.
+12. For real firmware differences, briefly enable the safe protocol trace under **Advanced**. With no path, the bounded sanitized memory trace is shown only after the test; an absolute path writes JSONL mode `0600` on POSIX. On Windows, restrict the trace path to the Node-RED service account with an NTFS ACL because POSIX mode bits are not reliable there. PSK, IV, keys, nonces, and appliance/network identifiers are removed. Inspect before sharing, then disable tracing and delete the file.
+13. `LOCAL_HEARTBEAT_TIMEOUT` or `LOCAL_DISCONNECTED` after an initially successful connection points to power/standby, Wi-Fi roaming, VLAN/firewall, or packet loss. The runtime rebuilds transport, crypto state, `sID`, `msgID`, services, and read session with backoff.
+
+`LOCAL_READ_ONLY` is not a connectivity failure. It proves the local write barrier worked. Use a separate cloud configuration for guarded writes. See [Local LAN connection](LOCAL-LAN.md).

package/docs/images/README.md

@@ -0,0 +1,10 @@
+# Documentation screenshots
+
+The final 0.2.0 release includes two user-provided, visually reviewed English PNG captures from the isolated simulated Demo:
+
+- `dashboard-overview-en.png` — English **Demo Overview** with three simulated summary cards; 2048 × 511; SHA-256 `fda4af394e65bb2cc48eafec152ae04eabe422d4c18a19a5a2152c7e13dce222`
+- `dashboard-details-en.png` — English details view with three simulated appliance cards; 2048 × 1063; SHA-256 `35f260f5ef49a8e8afb60c0ef19fb57961e966dbf44ce3f7039879e681a2dff9`
+
+Visual and OCR-assisted privacy review confirmed that both captures show only English Demo content. Every card is marked `SIMULATED`; visible identifiers are synthetic `Demo`/`DEMO-*` values. The frames contain no browser profile or chrome, account name, email address, hostname, IP address, OAuth material, credential, token, QR code, local profile data, real appliance identifier, unrelated tab/window, or private notification.
+
+Do not substitute screenshots from a real installation. `npm run release:check` verifies the exact reviewed SHA-256 hashes as well as PNG structure, minimum dimensions, and sensitive-looking metadata.