Zum Hauptinhalt springen
War diese Seite hilfreich?

Smart-Home-Automatisierung

PrimeCal-Automatisierungen können auf zwei Arten über den Kalender hinaus in Ihr Smart Home hineinreichen: durch direkten Aufruf der REST-API eines Geräts und durch bedarfsgesteuertes Instanziieren einer Routine-Vorlage über einen beliebigen Auslöser. Beides baut auf vorhandenen Automatisierungsbausteinen auf – es gibt kein separates „Smart Home“-Modul zu konfigurieren.

Die REST-API eines Smart-Home-Geräts aufrufen​

Die Aktion Call Webhook sendet eine HTTP-Anfrage von den Servern von PrimeCal aus. Das Ziel muss aus dem Internet über HTTPS erreichbar sein. Systeme, die nur in Ihrem Heimnetzwerk lauschen, können nicht direkt aufgerufen werden. Sie unterstützt eine konfigurierbare HTTP-Methode und vollwertige Authentifizierung – genau das, was die meisten Smart-Home-REST-APIs (Home Assistant, Shelly und Ähnliches) erwarten, sobald sie auf diese Weise erreichbar gemacht wurden.

Die Anfrage konfigurieren​

Im Aktions-Builder bietet die Aktion Call Webhook:

  • Method – GET, POST, PUT, PATCH oder DELETE (Standard POST, wenn nicht gesetzt, zur Kompatibilität mit Regeln, die gespeichert wurden, bevor dieses Feld existierte).
  • Auth type – none, bearer, basic oder header:
    • bearer sendet Authorization: Bearer <token>.
    • basic sendet Authorization: Basic <base64(user:pass)> – geben Sie das Token bereits im Format user:pass an.
    • header sendet das Token unter einem von Ihnen angegebenen benutzerdefinierten Header-Namen (nützlich für APIs, die z. B. X-API-Key erwarten).
  • Ein paar gängige Voreinstellungen (Home Assistant REST-Befehl, Shelly-Relais umschalten, generischer Bearer-Token-Endpunkt) füllen sinnvolle Standardwerte für Methode und Authentifizierung vor, damit Sie sich diese nicht merken müssen.

Action-Builder-Stack im PrimeCal-Automatisierungsmodal

Beispiel: Waschmaschine zum geplanten Start einschalten​

Die Lates haben eine Aufgabe „Start laundry“ innerhalb einer Routine-Vorlage. Wenn diese Aufgabe ihre geplante Startzeit erreicht, soll PrimeCal ihre Home-Assistant-Instanz aufrufen und die smarte Steckdose der Waschmaschine einschalten.

Beispiel-actionConfig für die Webhook-Aktion:

{
  "url": "https://<your-instance>.ui.nabu.casa/api/webhook/<webhook-id>",
  "method": "POST",
  "authType": "bearer",
  "authToken": "YOUR_HOME_ASSISTANT_LONG_LIVED_TOKEN",
  "customPayload": { "entity_id": "switch.washing_machine" }
}

Der Auslöser für diese Regel ist task.scheduled_start – er feuert, wenn eine Aufgabe (in diesem Fall eine aus einem Routine-Eintrag instanziierte Aufgabe) ihre geplante Startzeit erreicht. Dieser Auslöser ist noch nicht in der Auslöserauswahl des Regel-Builders verfügbar, daher wird eine solche Regel derzeit direkt über die Automatisierung API (oder von einem MCP-verbundenen Agenten) erstellt und nicht über das UI-Dropdown.

PrimeCal lehnt Anfragen ab, die es nicht sicher zustellen kann

Eine Call-Webhook-Anfrage wird abgelehnt, bevor sie gesendet wird, wenn:

  • die URL nicht HTTPS ist,
  • der Host localhost ist, auf .local endet, oder sich zu einer privaten/internen IP-Adresse auflöst,
  • die URL einen Benutzernamen oder ein Passwort enthält, oder
  • der Server mit einer Weiterleitung antwortet.

Eine nur lokal erreichbare Home-Assistant-Instanz (homeassistant.local, oder jede Adresse, die nur Ihr Heimnetzwerk erreicht) scheitert an jeder dieser Bedingungen. Machen Sie sie zuerst von außen erreichbar – über Home Assistant Cloud (Nabu Casa) oder einen eigenen Reverse-Proxy mit gültigem Zertifikat – und rufen Sie stattdessen ihren /api/webhook/<id>-Pfad auf.

Tokens aus geteilten Regeln heraushalten

Auth-Tokens werden als Teil der Aktionskonfiguration gespeichert. Behandeln Sie eine geklonte oder geteilte Automatisierungsregel genauso wie ein geteiltes Zugangsdatum – rotieren Sie das Token, falls die Regel jemals exportiert oder an einen Ort kopiert wird, den Sie nicht kontrollieren.

Ein fertiges Home-Assistant-Blueprint für die andere Richtung

Im obigen Beispiel ruft PrimeCal Home Assistant auf. Für die umgekehrte Richtung – Home Assistant ruft PrimeCal auf, oder Home Assistant soll einfach auf etwas reagieren, das PrimeCal ihm sendet – laden Sie das PrimeCal-Webhook-Action-Blueprint herunter und importieren Sie es in Home Assistant (Settings → Automations & scenes → Blueprints → Import blueprint). Es legt auf der Home-Assistant-Seite einen Webhook-Endpunkt an und lässt Sie eine beliebige Aktion auswählen, die beim Aufruf durch PrimeCal ausgeführt wird, wobei die von PrimeCal gesendeten Daten als Template-Variable verfügbar sind. Siehe Automatisierungsrezepte für die passende actionConfig auf der PrimeCal-Seite.

Eine Routine über einen beliebigen Auslöser starten​

Die Aktion instantiate_routine lässt jeden Auslöser – einen Webhook, eine geplante Zeit, das Erstellen eines Ereignisses, den Statuswechsel einer Aufgabe oder das Erreichen der geplanten Startzeit einer Aufgabe – eine Routine-Vorlage sofort starten, genau so, als hätten Sie darauf Start now geklickt. Was eine Routine-Vorlage ist und welche anderen zwei Wege es zum Starten gibt, erfahren Sie unter Routinen und Vorlagen.

Beispiel: Ein smarter Wecker löst die Morgenroutine aus​

Der smarte Wecker der Lates kann beim Klingeln einen Webhook per POST senden. Statt jeden Morgen manuell PrimeCal zu öffnen und bei der „Morgenroutine“ auf Start now zu klicken, verbinden sie den Wecker mit einer Regel, die sie automatisch startet.

Beispiel-actionConfig für die Aktion instantiate_routine:

{
  "routineTemplateId": 42
}

Regelaufbau:

  1. Auslöser: webhook.incoming – die Integration des smarten Weckers sendet beim Klingeln einen POST an die Webhook-URL der Regel. Wie Sie diese URL finden und ansprechen, erfahren Sie unter Webhooks.
  2. Aktion: instantiate_routine mit routineTemplateId, gesetzt auf die geklonte „Morgenroutine“-Vorlage der Lates.

Die Aktion verwendet dieselbe Besitzprüfung wie die manuelle Schaltfläche Start now – eine Regel kann nur eine Routine-Vorlage instanziieren, die ihr Besitzer bereits sehen kann (eigene Vorlagen, über die Personengruppe geteilte Vorlagen oder aktive System-Vorlagen), niemals eine beliebige Vorlagen-ID, die jemand anderem gehört.

Wie task.scheduled_start ist auch der Aktionstyp instantiate_routine noch nicht im Dropdown der Aktionsauswahl verfügbar. Erstellen oder bearbeiten Sie eine Regel über die Automatisierung API, um ihn zu verwenden – zum Beispiel mit PUT /api/automation/rules/:id und einem actions-Array, das { "actionType": "instantiate_routine", "actionConfig": { "routineTemplateId": 42 } } enthält.

Siehe auch​