DIY MODE API-Protokoll

Möchten Sie das SONOFF-Gerät über Ihre eigene App oder Heimautomatisierungsplattform steuern? Der DIY-Modus hilft!

Der DIY-Modus ist für IoT-Heimautomatisierungsnutzer und -Entwickler konzipiert, die das SONOFF-Gerät über eine vorhandene Open-Source-Heimautomatisierungsplattform oder einen lokalen HTTP-Client anstelle der eWeLink-App steuern möchten. Im DIY-Modus veröffentlicht das Gerät seine Dienste und Funktionen gemäß dem mDNS/DNS-SD-Standard, sobald es mit dem Netzwerk verbunden ist. Vor der Veröffentlichung des Dienstes aktiviert das Gerät den HTTP-Server auf dem im DNS-SRV-Eintrag angegebenen Port. Das Gerät stellt die Funktionen über eine HTTP-basierte RESTful-API bereit. Benutzer können Geräteinformationen abrufen und das Gerät per HTTP-API-Anfrage steuern.

Die SONOFF-Geräte ^[1] können entweder im eWeLink-Modus oder im DIY-Modus arbeiten. Im eWeLink-Modus ist das Gerät mit der eWeLink-Cloud verbunden und wird über die eWeLink-App gesteuert, während das Gerät im DIY-Modus seinen Leistungsdienst veröffentlicht und über eine HTTP-Post-Anfrage gesteuert wird.

Die Schritte zum Aufrufen des DIY-Modus und zum Verbinden mit einem vorhandenen WLAN-Netzwerk:

1. Wechseln Sie in den kompatiblen Kopplungsmodus (AP), indem Sie nach dem Einschalten die Kopplungstaste 5 Sekunden lang gedrückt halten
2. Verbinden des Access Points mit dem Namen ITEAD-XXXXXXXXXX und dem Standardkennwort 12345678 über Mobiltelefon oder PC
3. Browser besucht http://10.10.7.1/
4. Eingabe der SSID und des Passworts des vorhandenen WLAN-Netzwerks
5. Erfolgreicher Wechsel in den DIY-Modus mit verbundenem bestimmten WLAN-Netzwerk.

Beispiel für einen Einkanal-DIY-Stecker (BASICR3, RFR3, MINI/MINIR2, MINIR3), der in den DIY-Modus wechselt:

1. Einschalten;
2. Halten Sie die Taste 5 Sekunden lang gedrückt, um in den kompatiblen Kopplungsmodus (AP) zu wechseln.
   Benutzertipps: Wenn das Gerät mit der eWeLink-App gekoppelt wurde, muss das Gerät zurückgesetzt werden, indem Sie die Kopplungstaste 5 Sekunden lang gedrückt halten und dann weitere 5 Sekunden drücken, um in den kompatiblen Kopplungsmodus (AP) zu wechseln.
3. Die LED-Anzeige blinkt kontinuierlich
4. In den WLAN-Einstellungen des Mobiltelefons oder PCs wird ein Access Point des Geräts mit dem Namen ITEAD-XXXXXXXXXX gefunden. Verbinden Sie ihn mit dem Standardkennwort 12345678
5. Öffnen Sie den Browser und rufen Sie http://10.10.7.1/ auf.
6. Geben Sie als Nächstes die WLAN-SSID und das Passwort ein, mit denen das Gerät verbunden wäre
7. Erfolgreich, jetzt ist das Gerät im DIY-Modus.

Beispiel für einen Einkanal-DIY-Dimmer (D1), der in den DIY-Modus wechselt:

1. Einschalten;
2. Halten Sie die Pairing-Taste der RM433- Fernbedienung 5 Sekunden lang gedrückt, um in den kompatiblen Pairing-Modus (AP) zu wechseln.
   Benutzertipps: Wenn das Gerät mit der eWeLink-App gekoppelt wurde, muss das Gerät zurückgesetzt werden, indem Sie die Kopplungstaste der RM433- Fernbedienung 5 Sekunden lang gedrückt halten und dann weitere 5 Sekunden drücken, um in den kompatiblen Kopplungsmodus (AP) zu wechseln.
3. Das dimmbare Licht, das mit D1 verbunden ist, blinkt kontinuierlich (springt sofort von 100 % auf 1 %, von 1 % auf 100 % …)

Die Schritte 4 – 7 sind dieselben wie im Beispiel des Single Channel DIY Plug.

Beispiel für den Wechsel des Smart Power Meter (SPM-Main) in den DIY-Modus:

1. Einschalten;
2. Halten Sie die Taste auf SPM-Main 5 Sekunden lang gedrückt, um in den Bluetooth-Kopplungsmodus zu wechseln.
   Benutzertipps: Wenn das Gerät mit der eWeLink-App gekoppelt wurde, muss das Gerät zurückgesetzt werden, indem die Kopplungstaste 5 Sekunden lang gedrückt gehalten wird, um in den Bluetooth-Kopplungsmodus zu wechseln.
3. Die LED-Anzeige blinkt schnell.
4. Verbinden Sie SPM-Main über ein Ethernet-Kabel mit Ihrem Router. Zum Herstellen der Verbindung steht Ihnen eine der folgenden Methoden zur Verfügung.
5. Geben Sie die IP-Adresse von SPM-Main in den Browser auf Ihrem Computer ein und greifen Sie zu.
6. Geben Sie als Nächstes die WLAN-SSID und das Passwort ein.
7. Erfolgreich. Jetzt befindet sich das Gerät im DIY-Modus.

Beispiel für eine intelligente LED-Glühbirne (B02-BL-A60, B05-BL-A19, B05-BL-A60), die in den DIY-Modus wechselt:

1. Einschalten;
2. Wenn das Licht an ist, drücken Sie den Lichtschalter 5 Mal hintereinander im Abstand von 1 Sekunde (Aus-EIN-Aus-EIN-Aus-EIN-Aus-EIN-Aus-EIN).
3. Das „schnelle Blinken“ zeigt an, dass das Gerät in den kompatiblen Kopplungsmodus (AP) wechselt.
4. In den WLAN-Einstellungen des Mobiltelefons oder PCs wird ein Access Point des Geräts mit dem Namen ITEAD-XXXXXXXXXX gefunden. Verbinden Sie ihn mit dem Standardkennwort 12345678
5. Öffnen Sie den Browser und rufen Sie http://10.10.7.1/ auf.
6. Geben Sie als Nächstes die WLAN-SSID und das Passwort ein, mit denen das Gerät verbunden wäre
7. Erfolgreich, jetzt ist das Gerät im DIY-Modus.

Notiz:

• Die Benutzereinstellungen werden gelöscht, sobald der Betriebsmodus geändert wird.
• Der WLAN-Router oder AP sollte im 2,4-GHz-Bereich arbeiten und den mDNS-Dienst unterstützen.
• Bedeutung der blinkenden LED
  Schnelles Einzelblinken – Das Gerät stellt keine Verbindung zum WLAN-Netzwerk her;
  Schnelles Doppelblinken – Das Gerät stellt erfolgreich eine Verbindung zum WLAN her, kann über mDNS erkannt werden und auf die Anfrage vom LAN-Netzwerk antworten.
• Sobald sich das Gerät bereits im DIY-Modus befindet, ist die WLAN-Konfigurationsseite http://10.10.7.1/ nicht mehr zugänglich.
• Wenn eine falsche WLAN-SSID oder ein falsches Passwort eingegeben wurde, kann das Gerät keine Verbindung mit einem bestimmten WLAN-Netzwerk herstellen. Nach einem Timeout von 20 Sekunden stellt das Gerät die Verbindung zum WLAN-Netzwerk ein. Versuchen Sie es erneut mit den Beispielschritten 1–7.
• Offizielle Firmware-Upgrades sind nur in der eWeLink-App verfügbar.
• Auf das Protokoll v1.4 kann über https://github.com/itead/Sonoff_Devices_DIY_Tools zugegriffen werden

Die LAN-Erkennung im DIY-Modus implementiert das IETF Multicast DNS-Protokoll und das DNS-basierte Service-Discovery-Protokoll. ^{[2] – [8]}

Das Gerät veröffentlicht seinen eigenen Dienst (d. h. die Gerätefähigkeit) gemäß dem mDNS/DNS-SD-Standarderkennungsprotokoll, wenn das Gerät mit einem LAN (Local Area Network) verbunden ist.

Die Felddefinition lautet wie folgt:

TXT-Datensatzhinweis :

1. Der TXT-Eintrag muss die folgenden Zeichenfolgen enthalten:
   „ txtvers =1“, „ id =[Geräte-ID]“, „ type =[Gerätetyp]“, „ apivers =[Version der Geräte-API-Schnittstelle]“, „ seq =[Seriennummer des TXT-Datensatzes]“, „ data1 =[Geräteinformationen]“;
2. Optionale Zeichenfolgen:
   „ data2 =[Geräteinformationen]“, „ data3 =[Geräteinformationen]“, „ data4 =[Geräteinformationen]“
3. „ seq = [TXT-Datensatzsequenznummer]“ gibt die Reihenfolge an, in der die TXT-Datensätze aktualisiert werden (die Reihenfolge, in der der Gerätestatus aktualisiert wird). Es wird empfohlen, eine positive Ganzzahl zu verwenden, die von 1 an hochzählt (wird beim Neustart des Geräts auf 1 zurückgesetzt).
4. Wenn die Geräteinformationen länger als 249 Byte sind, müssen die ersten 249 Byte in data1 gespeichert werden. Die restlichen Bytes werden durch die Länge 249 geteilt und in data2, data3 und data4 gespeichert. Das vollständige Geräteinformationsformat ist ein JSON-Objekt.

Beispiel für einen mDNS-TXT-Eintrag für BASICR3, RFR3, MINI:
data1= {„Schalter“: „Ein“, „Start“: „Bleiben“, „Puls“: „Ein“, „Pulsbreite“: 2000, „RSSI“: –67, „fwVersion“: „3.5.0“}

Beispiel für einen D1 (Dimmer) mDNS-TXT-Eintrag:
data1= {„Schalter“: „Ein“, „Modus“: 0, „Helligkeit“: 50, „HelligkeitMin“: 0, „HelligkeitMax“: 255, „Start“: „Ein“, „RSSI“: -67, „fwVersion“: „3.5.0“}

Beispiel für einen SPM-Main mDNS-TXT-Eintrag:
data1= {„subDevId“: „123456“, „Schalter“: [{„Schalter“: „ein“, „Steckdose“: 0},{„Schalter“: „ein“, „Steckdose“: 1},{„Schalter“: „ein“, „Steckdose“: 2},{„Schalter“: „ein“, „Steckdose“: 3}]}

Beispiel für einen MINIR3 mDNS-TXT-Eintrag:
data1= {„Schalter“:[{„Schalter“:“ein“,”Steckdose“:0},{„Schalter“:“aus“,”Steckdose“:1},{„Schalter“:“aus“,”Steckdose“:2},{„Schalter“:“aus“,”Steckdose“:3}],”sledOnline“:“ein“}

Beispiel für einen TXT-Datensatz für B02-BL-A60, B05-BL-A19, B05-BL-A60:
data1= {„Schalter“: „aus“, „Start“: „aus“, „Puls“: „aus“, „Pulsbreite“: 500, „SSID“: „eWeLink“, „otaUnlock“: falsch, „fwVersion“: „3.5.0“, „Geräte-ID“: „100000140e“, „BSSID“: „ec:17:2f:3d:15:e“, „Signalstärke“: -25}

Wenn sich andere Inhalte als die Sequenz ändern, z. B. der Name der Dienstinstanz geändert wird, Geräteinformationen aktualisiert werden usw., muss das Gerät den entsprechenden DNS-Eintrag (einschließlich der inkrementierten Sequenz) gemäß dem mDNS/DNS-SD-Standard per Multicast senden.

Der Erkennungsprozess muss dem mDNS/DNS-SD-Erkennungsprotokoll folgen, um das Sonoff-DIY-Modus-Gerät mit dem Diensttyp „_ewelink._tcp“ zu erkennen, wenn Ihre Anwendung oder Ihr Client eine Verbindung mit dem Internet (WLAN oder Ethernet) herstellt.

So funktioniert der Erkennungsprozess:

1. Suche im LAN nach allen Geräten mit dem Diensttyp _ewelink._tcp über den DNS-PTR-Eintrag.
2. Ermitteln Sie den Hostnamen und den Port des Gerätedienstes durch Analyse des DNS-SRV-Eintrags des Geräts. (Der Standardport ist 8081.)
3. Holen Sie sich die IP-Adresse des Geräts über den DNS-A-Eintrag oder auf andere Weise.
4. Erhalten Sie die Informationen zu „Geräte-ID“, „Diensttyp“, „Version der Geräte-API-Schnittstelle“ und „Geräteinformationen“, indem Sie den DNS-TXT-Eintrag des Geräts analysieren.

Notiz:

• Wenn der „Gerätetyp“ des Gerätedienstes nicht mit dem „Gerätetyp“ Ihrer Anwendung oder Ihres Clients übereinstimmt oder die Version der Geräte-API-Schnittstelle des Gerätedienstes höher ist als die Ihrer Anwendung oder Ihres Clients, sollte die Anwendung oder der Client die „Geräteinformationen“ nicht analysieren und die Geräte-API-Schnittstelle aufrufen, sondern den Benutzern den genauen Grund nennen, warum das Gerät nicht über LAN gesteuert werden kann, und vorschlagen, die Anwendung oder den Client zu aktualisieren.

• Die Anwendung oder der Client erhält die IP-Adresse des Geräts über den DNS-A-Eintrag, wenn die API-Schnittstelle des Geräts aufgerufen werden soll.

Das Gerät muss den HTTP-Server über den im DNS-SRV-Eintrag angegebenen Port öffnen, bevor es seine Dienste veröffentlicht. Die Veröffentlichung erfolgt über eine HTTP-basierte RESTful-API. Aufgrund der LAN-Sicherheit und der begrenzten Rechenleistung des Geräts wird in diesem Dokument empfohlen, dass das Gerät eine HTTP- statt einer HTTPS-Schnittstelle bereitstellt.

Der Gerätetyp und die API-Schnittstellenversion jedes Produkts werden wie folgt angezeigt:

URL: http://[IP]:[Port]/[Pfad]
Rückgabewertformat: json
Methode: HTTP-Post
RESTful API-Anfragen funktionieren mit der POST-Methode und dem JSON-formatierten Anforderungstext.

 { 
    "deviceid": "100000140e", 
    "data": { 
        "switch": "on" 
       }
}

Die RESTful-API-Antwort funktioniert im 200-OK-HTTP-Antwortcode und im JSON-formatierten Antworttext.

 { 
    "seq": 2, 
    "error": 0, 
    "data": { 
        "signalStrength": -67 
    } 
}

Notiz:

• Aufgrund der Rechenleistung des Geräts sollte das Zeitintervall jeder HTTP-Anforderung nicht weniger als 200 ms betragen.
• Der Standardport: 8081

Referenz

[1] SONOFF-Geräte beziehen sich auf dieser Seite auf BASICR3 , RFR3 , MINI , D1
[2] Multicast-DNS-Protokoll: IETF RFC 6762
[3] DNS‑basiertes Service Discovery-Protokoll: IETF RFC 6763
[4] Zero-Configuration-Networking: Zeroconf
[5] Apple Bonjour Netzwerkerkennung und Konnektivität
[6] Android-Netzwerkdiensterkennung
[7] Wikipedia Zero Configuration Networking
[8] Wie schneidet Zeroconf im Vergleich zu Viiv/DLNA/DHWG/UPnP ab?