Protocollo API MODALITÀ FAI DA TE

Vuoi controllare il dispositivo SONOFF tramite la tua app o piattaforma di domotica? La modalità fai da te ti aiuta!

La modalità "fai da te" è progettata per utenti e sviluppatori di domotica IoT che desiderano controllare il dispositivo SONOFF tramite una piattaforma open source di domotica esistente o un client HTTP locale, anziché tramite l'app eWeLink. In modalità "fai da te", quando il dispositivo è connesso alla rete, pubblicherà i suoi servizi e funzionalità secondo lo standard mDNS/DNS-SD. Prima di pubblicare il servizio, il dispositivo ha abilitato il server HTTP sulla porta dichiarata dal record DNS SRV. Il dispositivo espone le funzionalità tramite un'API RESTful basata su HTTP. Gli utenti possono ottenere informazioni sul dispositivo e controllarlo inviando una richiesta API HTTP.

I dispositivi SONOFF ^[1] possono funzionare sia in modalità eWeLink che in modalità fai da te. In modalità eWeLink, il dispositivo è connesso al cloud eWeLink e controllato dall'APP eWeLink, mentre in modalità fai da te, il dispositivo pubblica il suo servizio di capacità ed è controllato dalla richiesta HTTP Post.

I passaggi per entrare in modalità fai da te e connettersi a una rete WiFi esistente sono:

1. Entrare nella modalità di associazione compatibile (AP) premendo a lungo il pulsante di associazione per 5 secondi dopo l'accensione
2. Collegamento del punto di accesso denominato ITEAD-XXXXXXXXXX con password predefinita 12345678 tramite telefono cellulare o PC
3. Il browser visita http://10.10.7.1/
4. Inserimento dell'SSID e della password della rete WiFi esistente
5. Accesso alla modalità fai da te riuscito con una rete WiFi specifica connessa.

Esempio per il plug fai da te a canale singolo (BASICR3, RFR3, MINI/MINIR2, MINIR3) che entra in modalità fai da te:

1. Accensione;
2. Premere a lungo il pulsante per 5 secondi per accedere alla modalità di associazione compatibile (AP)
   Suggerimenti per l'utente: se il dispositivo è stato associato all'APP eWeLink, è necessario reimpostare il dispositivo premendo a lungo il pulsante di associazione per 5 secondi, quindi premere per altri 5 secondi per accedere alla modalità di associazione compatibile (AP)
3. L'indicatore LED lampeggerà continuamente
4. Dalle impostazioni WiFi del telefono cellulare o del PC, verrà trovato un punto di accesso del dispositivo denominato ITEAD-XXXXXXXXXX , collegarlo con la password predefinita 12345678
5. Aprire il browser e accedere a http://10.10.7.1/
6. Successivamente, inserisci l'SSID WiFi e la password a cui il dispositivo si sarebbe connesso
7. Riuscito, ora il dispositivo è in modalità fai da te.

Esempio per il dimmer fai da te a canale singolo (D1) che entra in modalità fai da te:

1. Accensione;
2. Premere a lungo il pulsante di associazione del telecomando RM433 per 5 secondi per accedere alla modalità di associazione compatibile (AP)
   Suggerimenti per l'utente: se il dispositivo è stato associato all'APP eWeLink, è necessario reimpostare il dispositivo premendo a lungo il pulsante di associazione del telecomando RM433 per 5 secondi, quindi premere per altri 5 secondi per accedere alla modalità di associazione compatibile (AP)
3. La luce dimmerabile collegata a D1 lampeggerà continuamente (saltando rapidamente dal 100% all'1%, dall'1% al 100%...)

I passaggi da 4 a 7 sono gli stessi dell'esempio del plug fai da te a canale singolo.

Esempio per il contatore di energia intelligente (SPM-Main) che entra in modalità fai da te:

1. Accensione;
2. Premere a lungo il pulsante su SPM-Main per 5 secondi per accedere alla modalità di associazione Bluetooth.
   Suggerimenti per l'utente: se il dispositivo è stato associato all'app eWeLink, è necessario reimpostarlo tenendo premuto il pulsante di associazione per 5 secondi per accedere alla modalità di associazione Bluetooth.
3. L'indicatore LED lampeggerà velocemente.
4. Collega SPM-Main al router tramite un cavo Ethernet. Per effettuare la connessione, è disponibile uno dei seguenti metodi.
5. Digita l'indirizzo IP di SPM-Main nel browser del tuo computer e accedi.
6. Successivamente, inserisci l'SSID e la password del Wi-Fi.
7. Riuscito. Ora il dispositivo è in modalità fai da te.

Esempio per la lampadina LED intelligente (B02-BL-A60, B05-BL-A19, B05-BL-A60) che entra in modalità fai da te:

1. Accensione;
2. Quando la luce è accesa, premere ripetutamente l'interruttore della luce 5 volte a intervalli di 1 secondo (Off-ON-Off-ON-Off-ON-Off-ON-Off-ON).
3. Il "lampeggio rapido" indica che il dispositivo entra nella modalità di associazione compatibile (AP).
4. Dalle impostazioni WiFi del telefono cellulare o del PC, verrà trovato un punto di accesso del dispositivo denominato ITEAD-XXXXXXXXXX , collegarlo con la password predefinita 12345678
5. Aprire il browser e accedere a http://10.10.7.1/
6. Successivamente, inserisci l'SSID WiFi e la password a cui il dispositivo si sarebbe connesso
7. Riuscito, ora il dispositivo è in modalità fai da te.

Nota:

• Le impostazioni utente verranno cancellate quando si cambia la modalità operativa.
• Il router o l'AP WiFi deve funzionare a 2,4 GHz e supportare il servizio mDNS.
• Significato del lampeggiamento dei LED
  Lampeggio singolo veloce: il dispositivo non si connette alla rete WiFi;
  Doppio lampeggio veloce: il dispositivo si connette correttamente al Wi-Fi ed è in grado di essere rilevato tramite mDNS e di rispondere alla richiesta dalla rete LAN.
• Una volta che il dispositivo è già in modalità fai da te, la pagina di configurazione WiFi http://10.10.7.1/ non è accessibile.
• Se è stato inserito un SSID o una password Wi-Fi errati, il dispositivo non riuscirà a connettersi alla rete Wi-Fi specifica; con un meccanismo di timeout di 20 secondi, il dispositivo smetterà di connettersi alla rete Wi-Fi. Riprovare con i passaggi di esempio da 1 a 7.
• L'aggiornamento ufficiale del firmware è disponibile solo nell'APP eWeLink.
• È possibile accedere al protocollo v1.4 tramite https://github.com/itead/Sonoff_Devices_DIY_Tools

La scoperta LAN in modalità fai da te implementa il protocollo DNS multicast IETF e il protocollo di scoperta del servizio basato su DNS. ^{[2] – [8]}

Il dispositivo pubblica il proprio servizio (ovvero la capacità del dispositivo) in base al protocollo di rilevamento standard mDNS/DNS-SD quando il dispositivo è connesso alla LAN (rete locale).

La definizione dei campi è la seguente:

Nota sul record TXT :

1. Il record TXT deve contenere le seguenti stringhe:
   “ txtvers =1”, “ id =[ID dispositivo]”, “ type =[tipo di dispositivo]”, “ apivers =[versione dell'interfaccia API del dispositivo]”, “ seq =[numero di serie del record TXT]”, “ data1 =[informazioni sul dispositivo]”;
2. Stringhe facoltative:
   “ data2 =[informazioni sul dispositivo]”, “ data3 =[informazioni sul dispositivo]”, “ data4 =[informazioni sul dispositivo]”
3. " seq =[numero di sequenza del record TXT]" indica l'ordine in cui vengono aggiornati i record TXT (l'ordine in cui viene aggiornato lo stato del dispositivo). Si consiglia di utilizzare un numero intero positivo che incrementa da 1 (reimpostato a 1 al riavvio del dispositivo);
4. Quando le informazioni sul dispositivo sono più lunghe di 249 byte, i primi 249 byte devono essere memorizzati in data1, mentre i byte rimanenti vengono divisi per la lunghezza 249 e memorizzati in data2, data3 e data4. Il formato completo delle informazioni sul dispositivo è un oggetto JSON.

Per esempio di record txt mDNS BASICR3, RFR3, MINI:
data1= {“switch”:”on”,”startup”:”stay”,”pulse”:”on”,”pulseWidth”:2000,”rssi”:-67,”fwVersion”:”3.5.0”}

Per un esempio di record txt mDNS D1 (Dimmer):
data1= {“switch”: “on”,”mode”: 0,”brightness”: 50,”brightMin”:0,”brightMax”:255,”startup”: “on”,”rssi”:-67,”fwVersion”:”3.5.0”}

Per un esempio di record txt mDNS SPM-Main:
data1= {“subDevId”: “123456”,”switches”: [{“switch”: “on”,”outlet”: 0},{“switch”: “on”,”outlet”: 1},{“switch”: “on”,”outlet”: 2},{“switch”: “on”,”outlet”: 3}]}

Per un esempio di record txt mDNS MINIR3:
data1= {“interruttori”:[{“interruttore”:”acceso”,”presa”:0},{“interruttore”:”spento”,”presa”:1},{“interruttore”:”spento”,”presa”:2},{“interruttore”:”spento”,”presa”:3}],”sledOnline”:”acceso”}

Per esempio di record di testo 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}

Ogni volta che cambia un contenuto diverso dalla sequenza, come ad esempio il nome dell'istanza del servizio, le informazioni del dispositivo vengono aggiornate, ecc., il dispositivo deve trasmettere in multicast il record DNS corrispondente (inclusa la sequenza incrementata) secondo lo standard mDNS/DNS-SD.

Il processo di rilevamento deve seguire il protocollo di rilevamento mDNS/DNS-SD per rilevare il dispositivo Sonoff DIY Mode con tipo di servizio "_ewelink._tcp" quando l'applicazione o il client si connettono a Internet (WiFi o Ethernet);

Ecco il processo di scoperta:

1. Cercare nella LAN tutti i dispositivi con il tipo di servizio _ewelink._tcp tramite il record DNS PTR.
2. Ottieni il nome host e la porta del servizio dispositivo analizzando il record DNS SRV del dispositivo. (La porta predefinita è 8081)
3. Ottieni l'indirizzo IP del dispositivo tramite il record DNS A o con altri mezzi.
4. Ottieni le informazioni su "ID dispositivo", "Tipo di servizio", "Versione dell'interfaccia API del dispositivo" e "Informazioni sul dispositivo" analizzando il record TXT DNS del dispositivo.

Nota:

• Quando il "tipo di dispositivo" del servizio dispositivo non corrisponde al "tipo di dispositivo" dell'applicazione o del client, oppure la versione dell'interfaccia API del servizio dispositivo è superiore a quella dell'applicazione o del client, l'applicazione o il client non devono analizzare le "informazioni sul dispositivo" e chiamare l'interfaccia API del dispositivo, ma devono chiedere agli utenti il motivo specifico per cui il dispositivo non può essere controllato tramite LAN e suggerire di aggiornare l'applicazione o il client.

• L'applicazione o il client ottengono l'indirizzo IP del dispositivo tramite il record DNS A quando l'interfaccia API del dispositivo sta per essere chiamata.

Il dispositivo deve aprire il server HTTP sulla porta dichiarata dal record DNS SRV prima di pubblicare i propri servizi; il dispositivo pubblica le funzionalità tramite un'API RESTful basata su HTTP. A causa della sicurezza della LAN e della limitata potenza di calcolo del dispositivo, questo documento raccomanda che il dispositivo fornisca un'interfaccia HTTP anziché HTTPS.

Di seguito sono riportati il tipo di dispositivo e la versione dell'interfaccia API di ciascun prodotto:

URL: http://[ip]:[porta]/[percorso]
Formato del valore restituito: json
Metodo: post HTTP
La richiesta API RESTful funziona con il metodo POST e con il corpo della richiesta formattato JSON.

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

La risposta API RESTful funziona con codice di risposta HTTP 200 OK e corpo di risposta in formato JSON.

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

Nota:

• Data la capacità di elaborazione del dispositivo, l'intervallo di tempo di ogni richiesta HTTP non deve essere inferiore a 200 ms.
• Porta predefinita: 8081

Riferimento

[1] In questa pagina i dispositivi SONOFF fanno riferimento a BASICR3 , RFR3 , MINI , D1
[2] Protocollo DNS multicast: IETF RFC 6762
[3] Protocollo di rilevamento dei servizi basato su DNS: IETF RFC 6763
[4] Rete a configurazione zero: Zeroconf
[5] Apple Bonjour Network Discovery e connettività
[6] Rilevamento del servizio di rete Android
[7] Rete di configurazione zero di Wikipedia
[8] Come si confronta Zeroconf con Viiv/DLNA/DHWG/UPnP