SwitchBot Smart-Home-Integration, kostenlos und Open Source
SwitchBot-Geräte über die offizielle Cloud-API: Bots, Steckdosen, Vorhänge, Schlösser, Sensoren.
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Steuere deine SwitchBot-Geräte aus Gladys über die offizielle Cloud-API von SwitchBot (v1.1): Bots, Steckdosen, Vorhänge und Rollos, Schlösser, Thermometer, Kontakt-, Bewegungs- und Wasserlecksensoren, Lampen, Luftbefeuchter, Luftreiniger, Ventilatoren, Saugroboter und die Infrarot-Fernbedienungen deiner Hubs.
Ohne die Hardware entwickelt: Rückmeldungen willkommen. Diese Integration wurde mit den von SwitchBot dokumentierten Antworten und den Testdaten der Home-Assistant-Integration gebaut und getestet, weder mit echten Geräten noch mit einem echten SwitchBot-Konto. Wenn etwas nicht wie beschrieben funktioniert, sag es im Gladys-Forum oder in den Issues.
Keine Verbindung zu SwitchBot (Wonderlabs). SwitchBot ist eine Marke ihres Inhabers.
Was du brauchst
- Gladys Assistant 5.1.0 oder neuer, mit Internetverbindung (die Integration spricht mit der SwitchBot-Cloud, nicht mit den Geräten in deinem Netzwerk).
- Ein SwitchBot-Konto und die SwitchBot-App ab Version 9.
- Für Bluetooth-Geräte (Bot, Vorhang, Meter, Kontaktsensor, Schloss…): einen SwitchBot-Hub (Hub Mini, Hub 2, Hub 3…) und den in der SwitchBot-App für jedes Gerät aktivierten Cloud-Dienst. WLAN-Geräte (Steckdosen, Lampen, Hub 2…) brauchen nichts weiter.
- Optional, für Echtzeit: ein Gladys-Plus-Abo (siehe unten).
Konfiguration
- Installiere die Integration: in Gladys Integrationen → Von GitHub installieren mit
https://github.com/guim31/gladys-switchbot, oder aus dem Katalog, sobald sie dort steht. - In der SwitchBot-App: Profil → Einstellungen → Über, tippe 10-mal auf App-Version und öffne dann die Entwickleroptionen: Die App zeigt ein Token und einen geheimen Schlüssel.
- In Gladys: Integrationen → SwitchBot → Konfiguration, füge Token und geheimen Schlüssel ein und speichere. Der Status wird grün und die Integration liest deine Geräteliste.
- Öffne den Tab Entdecken: Jedes unterstützte Gerät steht dort, mit dem Namen aus der SwitchBot-App. Klicke auf Hinzufügen, wähle einen Raum und speichere. Nur hinzugefügte Geräte werden gelesen.
- Der Knopf Verbindung testen zeigt, was die Integration gefunden hat: Geräte, nicht unterstützte Geräte, IR-Fernbedienungen, den Abfragetakt und die API-Aufrufe des Tages.
Weitere Einstellungen:
- IR-Fernbedienungen: veröffentlicht auch die virtuellen Infrarot-Fernbedienungen deiner Hubs (siehe unten).
- Ver- und Entriegeln erlauben: standardmäßig aus, die Schlösser werden dann nur gelesen (siehe unten).
- Sprache der Funktionsnamen: die Namen der Funktionen von Geräten, die nach der Änderung hinzugefügt werden (standardmäßig Französisch). Die anderen Texte folgen der Sprache deines Gladys.
Token und geheimer Schlüssel bleiben in der Gladys-Konfiguration, signieren jede Anfrage und erscheinen nie in den Protokollen. Ein neues Token in der App macht das alte ungültig: Füge das neue ein.
Aktualisierungsintervall und Kontingent
SwitchBot erlaubt 10.000 API-Aufrufe pro Tag und Konto, alle Apps mit demselben Token eingeschlossen. Darüber lehnt SwitchBot jeden Aufruf bis Mitternacht ab. Die Integration liest jedes hinzugefügte Gerät einmal pro Intervall (ein Aufruf pro Gerät):
- Automatisch (Standard): höchstens alle 2 Minuten und langsamer bei vielen Geräten, damit die Abfragen nie mehr als die Hälfte des Kontingents verbrauchen. Beispiele: 10 Geräte alle 3 Minuten, 26 alle 8 Minuten, 50 alle 15 Minuten.
- Ein festes Intervall (1 Minute bis 1 Stunde) wird verlängert, wenn es mehr als die Hälfte des Kontingents verbrauchen würde.
Die andere Hälfte bleibt für deine Befehle, das erneute Lesen nach jedem Befehl (ein Aufruf, einige
Sekunden später), die Echtzeit-Abfragen und deine anderen Apps. Die Integration zählt ihre Aufrufe
(in /data gespeichert, ein Neustart vergisst sie nicht): Ab 9.000 Aufrufen pausieren die
Abfragen bis Mitternacht, Befehle funktionieren weiter. Die Aufrufe deiner anderen Apps (Home
Assistant, Skripte…) sieht sie nicht: Verlängere das Intervall, wenn du das Token teilst.
Echtzeit über Gladys Plus (optional)
Ohne sie erscheint eine Änderung außerhalb von Gladys (eine geöffnete Tür, ein Knopf am Gerät) bei der nächsten Abfrage. Mit einem Gladys-Plus-Abo kann SwitchBot Gladys sofort benachrichtigen:
- Erstelle in Gladys Plus einen Open-API-Schlüssel (Einstellungen → Open API).
- Füge ihn in der Konfiguration der SwitchBot-Integration im Block Gladys-Plus-Webhooks ein.
- Schalte Echtzeit über Gladys Plus ein und speichere.
Die Integration registriert dann die Gladys-Plus-Adresse bei SwitchBot. Jede Änderungsmeldung löst ein Lesen dieses Geräts über die API aus (eine Meldung ist ein Auslöser und wird nie direkt übernommen), und diese Geräte werden nur noch alle 30 Minuten abgefragt, um eine verlorene Meldung aufzufangen. SwitchBot speichert nur einen Webhook pro Konto: Diesen zu registrieren, entfernt den einer anderen App (Home Assistant…). Das Ausschalten der Option entfernt die Gladys-Adresse.
Was jedes Gerät bietet
| Gerät | Funktionen in Gladys |
|---|---|
| Bot | Drücken / Schalter (im Druckmodus drückt jeder Befehl, dann fällt der Zustand auf aus), Batterie |
| Plug, Relay Switch 1 | Ein/Aus |
| Plug Mini (US, JP) | Ein/Aus, Leistungsverbrauch (W), Spannung (V), Strom (A) |
| Plug Mini (EU), Relay Switch 1PM | Ein/Aus, Leistung, Spannung, Strom, Verbrauch heute (kWh) |
| Curtain, Curtain 3, Roller Shade, Blind Tilt | Position (100 = offen), öffnen / schließen / stoppen, Batterie (nicht beim Blind Tilt) |
| Lock, Lock Pro, Lock Ultra, Lock Vision… | Schlossstatus, Tür (nicht beim Lock Lite), Batterie; ver- / entriegeln mit der Option |
| Meter, Meter Plus, Outdoor Meter, Meter Pro | Temperatur, Luftfeuchtigkeit, Batterie |
| Meter Pro CO2 | Temperatur, Luftfeuchtigkeit, CO2 (ppm), Batterie |
| Hub 2, Hub 3 | Temperatur, Luftfeuchtigkeit, Helligkeit (1 bis 20); Bewegung beim Hub 3 |
| Contact Sensor | Kontakt (offen / geschlossen), Bewegung, Batterie |
| Motion Sensor | Bewegung, Batterie |
| Water Leak Detector | Wasserleck, Batterie |
| Color Bulb, Strip Light 3, Floor Lamp, RGBICWW-Streifen / -Lampe | Licht, Helligkeit, Farbe, Farbtemperatur |
| Strip Light, RGBIC-Neonschläuche | Licht, Helligkeit, Farbe |
| Ceiling Light, Ceiling Light Pro | Licht, Helligkeit, Farbtemperatur |
| Humidifier | Ein/Aus, Luftfeuchtigkeit, Temperatur, Wassertank (niedrig, wenn leer) |
| Air Purifier (VOC, PM2.5, Tischmodelle) | Ein/Aus, Modus (normal, auto, Schlaf, Haustier) |
| Circulator Fan, Battery Circulator Fan, Standing Fan | Ein/Aus, Geschwindigkeit (1 bis 100 %, schaltet in den Direktmodus), Batterie bei Akkumodellen |
| Robot Vacuum S1, S1 Plus, K10+, K10+ Pro | Zustand, Reinigung (starten / stoppen), zurück zur Ladestation, Batterie |
| Robot Vacuum S10, S20, K10+ Pro Combo, K20+ Pro, K11+ | Zustand, zurück zur Ladestation, Batterie (starte sie aus der SwitchBot-App) |
Andere SwitchBot-Geräte (Hub Mini ohne Sensoren, Kameras, Tastenfelder…) werden nicht veröffentlicht: Der Knopf Verbindung testen listet sie auf. Manche Werte kommen verzögert: Nach einem Befehl wird das Gerät 5 Sekunden später erneut gelesen (15 Sekunden bei einem Vorhang).
Vorhänge und Rollos
Gladys liest eine Position als 100 = offen, 0 = geschlossen: Die Integration rechnet die Positionen von SwitchBot um, die andersherum zählen. Ein Blind Tilt ist in der Mittelstellung offen und an beiden Enden geschlossen: Seine Position ist 100 bei offenen Lamellen, und beim Setzen einer Position bleibt die zuletzt genutzte Richtung (hoch oder runter). Nur die Vorhänge können auf Befehl anhalten.
Schlösser
Ein Türschloss ist ein Sicherheitsgerät: Standardmäßig liest die Integration es nur (verriegelt, entriegelt, in Bewegung, blockiert oder halb verriegelt, und den Türzustand). Um aus Gladys (Dashboard, Szenen, mit Gladys verbundene Sprachassistenten) zu ver- und entriegeln, schalte Ver- und Entriegeln erlauben ein und füge das Schloss danach hinzu (oder aktualisiere es im Tab „Entdecken“). Denk daran, wer und was diese Befehle erreichen kann.
IR-Fernbedienungen
Mit der Option IR-Fernbedienungen wird jede virtuelle Fernbedienung deiner Hubs (TV, Klimaanlage, Ventilator, Lampe…) zu einem Gerät mit Ein/Aus-Knopf und dem zuletzt gesendeten Befehl. SwitchBot liefert für sie keinen Zustand: Ein/Aus zeigt den letzten gesendeten Befehl, nicht das Gerät. Jede andere Taste, eigene eingeschlossen, sendest du mit der Szenenaktion SwitchBot-IR-Befehl senden. Fernbedienungen vom Typ „Others“ haben nur eigene Tasten.
Dashboard-Widget
Das Widget SwitchBot zeigt auf einen Blick:
- bis zu sechs Temperaturen (Live-Kacheln deiner Thermometer und Hubs);
- offene Türen und Fenster (und offen gelassene), nicht verriegelte oder blockierte Schlösser, Wasserlecks, schwache Batterien;
- die API-Aufrufe des Tages und die SwitchBot-Cloud, wenn sie ablehnt oder nicht antwortet.
Es liest selbst nichts bei SwitchBot: Es zeigt die letzten Abfragen.
Szenenauslöser
Im Szeneneditor, Kategorie Integrationen:
- SwitchBot-Tür oder -Fenster: Ein Kontaktsensor meldet offen, geschlossen oder offen gelassen (die in der SwitchBot-App eingestellte Dauer, die ein einfacher Zustand nicht ausdrücken kann). Filter: der Sensor, die Zustände. Variablen: Gerätename, Zustand.
- SwitchBot erkennt Bewegung: Ein Bewegungsmelder, der eines Kontaktsensors oder ein Hub 3 erkennt eine Bewegung. Variable: Gerätename.
- SwitchBot-Wasserleck: Ein Wasserlecksensor wechselt von trocken zu nass. Variable: Gerätename.
- SwitchBot-Batterie schwach: Eine Batterie fällt auf 20 % oder weniger, einmal, bis sie wieder über 30 % liegt. Variablen: Gerätename, Batterie.
Diese Auslöser lösen nur bei einer Änderung aus, nie beim Start. Ohne Echtzeit kann eine Änderung, die kürzer als das Aktualisierungsintervall ist (eine kurze Bewegung), unbemerkt bleiben: Nutze für Bewegung die Gladys-Plus-Option.
Szenenaktionen
- SwitchBot-Bot drücken lassen: ein Druck des gewählten Bots, egal in welchem Modus.
- SwitchBot-IR-Befehl senden: eine Fernbedienung (mit der Option für IR-Fernbedienungen), ein
Befehl und ein optionaler Parameter. Standardbefehle:
turnOn,turnOff,volumeAdd,volumeSub,channelAdd,channelSub,setMute,Play,Pause,Stop,Next,Previous,swing,lowSpeed,middleSpeed,highSpeed,brightnessUp,brightnessDown,SetChannel(Parameter: der Sender) undsetAllfür eine Klimaanlage (Parameter:Temperatur,Modus,Lüfter,Ein/Aus, zum Beispiel26,2,1,on: Modus 1 auto, 2 kühlen, 3 entfeuchten, 4 lüften, 5 heizen; Lüfter 1 auto, 2 niedrig, 3 mittel, 4 hoch). Jeder andere Name ist eine eigene Taste der Fernbedienung, Groß- und Kleinschreibung beachten.
Szenenbeispiele
- Tür offen gelassen: Auslöser SwitchBot-Tür oder -Fenster, Zustand Offen gelassen → Nachricht „{{triggerEvent.data.device_name}} ist immer noch offen“.
- Wasserleck: Auslöser SwitchBot-Wasserleck → Nachricht „Wasserleck: {{triggerEvent.data.device_name}}“, dann die Steckdose der Waschmaschine ausschalten.
- Morgenkaffee: werktags um 7:00 → SwitchBot-Bot drücken lassen (der Bot der Kaffeemaschine), dann den Wohnzimmervorhang auf 100 % öffnen.
- Abkühlen: Wenn die Schlafzimmertemperatur über 27 °C steigt → SwitchBot-IR-Befehl senden,
setAllmit24,2,1,onan die Fernbedienung der Klimaanlage. - Batterien: Auslöser SwitchBot-Batterie schwach → Nachricht „Wechsle die Batterie von {{triggerEvent.data.device_name}} ({{triggerEvent.data.battery}} %)“.
Fehlerbehebung
- „SwitchBot lehnt die Zugangsdaten ab“: Prüfe Token und geheimen Schlüssel (kopiere sie erneut aus der App; ein neues Token macht das alte ungültig). Dieselbe Antwort kommt, wenn das Tageskontingent aufgebraucht ist: Warte bis Mitternacht und verlängere das Intervall, wenn du das Token mit einer anderen App teilst. Die Integration versucht es alle 30 Minuten erneut.
- „Die SwitchBot-Cloud antwortet nicht“: Prüfe die Internetverbindung von Gladys. Die Integration versucht es alle 5 Minuten erneut.
- Ein Gerät fehlt in „Entdecken“: Es wird vielleicht nicht unterstützt (siehe Verbindung testen), oder sein Cloud-Dienst ist in der SwitchBot-App aus. Suche danach erneut im Tab „Entdecken“.
- Ein Gerät ist nicht erreichbar: SwitchBot meldet, dass das Gerät oder sein Hub offline ist (Batterie leer, außerhalb der Bluetooth-Reichweite des Hubs, Hub ausgesteckt).
- Werte kommen verspätet: Das ist das Aktualisierungsintervall (siehe Verbindung testen); schalte für Türen und Bewegung die Gladys-Plus-Echtzeit ein.
- Echtzeit funktioniert nicht: Prüfe, dass der Open-API-Schlüssel im Block der Gladys-Plus-Webhooks steht und die Option an ist; eine andere App hat vielleicht inzwischen ihren eigenen Webhook registriert (SwitchBot speichert einen): Speichere die Konfiguration erneut.
- Protokolle: Setze
LOG_LEVEL=debugfür die Integration, um jede Abfrage zu sehen; Token und geheimer Schlüssel erscheinen dort nie.
Grenzen
- Nur Cloud: keine lokale Bluetooth-Steuerung, die Geräte brauchen einen Hub und eine Internetverbindung, und die Server von SwitchBot müssen antworten.
- 10.000 API-Aufrufe pro Tag und Konto: Die Werte werden alle paar Minuten aktualisiert, nicht sofort, außer mit der Gladys-Plus-Echtzeit.
- Die SwitchBot-API ist für den privaten Gebrauch bestimmt (siehe ihre Bedingungen).
- Kein Zustand für IR-Fernbedienungen; keine Reinigungsprogramme für die neueren Saugroboter; keine Lüftermodi, Nachtlichter oder Kindersicherungen; noch keine Tastenfelder, Kameras, Videotürklingeln, Thermostate oder Relay Switch 2PM.
- Die Integration zählt nur ihre eigenen API-Aufrufe, nicht die deiner anderen Apps.
- Ohne Hardware und ohne SwitchBot-Konto entwickelt: Feldnamen und Werte stammen aus der SwitchBot-Dokumentation und aus den Tests von Home Assistant.
Konfigurationseinstellungen
Diese Einstellungen fragt SwitchBot in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Dein SwitchBot-Token | section | Nein | In der SwitchBot-App (ab Version 9): Profil, Einstellungen, Über, tippe 10-mal auf App-Version, dann Entwickleroptionen: Kopiere Token und geheimen Schlüssel hierher. Bluetooth-Geräte brauchen einen SwitchBot-Hub und den in der App aktivierten Cloud-Dienst. |
| Token | secret | Ja | Das Token aus den Entwickleroptionen der SwitchBot-App. |
| Geheimer Schlüssel | secret | Ja | Der geheime Schlüssel unter dem Token. Er signiert jede Anfrage und verlässt Gladys nie. |
| Aktualisierungsintervall | select | Nein | Wie oft jedes Gerät gelesen wird. SwitchBot erlaubt 10.000 Aufrufe pro Tag und Konto: Automatisch nutzt höchstens die Hälfte, ein kürzeres Intervall wird verlängert, wenn es mehr bräuchte. |
| Echtzeit über Gladys Plus | boolean | Nein | Braucht Gladys Plus und dessen Open-API-Schlüssel im Webhook-Block. SwitchBot speichert EINEN Webhook pro Konto: Der einer anderen App (Home Assistant…) wird ersetzt. |
| IR-Fernbedienungen | boolean | Nein | Auch die virtuellen Infrarot-Fernbedienungen deiner Hubs (TV, Klimaanlage…) veröffentlichen, für ihren Ein/Aus-Knopf und die Szenenaktion „IR-Befehl senden“. |
| Ver- und Entriegeln erlauben | boolean | Nein | Aus: Die Schlösser werden nur gelesen. Ein: Danach hinzugefügte Schlösser lassen sich von Gladys, ihren Szenen und Assistenten ver- und entriegeln. |
| Sprache der Funktionsnamen | select | Nein | Namen, die den Funktionen neuer Geräte gegeben werden (Temperatur, Position, Batterie…). |
So installierst du SwitchBot in Gladys
- Öffne in Gladys Integrationen: SwitchBot erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-switchbot:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-switchbot.
SwitchBot benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
SwitchBot ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle externen Integrationen durchsuchen
- Die nativen Integrationen entdecken, die in Gladys eingebaut sind
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation