Modul Shelly

Todo: Achtung: Diese Seite ist teilweise veraltet, insbesondere unterstützt das Modul weitere Aktoren. Bitte Commandref lesen - diese Seite ist in Überarbeitung

Shelly
Zweck / Funktion
Das Modul stellt ein Interface zur Bedienung von Shelly Devices zur Verfügung
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE Thema
Support (Forum)	Sonstige Systeme
Modulname	36_Shelly.pm
Ersteller	Starkstrombastler (Forum /Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Auf dieser Seite werden die Aktoren des bulgarischen Herstellers Allterco Robotics beschrieben (Markenname Shelly) sowie deren Ansteuerung mit FHEM und aufgetretene Probleme.

Achtung: Einige der auf dieser Seite erwähnten Geräte und Funktionen sind derzeit nur mit dieser Testversion verfügbar, die manuell installiert werden muss!

• Für die Weiterentwicklung des Moduls wurde im Forum ein neues Thema (Entwicklungs-Thread Modul 36_Shelly.pm) aufgemacht.

Bei den Shelly-Geräten handelt es sich um IP-basierte Schalt- und Dimmaktoren, die auf verschiedene Weise angesteuert werden können

• über die Web-Oberfläche des eingebauten Mikro-Webservers,
• über eine proprietäre App des Herstellers (Achtung, Cloud!),
• über das hier beschriebene FHEM-Modul 36_Shelly.pm
• über MQTT

Ein Teil der Aktoren verfügt über eine eingebaute Leistungsmessung (siehe Spalte Messkanäle in unten stehender Tabelle).

Geräteübersicht

Übersicht der IP-basierten Produktreihen

ID	Produktreihe	gemeinsame Merkmale
SH	erste Generation	COIOT (Nutzung mit Shelly-Monitor), kein Bluetooth
SN	Shelly Plus Shelly Plus mini
SP	Shelly Pro	Montage auf Hutschiene, zusätzlicher Ethernet-Port (RJ45)
S3	Shelly Gen3 Shelly Gen3 mini	proprietärer Prozessor
SA	Control Panel	Android-System

ID: erste beiden Stellen der Modell-ID

Liste der aktuell unterstützten Geräte (hier nicht aufgeführte Geräte der ersten Generation können zusammen mit dem Shelly-Monitor genutzt werden):

Modell	Typ	Schalt- kanäle	Dimm- kanäle	Mess- kanäle	Digital Eingänge	Bemerkungen
Gen 1
Shelly 1	Schalter	1			1
Shelly 1PM	Schalter	1		1	1
Shelly 1L	Schalter	1		1	1
Shelly 2	Schalter	2		1	2
	Rollladenaktor	1		1	2
Shelly 2.5	Schalter	2		2	2
	Rollladenaktor	1		1	2
Shelly 4Pro	Schalter	4		4	4
Shelly i3	Digitale Eingänge				3
Shelly EM	Leistungsmessung	1		2
Shelly 3EM	Leistungsmessung	1		3
Shelly Uni	Universal	2			*)	1-Wire, 2 potentialfreie Relaisausgänge Analogeingänge
Shelly Plug Shelly Plug S	Schaltsteckdose	1		1		1 Taster
Shelly RGBW2	Dimmer		4	4	1	4-fach Aktor
	Dimmer		1	1	1	RGBW Controller
Shelly Dimmer2	Dimmer		1	1	2
Shelly Duo	Leuchte		1			E27 oder GU10 Fassung
Shelly Vintage	Leuchte		1
Shelly Bulb	Leuchte		1			Modi: weiß oder farbe
Shelly Plus
Shelly Plus 1	Schalter	1			1
Shelly Plus 1PM	Schalter	1		1	1
Shelly Plus 2PM	Schalter	2		2	2
	Rollladenaktor	1		1	2
Shelly Plus i4	Digitale Eingänge				4	AC und DC - Variante
Shelly Plus Plug S Shelly Plus Plug IT Shelly Plus Plug UK Shelly Plus Plug US	Schaltsteckdose	1		1		1 Taster; Varianten V1, V2
Shelly Plus Uni	Universal	2			*)	1-Wire, 2 potentialfreie Relaisausgänge Analogeingänge; Neu in 2024
Shelly Plus 0-10V Dimmer	Dimmer		1	1	2	0-10 V DC Ausgang
Shelly Plus RGBW	Dimmer		4	4	4	4-fach Aktor
	Dimmer		1	1	1	RGBW Controller
Shelly Plus Mini
Shelly Plus 1 Mini	Schalter	1			1
Shelly Plus 1PM Mini	Schalter	1		1	1
Shelly PM Mini	Leistungsmessung			1
Shelly Pro
Shelly Pro 1	Schalter	1			2
Shelly Pro 1PM	Schalter	1		1	2
Shelly Pro 2	Schalter	2			2
Shelly Pro 2PM	Schalter	2		2	2
Shelly Pro Dual	Rollladenaktor	4			4	2 Rolladenaktoren
Shelly Pro Dimmer 1PM	Dimmer		1	1	2
Shelly Pro Dimmer 2PM	Dimmer		2	2	4
Shelly Pro 3	Schalter	3			3
Shelly Pro 3EM	Leistungsmessung			3		1 Schaltkanal mit Addon
Shelly Pro EM50	Leistungsmessung
Shelly Pro 4PM	Schalter	4		4	4
Shelly Gen3
Shelly 1 Gen3	Schalter	1			1
Shelly 1PM Gen3	Schalter	1		1	1
Shelly i4 Gen3	Digitale Eingänge				4
Shelly Dimmer 0/1-10V Gen3	Dimmer		1	1	2	0-10V DC oder 1-10V DC Ausgang
Shelly Gen3 Mini
Shelly 1 Mini Gen3	Schalter	1			1
Shelly 1PM Mini Gen3	Schalter	1		1	1
Shelly PM Mini Gen3	Leistungsmessung			1
Control Panels
Shelly Wall Display	Control Panel	1			1

Einbindung in FHEM

Vorgehensweise zur Einbindung eines Shelly-Gerätes in FHEM:

• Aktor nach Vorschrift anschließen
• mit einem WLAN-fähigen Gerät (Laptop, Smartphone, Tablet...; im Folgenden als Laptop bezeichnet) nach dem internen Access Point suchen, der durch das Shelly-Gerät erzeugt wird; typischerweise hat es eine SSID ähnlich wie

shelly1-..., shellyswitch-..., shelly4pro-...,

• Laptop mit diesem Access Point verbinden; typischerweise bekommt das Gerät dabei die IP-Adresse 192.168.33.2 zugewiesen.
• im Browser des Laptops die IP-Adresse 192.168.33.1 aufrufen - das ist der Shelly selbst; in der damit angezeigten Weboberfläche kann das Shelly-Gerät konfiguriert werden
  • Shelly ins häusliche WLAN anmelden (mit fester IP-Adresse <shelly-ip> natürlich...)
  • Internen Access Point abschalten (kann auch nach dem nächsten Schritt oder noch später erfolgen)
  • Testen: Laptop wieder mit dem häuslichen WLAN verbinden, und im Browser die Adresse <shelly-ip> aufrufen
• In FHEM definieren

define myShelly Shelly <shelly-ip>

• Das Modul setzt bei bekannten Geräten das Attribut model automatisch. Bei nicht unterstützten Geräten wird das Attribut auf den Wert generic gesetzt. In diesen Fällen kann das Attribut model auf der Detailseite des Devices manuell gesetzt werden:

attr myShelly model shellyrgbw|shellydimmer|shelly2.5|shelly2|shellyem|shelly3em|shelly4|shellyplug|shelly1|shellybulb|shelly1pm|shellyuni|generic

Falls es sich um einen Shelly2 oder 2.5 handelt, muss ferner das Attribut mode auf "roller" oder "relay" gesetzt werden. Mit diesem Modul können alle Daten übertragen und (prinzipiell) alle Konfigurationsänderungen durchgeführt werden, außerdem ist es auf einfachste Weise zu installieren. Das Modul pollt im per Attribut interval einstellbaren Abstand zyklisch den Aktor auf Statusänderungen (Wert 0 => kein Polling). Damit der Aktor im Stande ist, irgendwelche Zustandsänderungen von sich aus an FHEM zu melden, müssen diese als REST-Befehle (also URL-Aufrufe) in der Konfigurationsoberfläche des Shelly-Aktors eingetragen werden. Siehe CommandRef.

Zum Betrieb ist ferner noch zu bemerken, dass das Modul zwar meldet, ob ein Firmware-Update nötig ist, ausgelöst werden muss dieses aber über die Web-Oberfläche des Shelly selber.

Actions/Webhooks (nur Testversion)

Ab Shelly Firmware 1.5.0 werden Actions unterstützt. Damit besteht die Möglichkeit, dass ein Shelly bei Eintreten bestimmter Ereignisse von sich aus Meldungen an andere Shellies und/oder übergeordnete Systeme wie FHEM absetzt. Dies ist nützlich, um Statusänderungen, die z.B. durch lokal betätigte Tasten entstehen, direkt an FHEM zu übermitteln.

Nachfolgende Beispiele zeigen den Code, der im Shelly unter URL einzutragen ist:

Ausgang (Relais) eines Shelly1 schaltet ein:

http://<FHEM-IP>:<Port>/fhem?cmd=set%20<name>%20out_on

hierbei sind:

<FHEM-IP> die IP-Adresse des Servers auf dem FHEM läuft

<Port> die Port-Nummer

<name> der Name des FHEM-Devices

%20 stellt ein Leerzeichen dar

Beispiel 2: Eingang eines Shelly2 wird betätigt:

http://<FHEM-IP>:<Port>/fhem?cmd=set%20<name>%20input_on%20<ch>

<ch> die Nummer des Schaltkanals (Nummer des Eingangs), z.B. 0 oder 1

Beispiel 3: Eingang1 eines ShellyDimmers wird betätigt:

http://&#x3C;FHEM-IP&#x3E;:&#x3C;Port&#x3E;/fhem?cmd=set%20&#x3C;name&#x3E;%20short_push<nowiki/>%20<inp>

<inp> Nummer des Eingangs, 0 oder 1 (ShellyDimmer verfügen je Schaltkanal über zwei Eingänge)

Beispiel 4: Wirkleistung eines ShellyPro3EM:

http://<FHEM-IP>:<Port>/fhem?fwcsrf=csrf_368985985592099&cmd=set%20Y173%20Active_Power_$phase%20$active_power

fwcsrf=csrf_368985985592099 das CSRF-Token (FHEMWeb)

$phase wird vom Shelly durch a, b oder c ersetzt

$active_power wird vom Shelly durch die aktuelle Wirkleistung ersetzt

Endpoints

In vorstehenden Beispielen stellt der Teil set%20<name>%20<cmd> den Endpoint dar, d.h. dies ist der Befehl, der vom Shelly-Device in FHEM verarbeitet werden muss.

Liste der Befehle der Set-Endpoints:

<cmd>	Wert	Reading	Erläuterung	Geräte
out_on		relay_<ch>state	Ausgang ein	alle Shelly mit Relaisausgang ShellyBulb ShellyRGBW
out_off			Ausgang aus
button_on		button_<ch>	Eingang ein	ShellyPlug ShellyPlugS
button_off			Eingang aus
input_on		input_<ch>	Eingang ein	alle Shelly mit HW-Eingang, aber nicht Shelly-I-Geräte
input_off			Eingang aus
input_on		input_<inp>	Eingang ein	ShellyDimmer
input_off			Eingang aus
short_push			kurzer Tastendruck
long_push			langer Tastendruck
single_push		input_<ch>input_<ch>_action	kurzer Tastendruck	ShellyI3 ShellyI4
long_push			langer Tastendruck
double_push			zweifacher Tastendruck
triple_push			dreifacher Tastendruck
short_long_push			Tastersequenz lang-kurz	ShellyI3
long_short_push			Tastersequenz kurz-lang
stopped		state	Rollo angehalten	Shelly2/2.5/Plus2/Pro2 mode=roller *) nur für Shelly Plus2/Pro2
opening			Rollo wird geöffnet
closing			Rollo wird geschlossen
is_open *)			Rollo offen (in oberer Endlage)
is_closed *)			Rollo geschlossen (in unterer Endlage)
temperature_over		temperature_<ch>_range	Temperatur überschreitet eingestellten Grenzwert	ShellyAddOn
temperature_under		temperature_<ch>_range	Temperatur unterschreitet eingestellten Grenzwert
humidity_over		humidity_<ch>_range	Luftfeuchtigkeit überschreitet eingestellten Grenzwert
humidity_under		humidity_<ch>_range	Luftfeuchtigkeit unterschreitet eingestellten Grenzwert
tempC	$temperature	temperature	Temperatur in °C
voltage_over		voltage_range	Spannung überschreitet eingestellten Grenzwert	ShellyUni
voltage_under			Spannung unterschreitet eingestellten Grenzwert
Active_Power_$phase	$active_power	Active_Power_<ph>	Änderung Wirkleistung	ShellyPro3EM
Voltage_$phase	$voltage	Voltage_<ph>	Änderung Spannung
Current_$phase	$current	Current_<ph>	Änderung Strom

Bei Eintreffen eines Set-Endpoints wird im Shelly-Device das zugeordnete Reading entsprechend gesetzt. Damit kann das Shelly-Ereignis z.B. mit einem notify ausgewertet werden. Im Anschluss daran holt sich das Modul die aktuellen Daten vom Shelly und setzt das Intervall zurück.

Anmerkung zum ShellyPro3EM: Die Action wird erst bei einer gewissen Änderung des jeweiligen Wertes ausgelöst. Bei kleinen Schwankungen kommen also keine Webhooks in FHEM an.

Get-Endpoint

Eine besondere Form stellt der Get-Endpoint dar, mit dem das Shelly-Device in FHEM aufgefordert wird, den Status des Shelly zu holen. Beispiel:

http://<FHEM-IP>:<Port>/fhem?cmd=get%20<name>%20status

Attribut webhook (derzeit nur Gen2)

Durch Setzten des Attributes webhook werden auf dem Shelly die verfügbaren Webhooks automatisiert angelegt (auf der Shelly Oberfläche unter Actions zu sehen). Als Attribut-Wert muss das empfangende FHEMWeb-Device ausgewählt werden. Wird das FHEMWeb-Device mit einem csrf-Token abgesichert, wird der Token in den Webhook eingebunden. Bei Änderungen des Tokens (z.B. bei Neustart von FHEM) werden die entsprechenden Webhooks mit angepasst.

Die vom Modul angelegten Webhooks erhalten im Shelly einen Namen, beginnend mit einem Unterstrich (_). Wird das Attribut geändert oder gelöscht, dann werden auch zugehörige Actions geändert bzw. gelöscht. Durch Entfernen des Unterstrichs im Namen der Action kann dieser Mechanismus unterbunden werden.

Das Reading webhook_cnt zeigt die Anzahl aller auf dem Shelly hinterlegten Webhooks und webhooks_ver den Versionszähler des Shelly.

Eine Übersicht aller Actions/Webhooks eines Shelly bekommt man für Gen2-Geräte mit:

http://<ip-des-Shelly>/rpc/Webhook.List

MQTT

MQTT (Message Queue Telemetry Transport) ist ein nachrichtenbasiertes Protokoll, bei dem Geräte (Devices) nicht direkt miteinander, sondern mit einem zentralen MQTT-Server (in alter Nomenklatur Broker genannt) kommunizieren. Eine kurze Einführung in MQTT findet man auf der Seite MQTT Einführung. Mit entsprechend gesetzten Attributen lassen sich die Shelly-Aktoren auch steuern (Praxisbeispiele zu den MQTT2-Modulen), für Anfänger ist das allerdings nicht unbedingt zu empfehlen.

Links

• Support Thread zu diesem Modul
• Entwicklungs Thread zur Weiterentwicklung des Moduls, ab Februar 2024
• Website des Herstellers der Geräte
• Forum des Herstellers (englischsprachig