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

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

SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
  • Riprogrammazione firmware
COMPONENTI SOFTWARE UTILIZZATE:
DISPOSITIVI FISICI UTILIZZATI:
GUIDA maggiormente DEDICATA A utenti:
Tutti gli ambienti
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.6

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 Sonoff ZigBee 3.0 USB Dongle Plus ZBDongle-E - PackageITEAD 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 MultiPAN RCP.

Il “MultiPAN RCP” 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.

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

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ì:

Sonoff ZigBee 3.0 USB Dongle Plus ZBDongle-E - Board

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:

N.b. Dopo aver installato i driver, si ricorda di riavviare il computer di supporto, specialmente se dotato di sistema operativo 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. Ne elenchiamo alcuni:

  • Firmware NCP (consigliato):
    • ZigBee: per l’uso come coordinator (quindi come nodo centrale della propria rete ZigBee), è possibile utilizzare quelli adatti a BRIDGE/Gateway come ZigBee2MQTT o ZHA. In quanto alla velocità, selezionare file da 115200 baud. Li si trova qui::
      • QUI (versione ufficiale ITEAD) – non consigliato;
      • QUI (versioni darkxst “normale”, con prefisso NCP) – consigliato;
      • QUI (versione daskxst con solo controllo di flusso software in caso di problemi con quelli “normali”, prefisso NCP) – consigliato in caso di problemi.
    • ZigBee: per l’uso come router (quindi ripetitore di segnale ZigBee), è possibile utilizzare quello disponibile QUI (versione ufficiale ITEAD). All’utilizzo della ZBDongle-E come router abbiamo dedicato questa guida ad hoc;
  • Firmware RCP:
    • ZigBee + Thread: per utilizzare questa antenna sia come coordinator ZigBee (con BRIDGE/Gateway come ZigBee2MQTT o ZHA) sia come coordinator Thread (con BRIDGE/Gateway come Open Thread Border Router per esempio su Home Assistant, per aprirsi a Matter), il firmware da utilizzare è disponibile QUI (con prefisso RCP). In quanto alla velocità, selezionare file da 460800 baud. Usare esplicitamente la versione 4.3.1 del firmware RCP: le versioni più nuove hanno infatti dei problemi.

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.

ATTENZIONE. L’uso del firmware RCP per l’uso conteporaneo di ZigBee e Thread non consente l’uso plug&play verso di BRIDGE/Gateway sopra elencati, ma prevede un ulteriore strato software intermedio (un “co-processor communication daemon”) chiamato Silicon Labs Multiprotocol. La guida per la sua implementazione (dopo l’avvenuta riprogrammazione del firmware) è disponibile qui.

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:

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:

darkxst web flasher - ZBDongle-E - 1

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:

darkxst web flasher - ZBDongle-E - 2

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

A questo punto verrà chiesto cosa si voglia fare:

darkxst web flasher - ZBDongle-E - 3

cliccando su CHANGE FIRMWARE verranno elencate varie possibilità:

darkxst web flasher - ZBDongle-E - 4

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.

darkxst web flasher - ZBDongle-E - 5

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

darkxst web flasher - ZBDongle-E - 6

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-get 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.1.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.1.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)
N.b. In caso il comando dia luogo a un errore “access denied“, eseguire il comando:

sudo usermod -aG dialout nome_utente

adeguando quindi nome_utente al proprio nome utente Linux in uso. Uscire poi dalla sessione SSH/bash e rientrare col medesimo 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.

Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa.