README: alle 5 Intents dokumentiert (Temperatur, Stromverbrauch, Stromkosten, Waschmaschine, Trockner)
This commit is contained in:
+141
-41
@@ -1,11 +1,23 @@
|
||||
# Home Assistant Alexa Skill
|
||||
|
||||
Ein privater, selbst gehosteter Alexa Custom Skill, mit dem du Home Assistant per Sprache abfragen kannst — z.B. Raumtemperaturen. Läuft als **Alexa-hosted Skill** (Node.js), keine eigene AWS-Infrastruktur nötig.
|
||||
Ein privater, selbst gehosteter Alexa Custom Skill, mit dem du Home Assistant per Sprache abfragen kannst — Raumtemperaturen, Stromverbrauch, Stromkosten, sowie Waschmaschine und Trockner. Läuft als **Alexa-hosted Skill** (Node.js), keine eigene AWS-Infrastruktur nötig.
|
||||
|
||||
**Beispiel:**
|
||||
**Beispiele:**
|
||||
> "Alexa, frag Home Assistant wie warm es im Wohnzimmer ist"
|
||||
> → "Die Temperatur im Wohnzimmer beträgt 24.4 Grad."
|
||||
|
||||
> "Alexa, frag Home Assistant was ist die aktuelle Leistung"
|
||||
> → "Der aktuelle Stromverbrauch beträgt 645 Watt."
|
||||
|
||||
> "Alexa, frag Home Assistant wie hoch sind die Stromkosten diesen Monat"
|
||||
> → "Die Stromkosten für diesen Monat betragen 45,23 Euro."
|
||||
|
||||
> "Alexa, frag Home Assistant wie lange läuft die Waschmaschine noch"
|
||||
> → "Die Waschmaschine ist 96 Prozent fertig und endet um 21:30 Uhr."
|
||||
|
||||
> "Alexa, frag Home Assistant wie lange läuft der Trockner noch"
|
||||
> → "Der Trockner ist 40 Prozent fertig und endet um 22:15 Uhr."
|
||||
|
||||
---
|
||||
|
||||
## Inhalt dieses Repos
|
||||
@@ -22,13 +34,9 @@ home-assistant-skill/
|
||||
|
||||
## Warum ein Custom Skill (statt nur die native Nabu-Casa-Integration)?
|
||||
|
||||
Home Assistant über Nabu Casa bietet bereits einen offiziellen **Smart Home Skill**, der native Sprachbefehle wie "Alexa, wie warm ist es im Wohnzimmer" *ohne* Skill-Namen unterstützt. Das funktioniert aber nur, wenn:
|
||||
- die Entität für Alexa freigegeben ist (Home Assistant → Einstellungen → Sprachassistenten → Alexa)
|
||||
- die Capability korrekt erkannt wird (`Alexa.TemperatureSensor`)
|
||||
- das Gerät in der Alexa-App einem Raum zugeordnet ist
|
||||
- Discovery erneut ausgeführt wurde
|
||||
Home Assistant über Nabu Casa bietet bereits einen offiziellen **Smart Home Skill**, der native Sprachbefehle wie "Alexa, wie warm ist es im Wohnzimmer" *ohne* Skill-Namen unterstützt — das funktioniert zuverlässig, sobald die Entität freigegeben und einem Raum in der Alexa-App zugeordnet ist. Für **Temperatur** ist das die einfachste Lösung.
|
||||
|
||||
Falls das bei dir (z.B. bei komplexeren Geräten wie Homematic-Heizungsthermostaten) nicht zuverlässig funktioniert, ist ein **eigener Custom Skill** die zuverlässige Alternative — mit dem Nachteil, dass du immer den Invocation Name sagen musst (z.B. "frag Home Assistant ..."). Das ist eine feste Grammatikregel von Alexa für alle Custom Skills und lässt sich nicht umgehen — auch nicht mit Environment Variables oder Code-Tricks.
|
||||
Für alles darüber hinaus (Stromverbrauch, Stromkosten, Gerätestatus wie Waschmaschine/Trockner) hat Alexa aber **keine eingebaute Sprachgrammatik** — die native Integration unterstützt praktisch nur Temperatursensoren. Dafür ist dieser Custom Skill gedacht. Nachteil: Du musst immer den Invocation Name sagen (z.B. "frag Home Assistant ..."), das ist eine feste Grammatikregel von Alexa für alle Custom Skills und lässt sich nicht umgehen.
|
||||
|
||||
---
|
||||
|
||||
@@ -60,10 +68,12 @@ Falls das bei dir (z.B. bei komplexeren Geräten wie Homematic-Heizungsthermosta
|
||||
- Damit sprichst du den Skill später an: *"Alexa, frag home assistant ..."*
|
||||
- Save klicken
|
||||
|
||||
### 3. Slot Type für Räume anlegen
|
||||
### 3. Slot Types anlegen
|
||||
|
||||
**RoomList** (für Temperatur-Abfragen):
|
||||
|
||||
- Build-Tab → **Slot Types** → **+ Add** → Namen `RoomList` → "Create custom slot type"
|
||||
- Für jeden Raum einen **Value** eintragen, plus eine saubere **ID** (klein, ohne Umlaute/Leerzeichen), z.B.:
|
||||
- Für jeden Raum einen **Value** eintragen, plus eine saubere **ID** (klein, ohne Umlaute/Leerzeichen):
|
||||
|
||||
| Value | ID |
|
||||
|---|---|
|
||||
@@ -78,32 +88,75 @@ Falls das bei dir (z.B. bei komplexeren Geräten wie Homematic-Heizungsthermosta
|
||||
| Wohnzimmer | wohnzimmer |
|
||||
| Küche | kueche |
|
||||
|
||||
Die ID ist wichtig: Der Code liest den sauberen, festen Wert über die Slot-Resolution aus — nicht den roh gesprochenen Text (der z.B. durch angehängte Wörter wie "ist" verfälscht sein kann).
|
||||
**PeriodList** (für Stromkosten-Abfragen):
|
||||
|
||||
- Genauso vorgehen, Namen `PeriodList`:
|
||||
|
||||
| Value | ID |
|
||||
|---|---|
|
||||
| Tag | tag |
|
||||
| Woche | woche |
|
||||
| Monat | monat |
|
||||
|
||||
Die ID ist jeweils wichtig: Der Code liest den sauberen, festen Wert über die Slot-Resolution aus — nicht den roh gesprochenen Text (der z.B. durch angehängte Wörter wie "ist" verfälscht sein kann).
|
||||
|
||||
- Save klicken
|
||||
|
||||
### 4. Intent anlegen: GetTemperatureIntent
|
||||
### 4. Intents anlegen
|
||||
|
||||
- Build-Tab → **Intents** → den vom Template vorgegebenen `HelloWorldIntent` löschen
|
||||
- **+ Add Intent** → Name `GetTemperatureIntent` → "Create custom intent"
|
||||
- Sample Utterances hinzufügen, z.B.:
|
||||
```
|
||||
wie warm ist es im {Room}
|
||||
wie warm ist es in der {Room}
|
||||
wie ist die temperatur im {Room}
|
||||
wie ist die temperatur in der {Room}
|
||||
temperatur im {Room}
|
||||
```
|
||||
- Beim ersten Eintippen von `{Room}` erscheint ein Popup: "Create a new slot" → **Add** klicken
|
||||
- Danach im Bereich **Intent Slots** beim Slot `Room` als **Slot Type** `RoomList` auswählen
|
||||
- Save klicken
|
||||
Build-Tab → **Intents** → den vom Template vorgegebenen `HelloWorldIntent` löschen. Danach folgende fünf Intents anlegen (**+ Add Intent** → Namen eingeben → "Create custom intent" → Sample Utterances eintragen → Save):
|
||||
|
||||
**GetTemperatureIntent** (mit Slot `{Room}`, Slot Type `RoomList`):
|
||||
```
|
||||
wie warm ist es im {Room}
|
||||
wie warm ist es in der {Room}
|
||||
wie ist die temperatur im {Room}
|
||||
wie ist die temperatur in der {Room}
|
||||
temperatur im {Room}
|
||||
```
|
||||
Beim ersten Eintippen von `{Room}` erscheint ein Popup "Create a new slot" → **Add** klicken. Danach im Bereich **Intent Slots** beim Slot `Room` als **Slot Type** `RoomList` auswählen.
|
||||
|
||||
**GetPowerUsageIntent** (kein Slot):
|
||||
```
|
||||
wie hoch ist der aktuelle stromverbrauch
|
||||
was ist die aktuelle leistung
|
||||
wie viel strom verbrauchen wir gerade
|
||||
wie hoch ist die aktuelle leistung
|
||||
```
|
||||
|
||||
**GetEnergyCostIntent** (mit Slot `{Period}`, Slot Type `PeriodList`):
|
||||
```
|
||||
wie hoch sind die stromkosten diesen {Period}
|
||||
was kostet der strom diesen {Period}
|
||||
wie viel strom kosten haben wir diesen {Period}
|
||||
stromkosten {Period}
|
||||
```
|
||||
Genauso wie bei `{Room}`: Slot `Period` anlegen lassen, danach als Slot Type `PeriodList` zuweisen.
|
||||
|
||||
**GetWashingMachineIntent** (kein Slot):
|
||||
```
|
||||
wie lange läuft die waschmaschine noch
|
||||
wann ist die waschmaschine fertig
|
||||
ist die waschmaschine fertig
|
||||
wie weit ist die waschmaschine
|
||||
wie ist der fortschritt der waschmaschine
|
||||
```
|
||||
|
||||
**GetDryerIntent** (kein Slot):
|
||||
```
|
||||
wie lange läuft der trockner noch
|
||||
wann ist der trockner fertig
|
||||
ist der trockner fertig
|
||||
wie weit ist der trockner
|
||||
wie ist der fortschritt des trockners
|
||||
```
|
||||
|
||||
> Die Standard-Intents `AMAZON.CancelIntent`, `AMAZON.HelpIntent`, `AMAZON.StopIntent`, `AMAZON.NavigateHomeIntent` und `AMAZON.FallbackIntent` bleiben unverändert — die sind Pflicht und werden im Code bereits gehandhabt.
|
||||
|
||||
### 5. Modell bauen
|
||||
|
||||
- Oben rechts **Build Skill** klicken (dauert ca. 1 Minute)
|
||||
- **Wichtig:** Nach *jeder* Änderung an Utterances/Intents/Slots muss neu gebaut werden — sonst bleiben Änderungen im Simulator/auf dem Gerät unwirksam.
|
||||
- **Wichtig:** Nach *jeder* Änderung an Utterances/Intents/Slots muss neu gebaut werden — sonst bleiben Änderungen im Simulator/auf dem Gerät unwirksam. Das ist der häufigste Grund, warum ein neuer Intent zunächst nur die Fallback-Antwort auslöst.
|
||||
|
||||
### 6. Long-Lived Access Token in Home Assistant erstellen
|
||||
|
||||
@@ -123,41 +176,88 @@ Die ID ist wichtig: Der Code liest den sauberen, festen Wert über die Slot-Reso
|
||||
|
||||
> **Hinweis:** Alexa-hosted Skills bieten *keine* Environment-Variables-Oberfläche in der Konsole (im Gegensatz zu selbst verwalteten AWS-Lambda-Funktionen). Die `.env`-Datei ist daher die praktikabelste Lösung, um Secrets wenigstens von der Programmlogik getrennt zu halten. Sicherheitsrelevant bleibt sie trotzdem — nicht öffentlich teilen oder in ein öffentliches Repo pushen (dieses Gitea-Repo ist privat, das reicht für den Zweck).
|
||||
|
||||
- Im Raum-Mapping in `index.js` die Entity-IDs an deine echten Home-Assistant-Entitäten anpassen:
|
||||
```js
|
||||
const roomToClimateEntity = {
|
||||
badezimmer: 'climate.badezimmer_heizungssteuerung',
|
||||
kinderzimmer: 'climate.kinderzimmer_heizungssteuerung',
|
||||
kueche: 'climate.kueche_heizungssteuerung',
|
||||
schlafzimmer: 'climate.schlafzimmer_heizungssteuerung',
|
||||
wohnzimmer: 'climate.wohnzimmer_heizungssteuerung',
|
||||
};
|
||||
```
|
||||
Entity-IDs findest du in Home Assistant unter **Entwicklerwerkzeuge → Zustände** (Filter z.B. nach `climate.*`).
|
||||
- Die Entity-IDs in `index.js` an deine echte Home-Assistant-Installation anpassen (siehe [Entity-Referenz](#entity-referenz) unten). Entity-IDs findest du in Home Assistant unter **Entwicklerwerkzeuge → Zustände**.
|
||||
|
||||
- **Save** → **Deploy** klicken
|
||||
|
||||
### 8. Testen
|
||||
|
||||
- Tab **Test** → Skill-Testing auf **Development** stellen
|
||||
- Im Simulator eintippen oder sprechen:
|
||||
- Im Simulator eintippen oder sprechen, z.B.:
|
||||
```
|
||||
frag home assistant wie warm es im wohnzimmer ist
|
||||
frag home assistant was ist die aktuelle leistung
|
||||
frag home assistant wie hoch sind die stromkosten diesen monat
|
||||
frag home assistant wie lange läuft die waschmaschine noch
|
||||
frag home assistant wie lange läuft der trockner noch
|
||||
```
|
||||
- Bei Erfolg antwortet der Simulator mit der aktuellen Temperatur
|
||||
- Bei Erfolg antwortet der Simulator mit dem entsprechenden Wert
|
||||
- Sobald es im Simulator funktioniert, ist der Skill automatisch auch auf allen Echo-Geräten verfügbar, die mit demselben Amazon-Konto verknüpft sind — keine separate Veröffentlichung nötig
|
||||
|
||||
---
|
||||
|
||||
## Entity-Referenz
|
||||
|
||||
Diese Home-Assistant-Entity-IDs sind aktuell in `index.js` hinterlegt und müssen ggf. an deine Installation angepasst werden:
|
||||
|
||||
**Temperatur** (`roomToClimateEntity`):
|
||||
```js
|
||||
badezimmer: 'climate.badezimmer_heizungssteuerung',
|
||||
kinderzimmer: 'climate.kinderzimmer_heizungssteuerung',
|
||||
kueche: 'climate.kueche_heizungssteuerung',
|
||||
schlafzimmer: 'climate.schlafzimmer_heizungssteuerung',
|
||||
wohnzimmer: 'climate.wohnzimmer_heizungssteuerung',
|
||||
```
|
||||
|
||||
**Stromverbrauch** (aktuelle Leistung in Watt):
|
||||
```js
|
||||
POWER_ENTITY = 'sensor.kammer_netzbezug_plus_keller_power_calc'
|
||||
```
|
||||
|
||||
**Stromkosten** (je Zeitraum):
|
||||
```js
|
||||
tag: 'sensor.netzbezug_kosten_tag',
|
||||
woche: 'sensor.netzbezug_kosten_woche',
|
||||
monat: 'sensor.netzbezug_kosten_monat',
|
||||
```
|
||||
|
||||
**Waschmaschine:**
|
||||
```js
|
||||
WASHING_MACHINE_STATUS_ENTITY = 'sensor.waschmaschine_betriebszustand' // optional, wird toleriert falls nicht vorhanden
|
||||
WASHING_MACHINE_PROGRESS_ENTITY = 'sensor.waschmaschine_programm_fortschritt' // Prozent, z.B. "96"
|
||||
WASHING_MACHINE_END_TIME_ENTITY = 'sensor.waschmaschine_programm_endzeit' // ISO-Zeitstempel, z.B. "2026-08-22T19:30:00+00:00"
|
||||
```
|
||||
|
||||
**Trockner** (identisches Schema):
|
||||
```js
|
||||
DRYER_STATUS_ENTITY = 'sensor.trockner_betriebszustand'
|
||||
DRYER_PROGRESS_ENTITY = 'sensor.trockner_programm_fortschritt'
|
||||
DRYER_END_TIME_ENTITY = 'sensor.trockner_programm_endzeit'
|
||||
```
|
||||
|
||||
**Wie die Waschmaschine/Trockner-Logik funktioniert:**
|
||||
1. Falls der optionale `*_betriebszustand`-Sensor existiert und einen Wert wie `fertig`, `inaktiv`, `finished` oder `inactive` liefert → Antwort: "läuft aktuell nicht"
|
||||
2. Falls Fortschritt oder Endzeit `unknown`/`unavailable`/`none` sind → ebenfalls "läuft aktuell nicht"
|
||||
3. Ist die Endzeit bereits verstrichen → "ist fertig"
|
||||
4. Sonst → Prozent gerundet + Endzeit als `HH:MM Uhr` in der Zeitzone `Europe/Berlin`, z.B. "ist 96 Prozent fertig und endet um 21:30 Uhr"
|
||||
|
||||
---
|
||||
|
||||
## Fehlersuche
|
||||
|
||||
- **Fehlermeldung im Simulator:** JSON Output rechts prüfen — zeigt meist den genauen Fehler (z.B. HTTP-Statuscode von Home Assistant)
|
||||
- **"Das habe ich nicht verstanden" (Fallback) direkt nach dem Anlegen eines neuen Intents:** Meistens wurde nach dem Speichern der Utterances nicht auf **"Build Skill"** geklickt — das Modell im Simulator läuft dann noch gegen den alten Stand.
|
||||
- **"Ich konnte keine Verbindung herstellen":** Prüfen, ob `HA_URL` korrekt ist (kein Pfad, kein abschließender Slash) und ob Home Assistant tatsächlich von außen per HTTPS erreichbar ist
|
||||
- **"Ich kenne den Raum ... nicht":** Slot-Erkennung hat nicht gegriffen — meist hilft eine zusätzliche Sample Utterance mit der genauen Formulierung, die genutzt wurde, plus erneutes "Build Skill"
|
||||
- **Zahlen werden falsch vorgelesen (z.B. Dezimalzahlen als Ziffernfolge statt als Zahl):** Alexas deutsche TTS-Engine liest Dezimalpunkte manchmal falsch vor. Lösung im Code: Werte runden (`Math.round`) bzw. mit Komma statt Punkt formatieren (`.toFixed(2).replace('.', ',')`) — ist für Stromverbrauch und -kosten bereits so umgesetzt.
|
||||
- **Ausführlichere Logs:** Code-Tab → **CloudWatch Logs** (führt zu den AWS-Logs der Lambda-Funktion)
|
||||
|
||||
---
|
||||
|
||||
## Offene Erweiterung (zurückgestellt)
|
||||
## Status
|
||||
|
||||
- `GetPowerUsageIntent` für Stromverbrauchs-Abfragen — bisher nicht implementiert, kann nach demselben Muster wie `GetTemperatureIntent` ergänzt werden (neuer Intent + neuer Handler in `index.js`, passende `sensor.*`-Entity in Home Assistant).
|
||||
✅ `GetTemperatureIntent` — Raumtemperaturen
|
||||
✅ `GetPowerUsageIntent` — aktueller Stromverbrauch
|
||||
✅ `GetEnergyCostIntent` — Stromkosten nach Tag/Woche/Monat
|
||||
✅ `GetWashingMachineIntent` — Waschmaschinen-Fortschritt und Endzeit
|
||||
✅ `GetDryerIntent` — Trockner-Fortschritt und Endzeit
|
||||
|
||||
Reference in New Issue
Block a user