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

Riprogrammare il firmware di ITEAD Sonoff ZBDongle-P (ZigBee 3.0 USB Dongle Plus)

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: 2.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 firmware.

SONOFF Zigbee USB dongle

ITEAD Sonoff ZigBee 3.0 USB Dongle Plus è un piccolo ed economico componente che permette, abbinato al software ZigBee2MQTT (o altri software analoghi) di definire un BRIDGE/Gateway ZigBee↔︎MQTT utile ad amministrare una rete ZigBee nella propria domotica personale (e quindi accessori basati su questo standard); il componente per lo più è pronto all’uso, ma talvolta si rende necessaria una riprogrammazione del firmware per l’aggiornamento (o la sostituzione) dello stesso.

Questa guida illustra una delle modalità di riprogrammazione tramite un computer di supporto (qualsiasi modello) e senza la necessità di dispostivi di collegamento, grazie all’ausilio di questo progetto Open Source. Tale riprogrammazione si rende necessaria in presenza di aggiornamenti del firmware presente sul device oppure per la volontà, per motivi propri, di cambiarne versione od origine.

La guida, ovviamente, è utilizzabile anche con eventuali altri firmware compatibili con ITEAD Sonoff ZigBee 3.0 USB Dongle Plus.

Si parte

Smontare la chiavetta (se serve)

In alcuni casi si rende necessario, per impostare il coordinator in modalità di riprogrammazione, di premere un pulsante presente sulla board, definito “boot button“:

Sonoff ZigBee 3.0 USB Dongle Plus - Package - Hardware

Procedere quindi alla riprogrammazione come spiegato nei paragrafi che seguono: se non si riesce a scrivere il firmware, allora accedere alla board interna del coordinator tramite smontaggio.

Per farlo, svitare l’antenna e poi svitare le due piccole viti sul frontale, facendo attenzione a non perderle.

ITEAD Sonoff ZigBee 3.0 USB Dongle Plus - USB viti
dettaglio del frontale.

Assunti

Importante: prima di cominciare qualunque operazione di riprogrammazione, accertarsi che eventuali software che utilizzano la chiavetta (eg. ZHA, o ZigBee2MQTT) siano stati opportunamente fermati.

Driver

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

Tali driver sono disponibili qui.

Firmware da utilizzare

In fase di riprogrammazione di questo dongle vari possono essere i firmware utilizzabili. Ne elenchiamo alcuni:

  • ZigBee: per l’uso come coordinator (quindi come nodo centrale della propria rete ZigBee), è possibile utilizzare quello disponibile QUI (identificare l’ultima versione disponibile del launchpad_coordinator), adatto a BRIDGE/Gateway come ZigBee2MQTT o ZHA;
  • ZigBee: per l’uso come router (quindi ripetitore di segnale ZigBee), è possibile utilizzare quello disponibile QUI.

In tutti i casi è necessario ricavare l’indirizzo RAW del firmware da installare (servirà più avanti) cliccando sul nome del file firmware, poi col tasto destro del mouse sopra il pulsante “Download” sulla destra, “copia indirizzo”.

Riprogrammazione

Via Docker (su qualsiasi sistema)

Se si dispone di Docker installato sul proprio computer di appoggio (qui una guida per Linux Debian, qui una per Raspberry Pi OS), l’aggiornamento del firmware è abbastanza semplificato.

Con la chiavetta collegata alla porta USB del proprio computer di appoggio, verificare quale sia la porta logica assegnata alla USB dongle tramite il nostro script per Linux (o in altri modi su altri sistemi operativi).

Nota: su Linux la porta assegnata potrebbe essere /dev/ttyUSB0, oppure /dev/ttyUSB0 – ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXX; su Windows potrebbe essere COM1 o qualcosa di simile.

A questo punto possiamo eseguire un comando che istanzi temporaneamente un container docker basato sull’app ckware/ti-cc-tool e che, indicata la corretta porta assegnata alla USB dongle e l’URL dal quale andare a prendere il firmware, provveda a flasharlo sulla USB dongle:

docker run --rm --device /dev/XXXXX:/dev/ttyUSB0 -e FIRMWARE_URL=URL_DEL_FIRMWARE?raw=true ckware/ti-cc-tool -ewv -p /dev/XXXXX --bootloader-sonoff-usb

perché tutto funzioni, va personalizzato in modo corretto:

  • la porta /dev/XXXXX, la quale va personalizzata con la propria porta assegnata (eg. /dev/ttyUSB);
  • la chiave URL_DEL_FIRMWARE, la quale deve contenere l’indirizzo del file .zip del firmware (compresso) da usare (eg. https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/Z-Stack_3.x.0/bin/CC1352P2_CC2652P_launchpad_coordinator_20230507.zip).
    Tale url (RAW) si ottene come spiegato sopra.

