Shelly Scripting #6: EventHandler und StatusHandler für sofortige Reaktionen nutzen

Posted on by Stefan Draeger

Mit Shelly Scripting, EventHandler und StatusHandler lassen sich smarte Automatisierungen besonders effizient umsetzen. In diesem Beitrag zeige ich dir, wie du mit einem Shelly 2PM zwei Lampen so steuerst, dass sie wechselseitig mit einem Serienschalter ein- und ausgeschaltet werden.

Zwar könnte man diese Logik auch über eine Szene in der Shelly App realisieren, doch mit einem kleinen Shelly Script benötigen wir dafür nur wenige Zeilen Code. Der große Vorteil: Da wir direkt auf Statusänderungen mit dem EventHandler reagieren, erfolgt die Schaltung ohne Verzögerung und ganz ohne Timer – die Lampen wechseln sofort ihren Zustand, sobald der Schalter betätigt wird.

Shelly Scripting #6: EventHandler und StatusHandler für sofortige Reaktionen nutzen
Dieses Video auf YouTube ansehen.

Im letzten Beitrag Shelly 2PM Gen2: Smarte Steuerung und Verbrauchsmessung für wenig Geld habe ich den Shelly 2PM Gen2 bereits ausführlich vorgestellt. Falls du mehr über seine Funktionen, Einrichtung und Einsatzmöglichkeiten erfahren möchtest, schau gerne dort vorbei!

Inhaltsverzeichnis

Unterschied zwischen einem EventHandler und einem StatusHandler in Shelly Scripting

Beim Shelly Scripting gibt es zwei zentrale Mechanismen, um auf Änderungen zu reagieren:

  • EventHandler (Shelly.addEventHandler)
  • StatusHandler (Shelly.addStatusHandler)

Obwohl sie auf den ersten Blick ähnlich erscheinen, gibt es wesentliche Unterschiede in ihrer Funktionsweise und Anwendung.

EventHandler – Reaktion auf spezifische Ereignisse

Ein EventHandler (Shelly.addEventHandler) wird ausgelöst, wenn ein bestimmtes Ereignis am Shelly-Gerät auftritt.

Merkmale:

  • Wird nur bei einer Aktion oder einem Event ausgelöst (z. B. Taster gedrückt, MQTT-Nachricht empfangen).
  • Reagiert nur auf relevante Events und verarbeitet keine allgemeinen Statusänderungen.
  • Besonders nützlich für Schalter-/Taster-Steuerungen, MQTT-Kommunikation oder externe Trigger.

Beispiel:
Ein EventHandler erkennt, wenn ein Schalter getoggelt wird (event.info.event === "toggle") und schaltet dann ein anderes Relais aus.

Shelly.addEventHandler(function (event) {  
  print(event); // Gibt das komplette Event-Objekt aus (nützlich fürs Debugging)

  if (event.id === 0 && event.info.component === "switch:0" && event.info.event === "toggle") {
    print("Schalter links wurde betätigt!");
  }

  if (event.id === 1 && event.info.component === "switch:1" && event.info.event === "toggle") {
    print("Schalter rechts wurde betätigt!");
  }
});

Dieser Code erkennt, wenn ein Schalter (Switch 0 oder Switch 1) umgelegt wurde und gibt eine Debug-Nachricht aus.

StatusHandler – Reaktion auf Statusänderungen

Ein StatusHandler (Shelly.addStatusHandler) wird immer dann ausgelöst, wenn sich ein Statuswert eines Geräts ändert – unabhängig davon, was die Änderung verursacht hat.

Merkmale:

  • Wird bei jeder Statusänderung aufgerufen (z. B. Relais AN/AUS, Temperaturwerte, WLAN-Signalstärke).
  • Kann ausgelöst werden durch Benutzeraktionen, Skripte oder externe Steuerungen (z. B. MQTT oder REST-API).
  • Ideal für Überwachung, Logging oder automatisches Reagieren auf Zustandsänderungen.

Beispiel:
Ein StatusHandler erkennt, wenn ein Relais ein- oder ausgeschaltet wurde und gibt den neuen Zustand aus.

Shelly.addStatusHandler(function (status) {
  if (status.name === "switch" && status.id === 0 && status.delta.output) {
    print("Relais 0 wurde geschaltet! Neuer Zustand: " + status.delta.output);
  }
});

Dieser Code erkennt, wenn Relais 0 geschaltet wurde (egal ob durch ein Skript, eine Szene oder manuell) und gibt den neuen Zustand aus.

Vergleich: Wann nutzt man welchen Handler?

EigenschaftEventHandler (Shelly.addEventHandler)StatusHandler (Shelly.addStatusHandler)
Wann wird er ausgelöst?Nur bei spezifischen Ereignissen (z. B. Tasterdruck, MQTT-Nachricht)Bei jeder Statusänderung (z. B. Relais AN/AUS, Temperaturänderung)
Reaktion auf…Benutzeraktionen, externe Trigger, MQTTJede Statusänderung, egal wodurch verursacht
Typische AnwendungSchalter-Toggles, Bewegungssensoren, EreignissteuerungÜberwachung von Relais, Sensorwerten, WLAN-Verbindung
Wird ausgelöst durch…Aktionen wie Tastendruck, MQTT-Nachrichten, API-BefehleJede Änderung eines Statuswerts, auch durch andere Skripte oder Benutzer
BeispielReagieren, wenn ein Taster gedrückt wurdePrüfen, ob das Relais geschaltet wurde

