Riprogrammare un ITEAD Sonoff usando la modalità DIY via OTA

Abstract

Ogni dispositivo elettronico contiene a grandi linee una piccola porzione software, chiamata firmware, che ne determina funzioni e comportamento. La nostra automobile è dotata di diversi firmware; ne possiede uno la lavatrice, il nostro telecomando, persino una radiosveglia è dotata di un proprio firmware.

I dispositivi basati su SOC ESP8266 (un processore dotato di Wi-Fi piuttosto in voga per il basso costo, le limitate dimensioni e la grande versatilità) non sono da meno: tutti montano un proprio firmware, solitamente scritto e compilato dal produttore. Un classico esempio viene dai dispositivi della linea ITEAD Sonoff “Smart Home” i quali, prevalentemente, montano tale processore.

Usando una similitudine, riprogrammare (o flashare) il firmware di un dispositivo è come sovrascrivere per intero una videocassetta VHS. Bene: i dispositivi che montano l’ESP8266 si prestano facilmente a tale riprogrammazione, la quale, per lo più, viene effettuata allo scopo di dotare i componenti di funzionalità aggiuntive (o comunque diverse) da quelle di fabbrica.

È il caso di firmware alternativi come il Tasmota o l’ESPHome, firmware gratuiti scritti per dispositivi basati su ESP8266 (come i Sonoff, gli Shelly e molti altri): vengono implementati per “liberare” i dispositivi dal firmware di fabbrica e implementare, appunto, molte funzionalità aggiuntive.

La procedura, solitamente, è quella che prevede di collegarsi fisicamente al componente per provvedere alla riprogrammazione del firmware; nel 2019, però, ITEAD ha messo a disposizione degli utenti una modalità definita DIY (do-it-yourself) la quale consente di riprogrammare alcuni componenti compatibili (per esempio i Sonoff Basic R3, Sonoff Mini ecc.) senza il bisogno di connessioni fisiche.

La procedura è semplice (e adatta a tutti) qualora si utilizzi un computer di appoggio basato su Windows, mentre è più complessa e ostica per chi possegga un Mac o una macchina Linux. In alternativa a questa procedura, rimane la buona e vecchia procedura tramite connessione fisica.

Si parte

1. Scelta Firmware
2. App “eWeLink”
3. Modalità DIY
   1. Con firmware <3.5
   2. Con firmware ≥ 3.5
4. Riprogrammazione
   1. Su Windows
   2. Su macOS & Linux
      1. Con firmware <3.5
      2. Con firmware ≥ 3.5
5. Precisazione per il firmware Tasmota
6. Conclusione

1. Scelta Firmware

Quale firmware utilizzare?

La questione è ampia e certamente non oggetto della presente guida. Ciò che è importante sapere è che al fine di riprogrammare il Sonoff in questione è necessario avere a disposizione il file .bin (quindi il compilato) del firmware scelto.

Solitamente i firmware più utilizzati sono ESPHome e Tasmota.
Utilizzando il firmware precompilato Tasmota (tra i più adottati – qui la pagina dedicata alla declinazione DIY) è necessario usare il file tasmota-lite.bin. Non usare – per nessuna ragione- il tasmota.bin o altri. 

2. App “eWeLink”

Primo passo è quello di collegare il componente all’app mobile eWeLink (per iOS e Android) allo scopo, unico, di aggiornare il firmware. Per ottenere il paring tra l’app e il componente è possibile far riferimento alla guida del produttore oppure al seguente video (il modello nelle immagini è il Sonoff Basic R2, ma la procedura è comunque sostanzialmente la stessa anche con i modelli nuovi).

Lo scopo è quello di aggiornare il firmware di fabbrica del componente. Per attuare la presente guida, infatti, è strettamente necessario che il componente disponga di una versione di firmware di base uguale o superiore alla 3.1. Una volta collegato a eWeLink, cliccare nelle impostazioni del componente e verificare e se possibile aggiornare il firmware.

Dopo l’aggiornamento, il nostro consiglio è quello di effettuare il backup del firmware di fabbrica, utile un domani si volesse tornare indietro rispetto alla scelta fatta di riprogrammarlo. Per effettuare questa pratica è però necessario un adattatore USB/TTL (che un po’ vanifica il senso di questa guida, ma tant’è). La procedura di backup, nel dettaglio, è spiegata in quest’altra guida ad hoc.

3. Modalità DIY

