Protokół API trybu DIY

Chcesz sterować urządzeniem SONOFF za pomocą własnej aplikacji lub platformy automatyki domowej? Tryb DIY Ci w tym pomoże!

Tryb DIY (zrób to sam) jest przeznaczony dla użytkowników i deweloperów automatyki domowej IoT, którzy chcieliby sterować urządzeniem SONOFF za pośrednictwem istniejącej platformy open source automatyki domowej lub lokalnego klienta HTTP, a nie aplikacji eWeLink. W trybie DIY (zrób to sam), po połączeniu urządzenia z siecią, urządzenie publikuje swoje usługi i funkcje zgodnie ze standardem mDNS/DNS-SD. Przed opublikowaniem usługi urządzenie włącza serwer HTTP na porcie zadeklarowanym w rekordzie DNS SRV. Urządzenie udostępnia funkcje za pośrednictwem interfejsu API RESTful opartego na protokole HTTP. Użytkownicy mogą uzyskać informacje o urządzeniu i sterować nim, wysyłając żądanie API HTTP.

Urządzenia SONOFF ^[1] mogą pracować w trybie eWeLink lub trybie DIY. W trybie eWeLink urządzenie jest połączone z chmurą eWeLink i sterowane za pomocą aplikacji eWeLink, natomiast w trybie DIY urządzenie publikuje swoją usługę możliwości i jest sterowane za pomocą żądania HTTP POST.

Kroki przejścia do trybu DIY i połączenia z istniejącą siecią Wi-Fi:

1. Wejście w tryb zgodnego parowania (AP) poprzez długie naciśnięcie przycisku parowania przez 5 sekund po włączeniu zasilania
2. Łączenie się z punktem dostępowym o nazwie ITEAD-XXXXXXXXXX z domyślnym hasłem 12345678 za pomocą telefonu komórkowego lub komputera
3. Przeglądarka odwiedza http://10.10.7.1/
4. Wprowadzanie istniejącego identyfikatora SSID i hasła sieci WiFi
5. Udało się pomyślnie przejść do trybu DIY po połączeniu z określoną siecią WiFi.

Przykład wejścia w tryb DIY wtyczki jednokanałowej DIY (BASICR3, RFR3, MINI/MINIR2, MINIR3):

1. Włącz zasilanie;
2. Naciśnij i przytrzymaj przycisk przez 5 sekund, aby przejść do trybu zgodnego parowania (AP)
   Wskazówki dla użytkownika: Jeśli urządzenie zostało sparowane z aplikacją eWeLink, konieczne jest zresetowanie urządzenia poprzez długie naciśnięcie przycisku parowania przez 5 sekund, a następnie naciśnięcie go przez kolejne 5 sekund w celu przejścia do trybu zgodnego parowania (AP).
3. Wskaźnik LED będzie migać nieprzerwanie
4. Z poziomu ustawień WiFi telefonu komórkowego lub komputera zostanie znaleziony punkt dostępu urządzenia o nazwie ITEAD-XXXXXXXXXXXX , połącz się z nim, używając domyślnego hasła 12345678
5. Otwórz przeglądarkę i uzyskaj dostęp do http://10.10.7.1/
6. Następnie wpisz identyfikator SSID i hasło sieci Wi-Fi, z którą urządzenie będzie się łączyć
7. Udało się, urządzenie jest teraz w trybie DIY.

Przykład przejścia ściemniacza jednokanałowego DIY (D1) w tryb DIY:

1. Włącz zasilanie;
2. Naciśnij i przytrzymaj przycisk parowania na pilocie RM433 przez 5 sekund, aby przejść do trybu zgodnego parowania (AP).
   Wskazówki dla użytkownika: Jeśli urządzenie zostało sparowane z aplikacją eWeLink, konieczne jest jego zresetowanie. W tym celu należy nacisnąć i przytrzymać przycisk parowania na pilocie RM433 przez 5 sekund, a następnie nacisnąć go przez kolejne 5 sekund, aby przejść do trybu zgodnego parowania (AP).
3. Ściemnialna lampa podłączona do D1 będzie migać nieprzerwanie (szybko przeskakując ze 100% do 1%, z 1% do 100% …)

Kroki 4–7 są takie same jak w przykładzie wtyczki jednokanałowej DIY.

Przykład przejścia inteligentnego miernika energii (SPM-Main) w tryb DIY:

1. Włącz zasilanie;
2. Naciśnij i przytrzymaj przycisk na urządzeniu SPM-Main przez 5 sekund, aby przejść do trybu parowania Bluetooth.
   Wskazówki dla użytkownika: Jeśli urządzenie zostało sparowane z aplikacją eWeLink, konieczne jest jego zresetowanie. W tym celu należy nacisnąć i przytrzymać przycisk parowania przez 5 sekund, aby przejść do trybu parowania Bluetooth.
3. Wskaźnik LED będzie szybko migać.
4. Podłącz SPM-Main do routera za pomocą kabla Ethernet. Możesz to zrobić jedną z poniższych metod.
5. Wpisz adres IP SPM-Main w przeglądarce na swoim komputerze i uzyskaj dostęp.
6. Następnie wprowadź identyfikator SSID i hasło sieci WiFi.
7. Udało się. Urządzenie jest teraz w trybie DIY.

Przykład inteligentnej żarówki LED (B02-BL-A60, B05-BL-A19, B05-BL-A60) wchodzącej w tryb DIY:

1. Włącz zasilanie;
2. Po włączeniu światła naciskaj włącznik światła 5 razy, powtarzając czynność co 1 sekundę (Wyłącz-Włącz-Wyłącz-Włącz-Wyłącz-Włącz-Wyłącz-Włącz).
3. „Szybkie mignięcie” oznacza, że urządzenie wchodzi w tryb zgodnego parowania (AP).
4. Z poziomu ustawień WiFi telefonu komórkowego lub komputera zostanie znaleziony punkt dostępu urządzenia o nazwie ITEAD-XXXXXXXXXXXX , połącz się z nim, używając domyślnego hasła 12345678
5. Otwórz przeglądarkę i uzyskaj dostęp do http://10.10.7.1/
6. Następnie wpisz identyfikator SSID i hasło sieci Wi-Fi, z którą urządzenie będzie się łączyć
7. Udało się, urządzenie jest teraz w trybie DIY.

Notatka:

• Ustawienia użytkownika zostaną wyczyszczone po zmianie trybu pracy z jednego na inny.
• Router WiFi lub punkt dostępowy powinien działać w paśmie 2,4 GHz i obsługiwać usługę mDNS.
• Znaczenie migania diody LED
  Szybkie pojedyncze mignięcie – urządzenie nie łączy się z siecią WiFi;
  Szybkie podwójne mruganie – urządzenie nawiązało połączenie z siecią WiFi, zostało wykryte przez mDNS i odpowiedziało na żądanie z sieci LAN.
• Gdy urządzenie jest już w trybie DIY, strona konfiguracji WiFi http://10.10.7.1/ nie jest dostępna.
• Jeśli wprowadzono błędny identyfikator SSID lub hasło sieci Wi-Fi, urządzenie nie będzie mogło nawiązać połączenia z określoną siecią Wi-Fi. Po upływie 20 sekund urządzenie przestanie łączyć się z siecią Wi-Fi. Spróbuj ponownie, wykonując przykładowe kroki 1-7.
• Oficjalna aktualizacja oprogramowania sprzętowego jest dostępna wyłącznie w aplikacji eWeLink.
• Dostęp do protokołu v1.4 można uzyskać przez https://github.com/itead/Sonoff_Devices_DIY_Tools

Tryb samodzielnego odkrywania sieci LAN implementuje protokół IETF Multicast DNS i protokół DNS‑Based Service Discovery. ^{[2] – [8]}

Urządzenie publikuje własną usługę (tj. możliwości urządzenia) zgodnie ze standardowym protokołem wykrywania mDNS/DNS-SD, gdy jest podłączone do sieci LAN (lokalnej sieci komputerowej).

Definicja pól wygląda następująco:

Notatka dotycząca rekordu TXT :

1. Rekord TXT musi zawierać poniższe ciągi:
   „ txtvers = 1”, „ id = [ID urządzenia]”, „ type = [typ urządzenia]”, „ apivers = [wersja interfejsu API urządzenia]”, „ seq = [numer seryjny rekordu TXT]”, „ data1 = [informacje o urządzeniu]”;
2. Opcjonalne ciągi znaków:
   „ data2 =[informacje o urządzeniu]”, „ data3 =[informacje o urządzeniu]”, „ data4 =[informacje o urządzeniu]”
3. „ seq =[numer sekwencji rekordu TXT]” wskazuje kolejność aktualizacji rekordów TXT (kolejność aktualizacji statusu urządzenia). Zaleca się, aby była to dodatnia liczba całkowita, która zwiększa się od 1 (resetuje się do 1 po ponownym uruchomieniu urządzenia);
4. Jeśli informacje o urządzeniu są dłuższe niż 249 bajtów, pierwsze 249 bajtów musi zostać zapisane w data1, a pozostałe bajty, podzielone przez długość 249, są przechowywane w data2, data3 i data4. Pełny format informacji o urządzeniu to obiekt JSON.

Przykład rekordu tekstowego mDNS BASICR3, RFR3, MINI:
data1= {“switch”:”on”,”startup”:”stay”,”pulse”:”on”,”pulseWidth”:2000,”rssi”:-67,”fwVersion”:”3.5.0”}

Przykład rekordu tekstowego mDNS D1 (Dimmer):
data1= {“przełącznik”: “włączony”,”tryb”: 0,”jasność”: 50,”jasnośćMin”: 0,”jasnośćMax”: 255,”uruchomienie”: “włączony”,”rssi”:-67,”wersja fw”:”3.5.0”}