Wann solltest du welchen Handler verwenden?

Verwende den EventHandler (Shelly.addEventHandler), wenn du

  • eine spezifische Aktion oder einen Trigger auswerten möchtest (z. B. Schalter, MQTT)
  • nur auf bestimmte Benutzeraktionen reagieren möchtest
  • ein Skript für schnelle, einmalige Reaktionen auf Events brauchst

Verwende den StatusHandler (Shelly.addStatusHandler), wenn du

  • jede Statusänderung mitverfolgen willst, egal wodurch sie ausgelöst wurde
  • Logik abhängig vom Gerätestatus implementieren möchtest
  • eine kontinuierliche Überwachung (z. B. Temperatur, WLAN-Status) brauchst

EventHandler / StatusHandler am Shelly 2PM mit Lampen

Um den Shelly 2PM noch flexibler zu steuern, kannst du EventHandler und StatusHandler nutzen, um direkt auf Schalterbetätigungen oder Statusänderungen zu reagieren. Anstatt regelmäßig mit einem Timer den Zustand abzufragen, ermöglichen diese Methoden eine sofortige Reaktion in Echtzeit.

Schaltung - Shelly 2PM Gen2 mit Schalter und Lampen
Schaltung – Shelly 2PM Gen2 mit Schalter und Lampen

In diesem Abschnitt zeige ich dir, wie du mit einem EventHandler direkt auf das Umschalten eines Schalters reagieren kannst und wie du mit einem StatusHandler überwachst, ob ein Relais geschaltet wurde – ideal für eine intelligente Lampensteuerung mit Shelly Scripting.

Script zum wechselseitigen Schalten mit StatusHandler

// Fügt einen Status-Handler hinzu, der auf Änderungen im Shelly-Gerät reagiert.
// Dieser Handler wird immer dann ausgelöst, wenn sich der Status eines Geräts verändert.
Shelly.addStatusHandler(function (status) {  

   // Überprüfen, ob das Ereignis vom Switch-Modul stammt und ob es sich um das Relais mit der ID 0 handelt.
   // Zudem wird geprüft, ob sich der `output`-Status (An/Aus) verändert hat.
   if (status.name === "switch" && status.id === 0 && status.delta.output) {
      
      // Definieren der Parameter für den Schaltbefehl:
      // - `id:1` -> Steuert das Relais mit der ID 1
      // - `on:false` -> Das Relais 1 wird ausgeschaltet
      let params = {id:1, on:false};

      // Senden des Befehls an das Shelly-Gerät, um Relais 1 auszuschalten.
      Shelly.call("Switch.Set", params);
   } 
   
   // Falls das Ereignis vom Relais mit der ID 1 stammt und sich der `output`-Status verändert hat:
   else if (status.name === "switch" && status.id === 1 && status.delta.output) {
      
      // Definieren der Parameter für den Schaltbefehl:
      // - `id:0` -> Steuert das Relais mit der ID 0
      // - `on:false` -> Das Relais 0 wird ausgeschaltet
      let params = {id:0, on:false};

      // Senden des Befehls an das Shelly-Gerät, um Relais 0 auszuschalten.
      Shelly.call("Switch.Set", params);
   }
});

Script zum wechselseitigen Schalten zweier Lampen mit EventHandler

// Fügt einen Event-Handler hinzu, der auf Ereignisse am Shelly reagiert.
// Diese Funktion wird aufgerufen, sobald eine Aktion (z. B. Schalterbetätigung) erkannt wird.
Shelly.addEventHandler(function (event) {  

  // Gibt das gesamte Event-Objekt im Debug-Log aus.
  // Dies hilft beim Debugging, um zu sehen, welche Daten das Event enthält.
  print(event);

  // Prüfen, ob das Ereignis vom Schalter 0 kommt und ob es sich um eine "toggle"-Aktion handelt.
  if (event.id === 0 && event.info.component === "switch:0" && event.info.event === "toggle") {
    
    // Definiert die Parameter für den Schaltbefehl:
    // - `id:1` -> Steuert das Relais mit der ID 1 (zweites Relais).
    // - `on:false` -> Das Relais 1 wird ausgeschaltet.
    let params = {id:1, on:false};

    // Senden des Befehls an das Shelly-Gerät, um Relais 1 auszuschalten.
    Shelly.call("Switch.Set", params);
  }

  // Prüfen, ob das Ereignis vom Schalter 1 kommt und ob es sich um eine "toggle"-Aktion handelt.
  if (event.id === 1 && event.info.component === "switch:1" && event.info.event === "toggle") {
    
    // Definiert die Parameter für den Schaltbefehl:
    // - `id:0` -> Steuert das Relais mit der ID 0 (erstes Relais).
    // - `on:false` -> Das Relais 0 wird ausgeschaltet.
    let params = {id:0, on:false};

    // Senden des Befehls an das Shelly-Gerät, um Relais 0 auszuschalten.
    Shelly.call("Switch.Set", params);
  }
});

Reagieren auf Sensoren mit dem StatusHandler am Shelly AddOn & Shelly 2PM

Mit dem StatusHandler kannst du nicht nur Relais überwachen, sondern auch auf Sensordaten in Echtzeit reagieren. In diesem Abschnitt zeige ich dir, wie du einen LDR (Lichtsensor) mit dem Shelly AddOn nutzt, um eine Lampe abhängig von der Umgebungshelligkeit automatisch ein- oder auszuschalten.

Schaltung - Shelly 2PM Gen2 + AddOn + LDR + Schalter + Lampen
Schaltung – Shelly 2PM Gen2 + AddOn + LDR + Schalter + Lampen

Das Prinzip funktioniert nicht nur mit einem LDR, sondern auch mit anderen Sensoren wie PIR-Bewegungssensoren, Abstandssensoren oder Temperatursensoren. Durch den StatusHandler erkennt das Shelly Script sofort Änderungen der Sensordaten und kann entsprechend reagieren – ohne Verzögerung und ohne ständige Abfragen durch einen Timer.

Shelly AddOn mit analogen & digitalen Sensoren
Shelly AddOn mit analogen & digitalen Sensoren

Wenn sich der LDR (Lichtsensor) am Shelly AddOn ändert, sendet der Shelly eine Statusänderung in JSON-Format, die folgendermaßen aufgebaut ist:

{
"component": "input:100",
12:06:58
"name": "input",
12:06:58
"id": 100,
12:06:58
"delta": { "id": 100, "percent": 20.31 }
12:06:58
}

Erklärung der JSON-Daten:

  • "component": "input:100" → Statusänderung kommt vom Eingangssensor (LDR an Port 100).
  • "delta.percent": 20.31 → Neuer Helligkeitswert in Prozent (hier 20,31 %).
  • "id": 100 → Die ID des Sensors, über die er angesprochen wird.

Daraus können wir folgendes kleines Script ableiten mit welchem wir bei Änderung der Helligkeit eine Lampe schalten können.

// Definiere Konstanten für die Schwellwerte des Ein- und Ausschaltens
const VAL_AUS = 15;  // Schwellenwert, oberhalb dessen das Licht ausgeschaltet wird
const VAL_AN = 20;   // Schwellenwert, unterhalb dessen das Licht eingeschaltet wird

// Initialisiere Objekte zur Steuerung der Lampen
let paramsLampeLinks = {id: 0, on: false};  // Lampe Links mit ID 0
let paramsLampeRechts = {id: 1, on: false}; // Lampe Rechts mit ID 1

// Füge einen Status-Handler für Ereignisse des Shelly-Geräts hinzu
Shelly.addStatusHandler(function (status) {
  print(status); // Debugging: Gibt den Status im Log aus

  // Prüfe, ob das Ereignis von "input:100" stammt und die ID 100 ist
  if (status.component === "input:100" && status.id === 100) {
    
    // Überprüfe den Helligkeitswert und steuere die Lampen entsprechend
    if (status.delta.percent < VAL_AN) {  
      // Wenn der Wert unter den Einschalt-Schwellenwert fällt, schalte beide Lampen ein
      paramsLampeLinks.on = true;
      paramsLampeRechts.on = true;
      print("Lampen AN");
      
    } else if (status.delta.percent > VAL_AUS) {
      // Wenn der Wert über den Ausschalt-Schwellenwert steigt, schalte beide Lampen aus
      paramsLampeLinks.on = false;
      paramsLampeRechts.on = false;
      print("Lampen AUS");
    }

    // Sende den neuen Status an das Shelly-Gerät, um die Lampen zu steuern
    Shelly.call("Switch.Set", paramsLampeLinks);
    Shelly.call("Switch.Set", paramsLampeRechts);
  }
});

Fazit: Effiziente Automatisierung mit EventHandler und StatusHandler

Mit dem EventHandler kannst du schnell und zuverlässig auf Ereignisse am Shelly reagieren, ohne dabei einen Timer im Hintergrund laufen zu lassen. Das spart nicht nur Ressourcen, sondern macht den Code auch einfacher und übersichtlicher. Dank dieser Methode erfolgt die Reaktion in Echtzeit, was besonders bei Schalterbetätigungen oder anderen direkten Eingaben von Vorteil ist.

Auch der StatusHandler hat enormes Potenzial, insbesondere für Automatisierungen mit Sensoren am Shelly. In zukünftigen Projekten lassen sich damit noch viele spannende Anwendungen umsetzen.

🔜 Im nächsten Beitrag widme ich mich dem Shelly i4 DC in Kombination mit Reed-Kontakten – sei gespannt! 🚀

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert