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.1

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:
    • ZigBee: per l’uso come coordinator (quindi come nodo centrale della propria rete ZigBee), è possibile utilizzare quello disponibile QUI, adatto a BRIDGE/Gateway come ZigBee2MQTT o ZHA;
    • ZigBee: per l’uso come router (quindi ripetitore di segnale ZigBee), è possibile utilizzare quello disponibile QUI;
  • Firmware RCP:

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.

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

clonare poi il progetto di Elelabs tramite il seguente comando:

git clone https://github.com/Elelabs/elelabs-zigbee-ezsp-utility.git
cd elelabs-zigbee-ezsp-utility
python3 -m pip install -r requirements.txt

portiamoci poi nella directory appena creata e scarichiamo il firmware.
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-sw_EZNet6.10.3_V1.0.1.gbl, i comandi saranno, utilizzando l’URL RAW della fonte del file:

wget https://github.com/itead/Sonoff_Zigbee_Dongle_Firmware/raw/master/Dongle-E/NCP/ncp-uart-sw_EZNet6.10.3_V1.0.1.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):

python3 Elelabs_EzspFwUtility.py restart -m btl -p /dev/ttyACM0

il che dovrebbe dare un output tipo:

Generic Zigbee EZSP adapter detected:
Firmware: x.xx.xxx
EZSP v8
Launch in bootloader mode
EZSP adapter in bootloader mode detected:
Gecko Bootloader vx.xx.xx
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:

python3 Elelabs_EzspFwUtility.py flash -p /dev/ttyACM0 -f ./ncp-uart-sw_EZNet6.10.3_V1.0.1.gbl

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

EZSP adapter in bootloader mode detected:
Gecko Bootloader vx.xx.xx
Allready in bootloader mode. No need to restart
Successfully restarted into X-MODEM mode! Starting upload of the new firmware... DO NOT INTERRUPT(!)
...
Firmware upload complete
Rebooting
Generic Zigbee EZSP adapter detected:
Firmware: x.xx.xxx
EZSP v8

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

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. Se ti sei perso, a tua disposizione c'è la mappa.