Riprogrammare il firmware di ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus) – v2

SCOPI DELLA GUIDA: Flashare il firmware di un coordinator ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus v2) con qualsiasi firmware compatibile Livello di difficoltà: medio/basso CONCETTI AFFRONTATI: Riprogrammazione firmware	COMPONENTI SOFTWARE UTILIZZATE: Silabs Firmware Flasher Universal Silabs Flasher altri tool eventuali DISPOSITIVI FISICI UTILIZZATI: ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus v2) da (ri)programmare un computer di supporto
GUIDA maggiormente DEDICATA A utenti:
NOTE E DISCLAIMER qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato; qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati; tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili; gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione; questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat; se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 1.9

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 mini-firmware.

La “chiavetta USB” meglio nota come ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus v2) è un piccolo ed economico componente che permette, abbinato a uno o più software appropriati, di definire BRIDGE/Gateway utili a realizzare e amministrare reti ZigBee e/o Thread (magari per usarlo con Matter) nella propria domotica personale (e quindi accessori smart basati su questi standard).

Questa guida illustra varie modalità di riprogrammazione tramite un computer di supporto (qualsiasi) e senza la necessità di ulteriori dispostivi di collegamento, se non la porta USB del computer di appoggio stesso.

Ma quando si rende necessaria la riprogrammazione? Dato che il componente può, come spiegato, sopperire a diverse configurazioni e funzioni, va da sé che possa accogliere varie tipologie e versioni di firmware che l’utente, in autonomia, dev’essere in grado di riconoscere e saper applicare.

Diversi tipi di firmware: NCP e RCP

I coordinator ZigBee come Sonoff ZBDongle-E si affidano tipicamente a un tipologia di firmware chiamata “Network Co-Processor“, o “NCP” – che guardacaso è la tipologia di firmware che si trova, di fabbrica, a bordo di questa chiavetta/dongle. Usando firmware NCP, l’applicazione ZigBee e lo stack del protocollo di rete vengono eseguiti sul dongle stesso, gestendo in autonomia la maggior parte degli aspetti tecnici della rete ZigBee. Il BRIDGE/Gateway in uso (eg. ZigBee2MQTT, ZHA o altri) si limita a comunicare col dongle per ricevere/inviare comandi dai/ai dispositivi della rete ZigBee.

I firmware di tipologia “Remote Co-Processor“, o “RCP“, consentono di scaricare completamente applicazione e stack lato applicativo, limitando l’uso del dongle a “semplice” antenna. Questo ha una serie di vantaggi:

• applicazione e stack possono essere aggiornati lato software, senza bisogno di riprogrammazioni firmware;
• maggiori prestazioni;
• possibilità di utilizzare RCP.

Esistono diversi tipi di RCP:

• il firmware “RCP MultiPAN” consente di utilizzare contemporaneamente, nel caso di ZBDongle-E, sia le funzioni ZigBee che Thread (per l’uso “semplice” o tramite Matter), liberando al 100% la potenza e la versatilità di questo eccellente coordinator;
• il firmware “RCP” è invece quello per l’uso del solo standard Thread (per l’uso “semplice” o tramite Matter).

Questa guida

In questa guida vedremo come riprogrammare il firmware utilizzando varie tecniche, sia allo scopo di adottare dei firmware NCP (come per esempio quello realizzato dal produttore ITEAD, magari semplicemente per aggiornare quello presente a bordo caricato in fabbrica) sia dei RCP (sia per l’uso MultiPAN che non).

Si parte

• Anatomia di ZBDongle-E
• Assunti
  • Driver e porta logica
• Firmware da utilizzare (NCP o RCP)
• Riprogrammazione
  • procedura semplificata via web-app su browser
  • procedura manuale su Linux, Raspberry Pi OS eccetera
  • procedura manuale su Windows come illustrata da ITEAD

Anatomia di ZBDongle-E

Per provvedere all’aggiornamento di ZBDongle-E solitamente non è necessario smontarla. La presenza però di pulsanti di RESET e di BOOT possono tornare utili in caso si debba “rianimarla” in caso di aggiornamenti falliti o altri scenari, quindi è bene conoscerne l’anatomia.

Al suo interno, il dongle è fatto così:

Assunti

IMPORTANTE: prima di cominciare qualunque operazione di riprogrammazione, accertarsi che eventuali software che utilizzino ZBDongle-E (eg. ZHA, ZigBee2MQTT eccetera) siano stati opportunamente fermati. La chiavetta dev’essere infatti svincolata da qualsiasi servizio che ne allochi le risorse hardware; diversamente, non sarà possibile riprogrammarla.

Driver e porta logica

Se si utilizza, per la riprogrammazione, un computer di supporto dotato di sistema operativo Apple MacOS o Microsoft Windows, prima di iniziare è necessario installare il driver di gestione del dongle USB.

Tali driver sono disponibili qui:

• per Apple MacOS;
• per Microsoft Windows.

A questo punto è necessario identificare la porta logica assegnata dal sistema operativo del computer di supporto alla chiavetta dongle anche se, per chi utilizzerà la procedura semplificata, questo passo potrebbe risultare inutile. Per identificare la porta su Linux, la procedura da seguire è questa; diversamente, su Windows o Mac è necessario riferirsi alla scheda di dettaglio dell’hardware del computer di supporto.

Tipicamente:

• Windows: COM2
• Mac: /dev/tty.usbserial12345
• Linux: /dev/ttyACM0

Una volta identificata la porta è possibile procedere oltre.

Firmware da utilizzare

In fase di riprogrammazione di questo dongle vari possono essere i firmware utilizzabili.
Ecco le scelte più tipiche:

Questi, comunque, sono solo alcuni tra gli esempi più adottati: nulla vieta di utilizzare firmware compilati provenienti da progetti di altra natura/fonte. L’importante è che siano compatibili, pertanto concepiti per operare su SOC EFR32MG21, quello alla base di ZBDongle-E e di altri coordinator.

Riprogrammazione

Per riprogrammare Sonoff ZBDongle-E è possibile sia utilizzare una procedura di molto semplificata basata su web app online oppure, per chi preferisse agire diversamente, tramite comandi manuali presso il computer di appoggio, oppure tramite le procedure indicate direttamente dal produttore.

Ecco le strade:

• procedura semplificata via web-app su browser (qualsiasi sistema operativo)
• procedura manuale su Linux, Raspberry Pi OS eccetera
• procedura manuale su Windows come illustrata da ITEAD

Tramite web-app su browser

Questa procedura è quella consigliabile a chiunque, perché semplice, efficace, veloce e sopratutto non prevede l’installazione di tool particolari (se non dei driver sopra illustrati).

Per effettuare questa procedura è necessario collegarsi, sempre tramite il computer di supporto al quale si è collegata la ZBDongle-E e sul quale si è installato (eventualmente) il driver, a un sito web tramite un browser basato su Chrome (Chrome stesso o altri).

Il sito è questo, ovvero web flasher di darkxst.

Una volta collegati, recarsi in basso alla voce ZBDongle-E:

cliccando su CONNECT si aprirà una box che, in assenza di problemi, dovrebbe elencare le chiavette connesse, ovvero nel nostro caso la singola ZBDongle-E:

selezionando la ZBDongle-E e poi Connect, la web app si collegherà alla chiavetta.

A questo punto verrà chiesto cosa si voglia fare:

cliccando su CHANGE FIRMWARE verranno elencate varie possibilità:

tra le quali la possibilità di installare dei firmware NCP o RCP proposti direttamente dall’app, oppure cliccando su “Upload your own firmware“, caricarne uno ad hoc. Cliccando infine su INSTALL, il caricamento averrà automaticamente.

Al termine, cliccare dunque su “CONTINUE” e poi disconnettere fisicamente la chiavetta dalla porta USB.

Complimenti! ZBDongle-E sarà stata riprogrammata.

Tramite Linux, Raspberry Pi OS ecc.

Prima di provvedere alla riprogrammazione è necessario verificare che l’ambiente operativo sia correttamente predisposto. Diamo per scontato che il sistema operativo sia Linux-like: gli esempi che seguono sono calati su Linux Debian o Raspberry Pi OS, ma sono facilmente mutuabili anche su altre derivazioni/distribuzioni Linux come MacOS o altro.

Colleghiamoci dunque via terminale (da CLI o via SSH) ed eseguiamo il seguente comando per verificare che Python sia installato:

python3 --version

in caso non sia installata almeno la versione 3, provvedere ad installarla con:

sudo apt install python3

aggiornare poi la versione di pip e installare i pacchetti necessari come pre-requisiti:

python3 -m pip install --upgrade pip
python3 -m pip install universal-silabs-flasher

Ora è necessario scaricare il firmware da utilizzare. Prima però colleghiamoci a uno degli indirizzi indicati sopra e troviamo il percorso Internet corretto e completo per il firmware che ci serve, che sia coordinator o router. È necessario ricavare l’indirizzo RAW del firmware da installare: in caso sia su GitHub, cliccare sul nome del file firmware, poi col tasto destro del mouse sopra il pulsante “Download” sulla destra, “copia indirizzo“.

Se per esempio l’ultima Coordinator fosse ncp-uart-hw-v7.4.3.0-zbdonglee-115200.gbl, i comandi saranno, utilizzando l’URL RAW della fonte del file:

wget https://github.com/darkxst/silabs-firmware-builder/raw/main/firmware_builds/zbdonglee/ncp-uart-hw-v7.4.3.0-zbdonglee-115200.gbl

Ora siamo pronti alla riprogrammazione. Prima però, sempre da terminale, verificare la porta logica assegnata tramite il nostro script o in altri modi (potrebbe essere /dev/ttyACM0), tipo: /dev/ttyACM0 – ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_XXXXXXXXXXXXXX

Infine, oprima di riprogrammare verfichiamo la versione del firmware presente a bordo col comando (adeguando la porta logica, se necessario):

universal-silabs-flasher --device /dev/ttyACM0 probe

il che dovrebbe dare un output tipo:

INFO Probing ApplicationType.GECKO_BOOTLOADER at 115200 baud
INFO Probing ApplicationType.CPC at 460800 baud
INFO Probing ApplicationType.CPC at 115200 baud
INFO Probing ApplicationType.CPC at 230400 baud
INFO Probing ApplicationType.EZSP at 115200 baud
INFO Probing ApplicationType.SPINEL at 460800 baud
INFO Detected ApplicationType.SPINEL, version 'SL-OPENTHREAD/x.x.x.x_GitHub-XXXXXXXX' (x.x.x.x) at 460800 baudrate (bootloader baudrate None)

sudo usermod -aG dialout nome_utente

a questo punto il device risponde ed è pronto per la riprogrammazione, che avviene tramite uno specifico comando (adeguando anche qui la porta logica e il nome del file, se necessario), per esempio:

universal-silabs-flasher --device /dev/ttyACM0 flash --firmware ncp-uart-hw-v7.4.1.0-zbdonglee-none-115200.gbl --allow-cross-flashing

Se andrà tutto bene, la procedura riporterà il seguente log:

INFO Extracted GBL metadata: NabuCasaMetadata(metadata_version=1, sdk_version='X.X.X', ezsp_version='X.X.X.X', ot_rcp_version=None, cpc_version=None, fw_type=<FirmwareImageType.NCP_UART_HW: 'ncp-uart-hw'>, baudrate=115200)
INFO Probing ApplicationType.GECKO_BOOTLOADER at 115200 baud
INFO Probing ApplicationType.EZSP at 115200 baud
INFO Probing ApplicationType.CPC at 460800 baud
INFO Probing ApplicationType.CPC at 115200 baud
INFO Probing ApplicationType.CPC at 230400 baud
INFO Probing ApplicationType.SPINEL at 460800 baud
INFO Detected ApplicationType.SPINEL, version 'SL-OPENTHREAD/X.X.X.X_GitHub-XXXXXXX' (X.X.X.X) at 460800 baudrate (bootloader baudrate None)
INFO Cross-flashing from FirmwareImageType.OT_RCP to FirmwareImageType.NCP_UART_HW
INFO Probing ApplicationType.GECKO_BOOTLOADER at 115200 baud
INFO Detected bootloader version '1.12.0'
INFO Detected ApplicationType.GECKO_BOOTLOADER, version 'X.XX.X' at 115200 baudrate (bootloader baudrate 115200)
ncp-uart-hw-vX.X.X.X-zbdonglee-115200.gbl [####################################] 100%

A questo puntio la chiavetta è pronta all’utilizzo col nuovo firmware.

La sintassi del comando è molto chiara. Nota particolare per l’option allow-cross-flashing alla fine (da inserire tassativamente dopo option per passare il file del firmware). Se non fosse stata utilizzata tale opzione, il flash sarebbe andato in KO perché, per maggiore sicurezza, di default non è consentito il flash di una tipologia di firmware diversa da quella già presente e nel nostro caso siamo passati da firmware RCP Open Thread a firmware NCP Zigbee. Ci sono anche altre opzioni disponibili con questo tool, ricapitoliamo di seguito quelle più importanti:

• --allow-cross-flashing consente il flash di una tipologia firmware diversa da quella attualmente presente sul device

• --allow-downgrades consente il flash di una versione firmware della stessa tipologia di quella attualmente presente sul device ma di versione inferiore

• --force consente di ignorare le logiche di default consentendo il flash qualsiasi firmware in termini di tipologia e versione

Tramite Windows

Su Window – salvo voler utilizzare la stessa procedura qui sopra per Linux utilizzando Python 3 per Windows, adattandola dove necessario – si rimanda alle indicazioni ufficiali di ITEAD.