SETUP.md: vollständige Schritt-für-Schritt-Anleitung, ohne Temperatur/RoomList-Reste

home-assistant-skill/SETUP.md

@@ -0,0 +1,166 @@
+# Setup-Anleitung: Home Assistant Alexa Skill
+
+## Schritt-für-Schritt-Anleitung
+
+### 1. Skill in der Alexa Developer Console anlegen
+
+1. Auf [developer.amazon.com](https://developer.amazon.com) einloggen → **Alexa** → **Alexa Skills Kit**
+2. **Create Skill**
+3. Namen vergeben (z.B. "HomeAssistantSkill")
+4. Locale: **German (DE)**
+5. Modell: **Custom**
+6. Hosting-Methode: **Alexa-hosted (Node.js)**
+7. Hosting-Region: **EU (Ireland)**
+8. Template: **Start from Scratch**
+9. **Create Skill** klicken
+
+### 2. Invocation Name festlegen
+
+- Build-Tab → **Invocations** → Invocation Name setzen, z.B. `home assistant`
+- Save klicken
+
+### 3. Slot Type anlegen
+
+**PeriodList** (für Stromkosten-Abfragen, wird von mehreren Intents wiederverwendet):
+
+- Build-Tab → **Slot Types** → **+ Add** → Namen `PeriodList` → "Create custom slot type"
+
+| Value | ID |
+|---|---|
+| Tag | tag |
+| Woche | woche |
+| Monat | monat |
+
+Tipp: Beim Value "Tag" als Synonym z.B. "heute" ergänzen.
+
+Die ID ist wichtig: Der Code liest den sauberen, festen Wert über die Slot-Resolution aus.
+
+- Save klicken
+
+### 4. Intents anlegen
+
+Build-Tab → **Intents** → `HelloWorldIntent` löschen. Danach folgende Intents anlegen:
+
+**GetPowerUsageIntent** (kein Slot):
+```
+wie hoch ist der aktuelle stromverbrauch
+was ist die aktuelle leistung
+wie viel strom verbrauchen wir gerade
+```
+
+**GetPowerKammerUsageIntent** (kein Slot):
+```
+wie hoch ist der aktuelle stromverbrauch in der kammer
+was ist die aktuelle leistung in der kammer
+```
+
+**GetEnergyCostIntent** (mit Slot `{Period}`, Slot Type `PeriodList`):
+```
+wie hoch sind die stromkosten diesen {Period}
+wie hoch sind die stromkosten {Period}
+was kostet der strom diesen {Period}
+```
+Beim Eintippen von `{Period}` Popup "Create a new slot" → **Add**. Danach bei Intent Slots `Period` als Slot Type `PeriodList`.
+
+**GetEnergyCostKammerIntent** (mit Slot `{Period}`, Slot Type `PeriodList`):
+```
+wie hoch sind die stromkosten für die kammer diesen {Period}
+was kostet die kammer diesen {Period}
+```
+
+**GetWashingMachineIntent** (kein Slot):
+```
+wie lange läuft die waschmaschine noch
+wann ist die waschmaschine fertig
+ist die waschmaschine fertig
+```
+
+**GetDryerIntent** (kein Slot):
+```
+wie lange läuft der trockner noch
+wann ist der trockner fertig
+ist der trockner fertig
+```
+
+> Die Standard-Intents (Cancel/Help/Stop/NavigateHome/Fallback) bleiben unverändert.
+
+### 5. Modell bauen
+
+- Oben rechts **Build Skill** klicken
+- Nach *jeder* Änderung an Utterances/Intents/Slots muss neu gebaut werden.
+
+### 6. Long-Lived Access Token erstellen
+
+- Home Assistant: Profil → runterscrollen zu **"Long-lived access tokens"** → Token erstellen → sofort kopieren
+
+### 7. Code einrichten
+
+- Skill → Tab **Code**
+- `index.js`, `factories.js`, `ha-client.js`, `static-handlers.js` aus diesem Repo übernehmen (per **New File** anlegen)
+- `package.json` ersetzen
+- Neue Datei `.env` anlegen, Inhalt aus `.env.example` mit echten Werten:
+  ```
+  HA_URL=https://deine-ha-domain.de
+  HA_TOKEN=dein-long-lived-access-token
+  ```
+- Entity-IDs in `index.js` an deine Installation anpassen
+- **Save** → **Deploy**
+
+### 8. Temperaturabfragen (native Integration)
+
+1. Home Assistant → Einstellungen → Sprachassistenten → Alexa → `climate`-Entitäten freigeben
+2. Alexa-App: Gerät dem passenden Raum zuweisen
+3. Falls nötig: Geräte neu suchen lassen
+4. Danach: *"Alexa, wie warm ist es im Wohnzimmer"* — ohne Skill-Namen
+
+### 9. Testen
+
+- Tab **Test** → Development
+- Simulator, z.B.: `frag home assistant was ist die aktuelle leistung`
+
+---
+
+## Entity-Referenz
+
+**Stromverbrauch:**
+```js
+GetPowerUsageIntentHandler: 'sensor.kammer_netzbezug_plus_keller_power_calc'
+GetPowerKammerUsageIntentHandler: 'sensor.kammer_serverschrank_leistung'
+```
+
+**Stromkosten:**
+```js
+// GetEnergyCostIntentHandler
+tag: 'sensor.netzbezug_kosten_tag',
+woche: 'sensor.netzbezug_kosten_woche',
+monat: 'sensor.netzbezug_kosten_monat',
+
+// GetEnergyCostKammerIntentHandler
+tag: 'sensor.kammer_serverschrank_kosten_tag',
+woche: 'sensor.kammer_serverschrank_kosten_woche',
+monat: 'sensor.kammer_serverschrank_kosten_monat',
+```
+
+**Waschmaschine:**
+```js
+statusEntity: 'sensor.waschmaschine_betriebszustand'
+progressEntity: 'sensor.waschmaschine_programm_fortschritt'
+endTimeEntity: 'sensor.waschmaschine_programm_endzeit'
+```
+
+**Trockner:**
+```js
+statusEntity: 'sensor.trockner_betriebszustand'
+progressEntity: 'sensor.trockner_programm_fortschritt'
+endTimeEntity: 'sensor.trockner_programm_endzeit'
+```
+
+---
+
+## Fehlersuche
+
+- **Fehlermeldung im Simulator:** JSON Output rechts prüfen
+- **Fallback direkt nach neuem Intent:** "Build Skill" vergessen
+- **Keine Verbindung:** `HA_URL` prüfen (kein Pfad, kein Slash am Ende), HA von außen erreichbar?
+- **Zahlen falsch vorgelesen:** Werte runden bzw. mit Komma formatieren (bereits umgesetzt)
+- **Ausführliche Logs:** Code-Tab → CloudWatch Logs