Przykład głównego rekordu mDNS w formacie txt dla SPM:
data1= {“subDevId”: “123456”,”przełączniki”: [{“przełącznik”: “włączony”,”wyjście”: 0},{“przełącznik”: “włączony”,”wyjście”: 1},{“przełącznik”: “włączony”,”wyjście”: 2},{“przełącznik”: “włączony”,”wyjście”: 3}]}

Przykład rekordu tekstowego mDNS MINIR3:
data1= {“przełączniki”:[{“przełącznik”:”włączony”,”gniazdo”:0},{“przełącznik”:”wyłączony”,”gniazdo”:1},{“przełącznik”:”wyłączony”,”gniazdo”:2},{“przełącznik”:”wyłączony”,”gniazdo”:3}],”sledOnline”:”włączony”}

Przykład rekordu tekstowego B02-BL-A60, B05-BL-A19, B05-BL-A60:
data1= {“switch”: “off”,”startup”: “off”,”pulse”: “off”,”pulseWidth”: 500,”ssid”: “eWeLink”,”otaUnlock”: false,”fwVersion”: “3.5.0”,”deviceid”: “100000140e”,”bssid”: “ec:17:2f:3d:15:e”,”signalStrength”: -25}

Za każdym razem, gdy zmienia się zawartość inna niż sekwencja, np. modyfikowana jest nazwa instancji usługi, aktualizowane są informacje o urządzeniu itd., urządzenie musi dokonać wielokrotnego rozsyłania odpowiedniego rekordu DNS (wraz ze zwiększoną sekwencją) zgodnie ze standardem mDNS/DNS-SD.

Proces wyszukiwania musi przebiegać zgodnie z protokołem mDNS/DNS-SD Discovery, aby wykryć urządzenie Sonoff DIY Mode z typem usługi „_ewelink._tcp”, gdy Twoja aplikacja lub klient łączy się z Internetem (WiFi lub Ethernet).

Oto proces odkrywania:

1. Wyszukaj w sieci LAN wszystkie urządzenia z typem usługi _ewelink._tcp poprzez rekord DNS PTR.
2. Uzyskaj nazwę hosta i port usługi urządzenia, analizując rekord DNS SRV urządzenia. (Domyślny port to 8081).
3. Uzyskaj adres IP urządzenia za pomocą rekordu A DNS lub w inny sposób.
4. Uzyskaj informacje o „identyfikatorze urządzenia”, „typie usługi”, „wersji interfejsu API urządzenia” i „informacjach o urządzeniu” poprzez analizę rekordu DNS TXT urządzenia.

Notatka:

• Jeśli „typ urządzenia” usługi urządzenia nie jest zgodny z „typem urządzenia” aplikacji lub klienta albo wersja interfejsu API urządzenia usługi urządzenia jest wyższa niż wersja aplikacji lub klienta, aplikacja lub klient nie powinien analizować „informacji o urządzeniu” i wywoływać interfejsu API urządzenia, lecz wyświetlić użytkownikowi konkretny powód, dla którego urządzenie nie może być sterowane za pośrednictwem sieci LAN, i zasugerować uaktualnienie aplikacji lub klienta.

• Aplikacja lub klient uzyskuje adres IP urządzenia za pośrednictwem rekordu DNS A w momencie, gdy ma zostać wywołany interfejs API urządzenia.

Urządzenie musi otworzyć serwer HTTP na porcie zadeklarowanym w rekordzie DNS SRV, zanim opublikuje swoje usługi; urządzenie publikuje swoje możliwości za pośrednictwem interfejsu API RESTful opartego na protokole HTTP. Ze względu na bezpieczeństwo sieci LAN i ograniczoną moc obliczeniową urządzenia, niniejszy dokument zaleca, aby urządzenie udostępniało interfejs HTTP zamiast HTTPS.

Poniżej przedstawiono typ urządzenia i wersję interfejsu API każdego produktu:

URL: http://[ip]:[port]/[ścieżka]
Format wartości zwracanej: json
Metoda: HTTP post
Żądanie RESTful API działa w metodzie POST i treści żądania w formacie JSON.

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

Odpowiedź RESTful API działa w 200-procentowym kodzie odpowiedzi HTTP i treści odpowiedzi w formacie JSON.

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

Notatka:

• Biorąc pod uwagę możliwości obliczeniowe urządzenia, odstęp czasu między każdym żądaniem HTTP nie powinien być krótszy niż 200 ms.
• Domyślny port: 8081

Odniesienie

[1] Urządzenia SONOFF odnoszą się na tej stronie do BASICR3 , RFR3 , MINI , D1
[2] Protokół DNS multicast: IETF RFC 6762
[3] Protokół wykrywania usług oparty na systemie DNS: IETF RFC 6763
[4] Sieć o zerowej konfiguracji: Zeroconf
[5] Odkrywanie sieci i łączność Apple Bonjour
[6] Odkrywanie usług sieciowych Androida
[7] Wikipedia Sieć o zerowej konfiguracji
[8] Jak Zeroconf wypada w porównaniu z Viiv/DLNA/DHWG/UPnP