Se tutto verrà scritto correttamente, l’aggiornamento avverà automaticamente e in modo corretto.

Via applicativa

Se non si vuole/non si può usare Docker, allora è possibile installare sul sistema operativo del computer di appoggio un piccolo applicativo utile alla riprogrammazione.

Su Raspberry OS, Linux Debian, 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 distribuzioni Linux.

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 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 pyserial intelhex

clonare poi il progetto tramite il seguente comando:

git clone https://github.com/JelmerT/cc2538-bsl.git

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.

Se per esempio l’ultima fosse CC1352P2_CC2652P_launchpad_coordinator_20230507.zip, i comandi saranno, utilizzando l’URL RAW della fonte del file:

cd cc2538-bsl
wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/Z-Stack_3.x.0/bin/CC1352P2_CC2652P_launchpad_coordinator_20230507.zip
unzip CC1352P2_CC2652P_launchpad_coordinator_20230507.zip

Ora siamo pronti alla riprogrammazione vera e propria. Con la chiavetta collegata alla porta USB del proprio computer di appoggio, verificare quale sia la porta logica ad essa assegnata tramite il nostro script (o in altri modi su altri sistemi operativi).

Nota: su Linux la porta assegnata potrebbe essere qualcosa come /dev/ttyUSB0, oppure /dev/ttyUSB0 – ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXX.

Ora lanciare il comando per la riprogrammazione:

./cc2538-bsl.py -p /dev/ttyUSB0 -evw --bootloader-sonoff-usb CC1352P2_CC2652P_launchpad_coordinator_20230507.hex

avendo cura di correggere /dev/ttyUSB0 con la corretta porta di assegnazione, qualora fosse diversa. Ovviamente il nome del file .hex può variare in base alla versione del firmware scaricato, quindi il comando andrà corretto coerentemente anche in questo senso-.

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

Opening port /dev/ttyUSB0, baud 500000
Reading data from CC1352P2_CC2652P_launchpad_coordinator_XXXXXXXX.hex
Your firmware looks like an Intel Hex file
Connecting to target...
CC1350 PG2.0 (7x7mm): 352KB Flash, 20KB SRAM, CCFG.BL_CONFIG at 0x00057FD8
Primary IEEE Address: 00:12:4B:00:24:C9:B1:07
    Performing mass erase
Erasing all main bank flash sectors
    Erase done
Writing 360448 bytes starting at address 0x00000000
Write 104 bytes at 0x00057F980
    Write done                                
Verifying by comparing CRC32 calculations.
    Verified (match: 0xba5c19c5) 

A questo punto basterà scollegare e ricollegare la chiavetta per poterla utilizzare nuovamente come proprio coordinator ZigBee.

Su Windows

In primis, scaricare l’ultima versione disponibile del firmware come spiegato sopra, poi decomprimerlo.

Verificare l’installazione di Python (da Powershell o da Prompt dei Comandi) tramite il comando…

python3 --version

Qualora non sia presente, scaricare Python (si consiglia versione 3) ed installarlo.

Aggiornare poi la versione di pip:

python3 -m pip install --upgrade pip

Installare i pacchetti indicati come prerequisiti:

python3 -m pip install pyserial intelhex

Clonare il progetto che consente la riproammazione con il seguente comando:

git clone https://github.com/JelmerT/cc2538-bsl.git
cd cc2538-bsl

Copiare all’interno della directory appena clonata il firmware da utilizzare per il flash (il nome varia in base alla versione, ipotizziamo che sia CC1352P2_CC2652P_launchpad_coordinator_20230507.hex)

A questo punto sarà necessario collegare la chiavetta ad una porta USB tenendo premuto il tasto BOOT, per poi rilasciarlo dopo un secondo (provare anche senza il bisogno di premere il pulsante, con alcune board va uguale).

Verificare dalla gestione delle periferiche la porta COM assegnata alla chiavetta; per la seguente guida assumiamo che sia COM4.
Sempre da Powershell o da Prompt dei Comandi lanciare il seguente comando:

cc2538-bsl.py -p COM4 -evw --bootloader-sonoff-usb CC1352P2_CC2652P_launchpad_coordinator_20230507.hex

Nota: ovviamente il nome del file .hex può variare in base alla versione del firmware scaricato, quindi il comando andrà corretto coerentemente.

A questo punto basterà scollegare e ricollegare la chiavetta per poterla utilizzare nuovamente come proprio coordinator ZigBee.

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.