3.1 Con firmware < 3.5

I dispositivi Sonoff che supportino la modalità DIY sono dotati, sulla board, di due contatti che, quando cortocircuitati, attivano per l’appunto la modalità DIY che consente la riprogrammazione OTA (Over-The-Air, ovvero senza connessione fisica).

Per farlo, è sufficiente aprire il componente, identificare i contatti (sono identificati da una piazzola etichettata “OTA“) e cortocircuitarli tra loro tramite il jumper in dotazione.

Dopo aver cortocircuitato i due contatti, alimentare l’unità.

A questo punto sarà necessario che nell’ambiente sia presente una rete Wi-Fi con un nome (SSID) e una password ben specifici. Queste coordinate, infatti, sono già note al componente (perché precedentemente configurato tramite app eWeLink) che, quando acceso in modalità DIY, prova ad accedervi – sempre che sia in grado di trovare tale rete. È altresì necessario che il computer di appoggio (tramite e grazie il quale effettueremo la riprogrammazione) entri sulla medesima rete.

Per far sì che esista tale rete sono possibili più approcci; ne elencheremo qualcuno:

• utilizzare il computer di appoggio (purché sia dotato di antenna Wi-Fi) come Access Point;
• utilizzare lo smartphone/tablet come Access Point, purché il computer riesca poi a collegarsi a tale rete:
  • o direttamente tramite la propria antenna Wi-Fi;
  • o tramite un dispositivo che funga da bridge, ovvero che si colleghi alla rete esposta dallo smartphone/tablet e, tramite una sua porta ethernet, permetta al computer di collegarsi alla rete via cavo.

L’approccio più semplice è ovviamente il primo: permette di creare la rete al quale connettere il Sonoff e consente al computer di esservi direttamente collegato (in quanto è lui stesso a definirlo).

Per realizzare la rete che ci serve si faccia riferimento a questa guida (via computer o smartphone/tablet).

Tale rete deve necessariamente possedere le seguenti caratteristiche:

• SSID: sonoffDiy (attenzione alle maiuscole)
• password: 20170618sn

Una volta definita la rete, accendere il componente Sonoff e verificare (in base al computer in uso) che sia tra i dispositivi collegati alla rete.

3.2 Con firmware ≥ 3.5

In presenza di firmware superiore alla 3.5, i passaggi per accedere alla modalità DIY e connettersi alla propria rete WiFi differiscono sostanzialmente dall’altra procedura.

La procedura da effettuare è la seguente:

• una volta alimentata l’unità, premere per 5 secondi il pulsante di pairing (il LED lampeggerà continuamente) per resettarla (visto che il device è stato già associato all’app eWeLink per l’aggiornamento firmware, per resettare il device è necessario premere il tastino per 5 secondi e poi premere per altri 5 secondi in modo tale da farlo entrare in AP Mode);
• collegarsi all’access point denominato ITEAD-XXXXXXXX con la password predefinita 12345678;
• collegarsi tramite browser all’indirizzo http://10.10.7.1;
• inserire il SSID e password d’accesso della propria Wi-Fi (da qui in poi l’unità entrerà in modalità DIY, pertanto la pagina di configurazione presso http://10.10.7.1 non sarà più accessibile).

4. Riprogrammazione

4.1 Su Windows

La procedura su Windows è la più semplice. È infatti sufficiente scaricare il Sonoff DIY Tool da GitHub ed eseguirlo.
Una volta in esecuzione, il tool dovrebbe rilevare il Sonoff connesso alla stessa rete del computer; selezionare “Firmware Flash” e selezionare il file .bin del proprio firmware.Selezionare dunque il componente dopodiché cliccare su “OK“. La riprogrammazione si avvierà fino a completarsi.

Saltare infine alla conclusione della procedura.

4.2 Su macOS e Linux

Su questi due sistemi operativi la procedura, come anticipato nell’abstract, è più complessa.

In primis è necessario che il computer possegga il tool curl e che siano attivi i servizi di network discovery (eg. mDNS per macOS o avahi-browse per Linux); in secondo luogo è necessario che sulla medesima rete dove siano attestati il computer e il dispositivo Sonoff sia presente un server web (no SimpleHTTPServer e affini). Quest’ultimo elemento è necessario per “appoggiarvi” il firmware da utilizzare per la riprogrammazione.

Per avviare la procedura è necessario, in primis, scoprire l’ID del dispositivo da riprogrammare. Per farlo è necessario eseguire un comando specifico per il proprio sistema operativo: nell’esempio che segue, ipotizziamo che l’ID sia 1000988699, giusto per capire dove, nel log, andare a guardare.

SU MACOS

dns-sd -B _ewelink._tcp

log di risposta d’esempio:

Browsing for _ewelink._tcp  
DATE: ---Mon 12 Aug 2019---  
20:19:31.956  ...STARTING...  
Timestamp     A/R    Flags  if Domain               Service Type         Instance Name  
20:19:31.957  Add        2   5 local.               _ewelink._tcp.       eWeLink_1000988699

SU LINUX

avahi-browse -t _ewelink._tcp --resolve

log di risposta d’esempio:

+ wlp3s0 IPv4 eWeLink_1000988699 _ewelink._tcp local
= wlp3s0 IPv4 eWeLink_1000988699 _ewelink._tcp local hostname = [eWeLink_1000988699.local] address = [192.168.1.109] port = [8081] txt = ["data1={"switch":"off","startup":"off","pulse":"off","pulseWidth":500,"rssi":-47}" "seq=1" "apivers=1" "type=diy_plug" "id=1000988699" "txtvers=1"]

4.2.1 Configurazione webserver locale

A questo punto sarà necessario creare un proprio server web per poter permettere successivamente al Sonoff di poter scaricare il firmware (non si potrà specificare direttamente la URL dell’host ufficiale Tasmota, ma dovrà necessariamente trovarsi presso il server locale che creeremo temporaneamente).

Scarichiamo dunque il l firmware e posizionandolo in una directory sul computer che si vuole utilizzare come server web (es. /tmp/share).

Di seguito un esempio di configurazione del blocco server per NGINX:

worker_processes  1;
events {
    worker_connections  1024;
}
http {
    include         mime.types;
    default_type    application/octet-stream;
    sendfile        on;
    keepalive_timeout   65;
    server {
        root /tmp/share;
        location / {    
            autoindex   on;
        }
    }
}

ovviamente andrà sostituita la directory /tmp/share con la directory su cui sarà presente il firmware (es. tasmota-lite.bin)

Una volta avviato, testare il funzionamento del server tramite browser, puntando l”indirizzo IP del computer che ospita il server, per esempio:

http://192.168.1.2

Ipotizzando che il server funzioni e che il file del firmware precompilato sia quello del firmware Tasmota (ovvero tasmota-lite.bin), dovremmo ottenere una risposta di questo tipo:

Verifichiamo a questo punto che il server supporti il “Range request header” tramite il comando:

curl -I http://192.168.1.2/tasmota-lite.bin

(ovviamente indirizzo IP e nome file andrà adeguato alla propria situazione operativa).

Il risultato dovrà essere simile al seguente; assicurarsi che “Accept-Ranges” risulti come segue:

HTTP/1.1 200 OK
Server: nginx/1.17.9
Date: Fri, 10 Apr 2020 22:19:39 GMT
Content-Type: application/octet-stream
Content-Length: 477328
Last-Modified: Fri, 10 Apr 2020 21:35:35 GMT
Connection: keep-alive
ETag: "5e90e6a7-74890"
Accept-Ranges: bytes

4.2.2 Flash del firmware

A questo punto possiamo effettuare un primo test che evochi dal componente Sonoff delle info di servizio (comando uguale sia per macOS che Linux).

CON FIRMWARE < 3.5

curl http://deviceIP:8081/zeroconf/info -XPOST --data '{"deviceid":"deviceID","data":{} }'

dove deviceIP è l’IP del componente Sonoff e deviceID è l’ID precedentemente scoperto.

Log di risposta d’esempio:

{"seq":2,"error":0,"data":"{"switch":"off","startup":"off","pulse":"off","pulseWidth":500,"ssid":"sonoffDiy","otaUnlock":false}"}

Se si ottiene questa risposta (o analoga), la comunicazione funziona.

A questo punto è possibile bloccare l’aggiornamento OTA tramite questo comando:

curl http://deviceIP:8081/zeroconf/ota_unlock -XPOST --data '{"deviceid":"deviceID","data":{} }'

Il comando deve generare una riposta come segue:

{"seq":2,"error":0}

Ottenuta questa riposta, finalmente si può provvedere alla riprogrammazione vera e propria tramite il comando:

curl http://deviceIP:8081/zeroconf/ota_flash -XPOST --data '{"deviceid":"deviceID","data":{"downloadUrl": "http://webServer/nomefirmware.bin", "sha256sum": "<SHAsum>"} }'

ATTENZIONE: Ovviamente webServer sarà l’indirizzo del nostro server web locale (IP assegnato dal router, non 127.0.0.1), mentre nomefirmware.bin sarà il nome del nostro firmware da esso ospitato e infine <SHAsum> il valore SHA256 del file nomefirmware.bin.

Quando e se otterrà la seguente risposta:

{"seq":2,"error":0}

la riprogrammazione sarà andata a buon fine.

CON FIRMWARE ≥ 3.5

curl http://deviceIP:8081/zeroconf/info -XPOST --data '{"deviceid":"","data":{} }'

dove deviceIP è l’IP del componente Sonoff.

Log di risposta d’esempio:

{"seq":2,"error":0,"data":"{"switch":"off","startup":"off","pulse":"off","pulseWidth":500,"ssid":"sonoffDiy","otaUnlock":false}"}

Se si ottiene questa risposta (o analoga), la comunicazione funziona.

A questo punto è possibile bloccare l’aggiornamento OTA tramite questo comando:

curl http://deviceIP:8081/zeroconf/ota_unlock -XPOST --data '{"deviceid":"","data":{} }'

Il comando deve generare una riposta come segue:

{"seq":2,"error":0}

Ottenuta questa riposta, finalmente si può provvedere alla riprogrammazione vera e propria tramite il comando:

curl http://deviceIP:8081/zeroconf/ota_flash -XPOST --data '{"deviceid":"","data":{"downloadUrl": "http://webServer/nomefirmware.bin", "sha256sum": "<SHAsum>"} }'

ATTENZIONE: Ovviamente webServer sarà l’indirizzo del nostro server web locale (IP assegnato dal router, non 127.0.0.1), mentre nomefirmware.bin sarà il nome del nostro firmware da esso ospitato e infine <SHAsum> il valore SHA256 del file nomefirmware.bin.

Quando e se otterrà la seguente risposta:

{"seq":2,"error":0}

la riprogrammazione sarà andata a buon fine.

5. Precisazione per il firmware Tastmota

Gli utenti che abbiano deciso di adottare il firmware Tasmota abbiano cura di perfezionare l’installazione del firmware con una configurazione ad hoc.

L’installazione di Tasmota su Sonoff Mini, infatti, causa di base un malfunzionamento (o meglio, un mancato funzionamento) dei contatti S1 e S2 presenti sull’unità e solitamente utilizzati per attestarvi interruttori/pulsanti per il controllo esterno manuale. Per far sì che tutto funzioni correttamente, dopo l’avvenuta riprogrammazione OTA accedere all’interfaccia web di Tasmota e accedere alla voce di menu “Configuration” > “Configure other“.

In alto, sotto la voce “Other parameters” > “Template“, si presenta una buca di testo:

In questa buca di testo viene indicata una stringa in notazione JSON la quale consente di indicare quale sia il “mapping” delle varie componenti logico/fisiche dell’unità. Come spiegato anche sul sito wiki di Tasmota, nel caso del Sonoff Mini è necessario specificare la seguente stringa (al posto della pre-esistente) affinché funzioni tutto correttamente:

{“NAME”:“Sonoff Mini”,“GPIO”:[17,0,0,0,9,0,0,0,21,56,0,0,255],“FLAG”:0,“BASE”:1}

Una volta terminata la modifica, cliccare su “Activate” e poi, in basso, su “Save“. L’unità si riavvierà e funzionerà come deve.

6. Conclusione

Ovviamente il comportamento sarà legato al firmware che si sarà montato: in caso di un Tasmota precompilato sarà sufficiente collegarsi tramite smartphone all’access point Wi-Fi esposto dall’unità appena riprogrammata (il SSID della Wi-Fi esposta sarà “Tasmota-xxxx“): si aprirà l’interfaccia di default di Tasmota presso la quale inserire le coordinate d’accesso alla propria Wi-Fi domestica. Una volta inserite e salvate, il componente si riavvierà ed entrerà automaticamente nella rete domestica. Se invece si sarà provveduto a preconfigurare il proprio file di configurazione e così compilarlo (usando poi il compilato per riprogrammare), il Sonoff Mini entrerà da solo nella propria rete Wi-Fi e sarà possibile cominciare ad utilizzarlo da subito.