Installare e configurare OpenThread Border Router con Docker su Linux Debian (Mini PC/Intel NUC o altro)

SCOPI DELLA GUIDA: Installare e configurare il BRIDGE/Gateway OpenThread Border Router usando Docker su sistema operativo Linux Debian (o più genericamente, su Linux), dotandosi così di una rete Thread per la propria domotica personale Livello di difficoltà: medio/basso CONCETTI AFFRONTATI: Utilizzo e configurazione software	COMPONENTI SOFTWARE UTILIZZATE: Sistema operativo Linux Debian (64bit) OpenThread Border Router per Docker Docker per Linux Debian Docker Compose (opzionale) PREREQUISITI: Mini PC/Intel NUC (o computer generico) precedentemente configurato con Linux Debian e collegato alla rete domestica e, tramite essa, ad Internet DISPOSITIVI FISICI UTILIZZATI: Il computer sul quale è in esecuzione Home Assistant Un’antenna Thread Coordinator compatibile con OpenThread Border Router (illustrato a seguire)
GUIDA 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.0

Abstract

Thread è uno standard wireless molto valido, specie in termini di sicurezza, affidabilità e resilienza. Nato nel 2015, malgrado sia tecnicamente superiore a standard di grande successo come ZigBee e Z-Wave non ha ottenuto, negli anni, il successo che avrebbe meritato. Pochissime le componenti compatibili, pochissime le sue implementazioni.

L’avvento di Matter ne ha rilanciato – giustamente – la popolarità. Scelto come standard soggiacente a questo nuovo sovra-standard (concepito espressamente per facilitare l’integrazione e la cooperazione di diversi ecosistemi smart), vive oggi una nuova primavera.

Per introdurre componenti Thread e/o Matter over-Thread nella propria domotica personale è necessario avere, presso la propria rete LAN (abilitata all’uso di IPv6), un cosiddetto router di confine (o di frontiera), vale a dire un BRIDGE/Gateway che faccia da ponte tra la propria rete Thread e la rete LAN – proprio come accade con i sopracitati standard ZigBee e Z-Wave. Per la natura di Thread, i router di confine possono essere più di uno e collaborano, tutti, alla gestione della rete mesh.

Un modo per dotarsi di router di confine Thread è quello di acquistare dispositivi che, oltre alla propria funzione principale, offrano questo servizio, per esempio:

• Apple HomePod;
• Amazon Echo 4a generazione (e superiori);
• Nanoleaf Shapes;
• Aqara Hub M3

e molti altri, anche da noi testati.

Un’alternativa efficace è altrimenti quella di utilizzare un BRIDGE/Gateway software come OpenThread Border Router (OTBR per gli amici) il quale, tramite un’antenna fisica (vedremo quale/i) può definire da sé una rete mesh Thread allo scopo di integrare, tramite esso, componenti Thread e, tramite istanze Matter che vi si “appoggino”, componenti Matter over-Thread.

N.b. Un componente Thread non è automaticamente compatibile Matter over-Thread, anzi: deve essere esplicitamente attivato allo scopo (dal produttore). Se non lo è, è “solo” compatibile Thread. Per esempio, questa e questa lampadina Nanoleaf sembrano uguali, ma in realtà la prima è Thread mentre la seconda è Matter over-Thread.

Lo scopo della presente guida è quindi quella di istanziare OpenThread Border Router (definendo così una rete Thread) usando Docker, presso il sistema operativo Linux.

In coda, per gli utenti che ne abbiano interesse, documenteremo come:

• integrare il servizio presso Home Assistant (abilitandolo indirettamente nell’integrare componenti Thread);
• abilitare la rete Thread così creata presso le reti note a Home Assistant, così da poter integrare componenti Matter over-Thread.

---

Altre guide disponibili su inDomus dedicate a Thread sono:

• Come attivare il supporto allo standard Matter su Home Assistant
• Come installare e configurare Silicon Labs Multiprotocol per gestire coordinator RCP MultiPAN (Sonoff ZBDongle-E, ZBT-1 e affini)
• Installare e configurare OpenThread Border Router su Home Assistant OS/Supervised (con ZBDongle-E, Z-Station, ZBT-1 e affini)
• Integrare lo standard Thread su Home Assistant usando coordinator RCP MultiPAN (Sonoff ZBDongle-E, ZBT-1 e affini)
• Riprogrammare il firmware di ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus)
• Riprogrammare il firmware di ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus) – v2

 

ATTENZIONE: LA PRESENTE GUIDA È DA CONSIDERARSI IN “BETA”, IN QUANTO LE CONFIGURAZIONI PROPOSTE – PER QUANTO CORRETTE E VERIFICATE – DANNO LUOGO A FUNZIONAMENTO NON DEL TUTTO STABILE, PROBABILMENTE A CAUSA DELLA GIOVENTÙ DELLA RELEASE DELL’IMMAGINE DOCKER E DELL’IMPLEMENTAZIONE STESSA DI OTBR. LA GUIDA È PRESIDIATA E VIENE AGGIORNATA AD OGNI EVENTUALE NOVITÀ O VARIAZIONE.

 

Si parte

• Assunti
• Thread Coordinator (antenna)
• Installare Docker
• OpenThread Border Router (OTBR)
  • Istanziarlo tramite comando “docker run”
  • Istanziarlo tramite Docker Compose
• Interfaccia web
• Integrazione di OTBR a Home Assistant
• Uso
  • Con Matter
  • Solo Thread

Assunti

Questa guida è dedicata a chi abbia già un computer con sistema operativo Linux Debian. Per coloro che non abbiano ancora provveduto e si trovino ad avere un Mini PC/Intel NUC, magari acquistato appositamente per realizzare la propria domotica, allora questo passo della guida va smarcato seguendo prima un’altra guida, che spiega passo passo come configurare il sistema operativo Linux Debian.

Una volta terminata la configurazione di Linux Debian (inclusa la possibilità di collegarvisi tramite SSH nonché aver effettuato il perfezionamento) è possibile procedere nella presente guida.

Inoltre, si assume che la rete LAN che ospita l’host (nonché l’interfaccia di rete dell’host stesso) abbia il supporto a IPv6 operativo.

Thread Coordinator (antenna)

Prima cosa, ancor prima di avventurarsi nell’installazione del BRIDGE/Gateway software, è l’installazione dell’antenna, ovvero del componente cardine di una rete mesh Thread: il coordinator. Tale elemento è rappresentato da un’antenna interfacciata al computer ospitante via USB, via seriale o altro.

OpenThread Border Router supporta svariate antenne, tra le quali abbiamo documentato:

Antenna coordinator	Caratteristiche
ConBee III	dongle USB, di buona potenza. Per essere usata con OTBR, necessita di firmware apposito.
🔆 ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E)	dongle USB multistandard (Thread e ZigBee). Se usata con firmware RCP MultiPAN, può fungere contemporaneamente da coordinator Thread su OTBR e ZigBee su altri BRIDGE/Gateway. Altrimenti, con firmware RCP, come solo coordinator Thread su OTBR. La guida per aggiornare il firmware è qui.
🔆 Z-Wave.Me Z-Station	dongle USB multistandard (ZigBee, Z-Wave, Thread). Per essere utilizzata con OTBR necessita di firmware apposito OpenThread, oppure firmware RCP Multistandard (chiamato anche "CPC" da Z-Wave.me) che consente di utilizzarla anche, contemporaneamente, come coordinator ZigBee. La guida ufficiale per aggiornare il firmware è qui.

Noi ne abbiamo testata una soltanto, quindi non ci sbilanciamo per ora su modelli alternativi. Tale antenna è la arcinota Sonoff ZBDongle-E.

Per essere utilizzata con la presente guida, tale antenna deve:

• essere riprogrammata con firmware RCP Thread (qui la guida), firmware da non confondersi con RCP MultiPAN (che permette l’uso contemporaneo come antenna ZigBee e Thread);
• essere utilizzata, quindi, unicamente per Thread.

Se si vuole utilizzare firmware RCP MultiPAN, far riferimento solo a quest’altra guida e non alla presente.

Una volta riprogrammata allo scopo, è possibile installare correttamente l’antenna (basta inserirla in una delle porte USB del computer ospitante Home Assistant) dopodiché appurare che il sistema operativo “veda” tale device.

N.b. Le tecniche descritte nella presente guida sono sostanzialmente valevoli per la Sonoff ZBDongle-E così come per qualsiasi altra antenna compatibile con OpenThread Border Router, purché non utilizzino firmware RCP MultiPAN.

VERIFICA POST-INSTALLAZIONE

Dopo aver aggiornato il firmware dell’antenna, averla collegata (in caso sia USB) e aver riavviato il computer host, è dunque il momento di effettuare una verifica per appurare porta logica sia stata assegnata all’antenna dal sistema operativo. A questo scopo andiamo a definire uno script come da nostra guida.

Eseguito lo script, si identificherà l’antenna, per esempio:

/dev/ttyACMx

oppure qualcosa tipo:

/dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_XXXXX-if00

In caso appaia l’installazione sarà considerata valida; segnarsi la stringa da una parte, servirà più avanti.

Installare Docker

Installare Docker su Linux Debian è piuttosto semplice, esiste una procedura completamente automatica e una manuale. Entrambe le procedure sono illustrate in dettaglio in questa breve guida.

Se si ha già provveduto all’installazione di Docker, va da sé che questo passaggio possa essere saltato.

ATTENZIONE: affinché i comandi a seguire funzionino, è necessario aver aggiunto Docker al gruppo sudoers, come spiegato in guida.

OpenThread Border Router (OTBR)

Vediamo dunque come istanziare questo BRIDGE/Gateway Thread.

In ambito Docker, l’istanziamento dell’applicazione può essere effettuato tramite esecuzione di un comando manuale (più immediato) oppure tramite una configurazione del tool di gestione Docker Compose, approccio inizialmente più ostico ma che consigliamo per tutta una serie di motivi. Entrambe le scelte sono valide, ma in prospettiva (specie in ottica di aggiornamento) imparare ad usare Docker Compose è altamente consigliato.

Prima di procedere, però, è necessario creare una cartella la quale conterrà la sua configurazione.

Una volta collegati via SSH a Linux Debian, eseguiamo:

mkdir -p ~/otbr

Inoltre, è necessario provvedere al probe della rete IPv6, eseguendo:

sudo modprobe ip6table_filter
sudo tee -a /etc/modules <<< "ip6table_filter"
sudo update-initramfs -u

Infine, riavviare con:

sudo reboot

Provvediamo ora all’istanziamento vero e proprio dell’applicazione, utilizzando come spiegato prima o il comando “docker run” o la più versatile configurazione Docker Compose.

Tramite comando “docker run”

Istanziamo dunque ZigBee2MQTT su Docker tramite il comando:

docker run --sysctl "net.ipv6.conf.all.disable_ipv6=0 net.ipv4.conf.all.forwarding=1 net.ipv6.conf.all.forwarding=1" -p 8080:80 -p 8081:8081 --dns=127.0.0.1 -it --volume device:/dev/ttyUSB0 --volume ~/otbr:/var/lib/thread --privileged openthread/otbr --radio-url spinel+hdlc+uart:///dev/ttyUSB0?uart-baudrate=460800 --restart always

dove ovviamente nel campo “device” vada indicata la porta precedentemente identificata, per esempio /dev/ttyACM0. La parte in rosso (/dev/ttyUSB0) non va modificata. Va lasciata così.

VERIFICA

Per verificare che tutto sia andato per il verso giusto, eseguire:

docker logs otbr

sul fondo, se è tutto ok, dovrebbe apparire un log tipo:

[00:00:00] INFO: Starting otbr-web...
otbr-web[267]: [INFO]-WEB-----: Running X.Y.Z-XXXXXce-dirty
otbr-web[267]: [INFO]-WEB-----: Border router web started on wpan0
Done
s6-rc: info: service otbr-agent-configure successfully started

che, sostanzialmente, identifica un corretto avvio di OpenThread Border Router.

Congratulazioni: OpenThread Border Router è ora operativo.
A questo punto è possibile provvedere all’integrazione con Home Assistant (per far sì che l’HUB utilizzi la rete Thread – anche, volendo, con Matter). Altrimenti, la guida si conclude qui.

Tramite Docker Compose

Se astutamente si sceglie di utilizzare Docker Compose, allora è semplicemente necessario aggiungere al proprio file docker-compose.yaml la seguente configurazione (sotto il bocco services):

  otbr:
    container_name: "otbr"
    image: openthread/otbr
    sysctls:
        - net.ipv6.conf.all.disable_ipv6=0 net.ipv4.conf.all.forwarding=1
          net.ipv6.conf.all.forwarding=1
    ports:
        - 8080:80
        - 8081:8081
    dns:
        - 127.0.0.1 
    stdin_open: true
    tty: true
    volumes:
        - device:/dev/ttyUSB0
        - ~/otbr:/var/lib/thread
    privileged: true
    command: ["--radio-url", "spinel+hdlc+uart:///dev/ttyUSB0?uart-baudrate=460800"]
    restart: always

dove ovviamente nel campo “device” vada popolato con la porta precedentemente identificata, per esempio /dev/ttyACM0), mentre la parte in rosso (/dev/ttyUSB0) non va modificata. Va lasciata così.

Una volta salvato il file docker-compose.yaml, eseguire il comando:

docker compose up -d otbr

il quale provvederà a istanziare il container.

N.b. In caso il comando “docker compose” dovesse dare errore, verificare di non aver installata la versione applicativa di Docker Compose anzichè la versione plug-in alla quale il comando sopra fa riferimento. In tal caso, adeguare il comando da “docker compose” a “docker-compose” (col trattino in mezzo).

VERIFICA

Lanciato il comando, attendere il completamente del primo avvio. Ci potrebbe volere un po’: per leggere in tempo reale i log e verificare quindi cosa stia succedendo all’interno del container, eseguire il comando:

docker logs otbr

sul fondo, se è tutto ok, dovrebbe apparire un log tipo:

[00:00:00] INFO: Starting otbr-web...
otbr-web[267]: [INFO]-WEB-----: Running X.Y.Z-XXXXXce-dirty
otbr-web[267]: [INFO]-WEB-----: Border router web started on wpan0
Done
s6-rc: info: service otbr-agent-configure successfully started

che, sostanzialmente, identifica un corretto avvio di OpenThread Border Router.

Congratulazioni: OpenThread Border Router è ora operativo.
A questo punto è possibile provvedere all’integrazione con Home Assistant (per far sì che l’HUB utilizzi la rete Thread – anche, volendo, con Matter). Altrimenti, la guida si conclude qui.

Interfaccia web

Open Thread Border Router presenta anche un’interfaccia web di amministrazione, la quale è disponibile presso:

http://IP_DI_OTBR:8080

dove IP_DI_OTBR è l’indirizzo IP assegnato all’host che ospita OTBR.
Per il momento, comunque, non la utilizzeremo.

Integrazione a Home Assistant

Giunti a questo punto il BRIDGE/Gateway OTBR è sì in esecuzione, ma Home Assistant ancora non lo “conosce”, pertanto non può utilizzarne la rete.

In realtà, recandosi presso al configurazione dell’integrazione Thread (la quale dovrebbe essere già operativa; in caso, attivarla manualmente cliccando su “Aggiungi integrazione“) potrebbe già apparire la rete appena creata la quale, però, non è effettivamente ancora utilizzabile dall’HUB.
Questo perché non ne conosce le credenziali di accesso.

Per far sì che Home Assistant le conosca, è appunto necessario integrare OTBR.

Recarsi dunque alla voce “Integrazioni” del pannello HACS e cercare, per l’appunto, “OpenThread Border Router” e aggiungerlo. Alla richiesta di coordinate di accesso, indicare:

ws://IP_DI_OTBR:8081

dove IP_DI_OTBR è l’indirizzo IP assegnato all’host che ospita OTBR.

Al termine della procedura, OpenThread Border Router (e la sua rete Thread) sarà stata integrata all’HUB.

Verifica

Recarsi presso l’integrazione Thread e, cliccando su configura, verificare che esista una rete Thread che presenti l’icona della chiave, ovvero che sia non solo rilevata da Home Assistant ma anche che quest’ultimo ne conosca le credenziali di accesso.

A questo punto cliccare su “RENDI RETE PREFERITA” (o “MAKE PREFERRED NETWORK“): questo farà sì che Home Assistant, per qualsiasi integrazione Thread e Matter over-Thread utilizzi questa rete di recente creazione.

Una volta fatto, la rete apparirà tra quelle preferite:

Complimenti! La configurazione ora è completa.

Uso

Come spiegato anche in abstract, ora è possibile cominciare a integrare componenti Thread e Matter over-Thread presso l’HUB. Per farlo, gli appocci sono molto diversi.

Con Matter

In primis, è necessario che l’integrazione Matter sia operativa e funzionante.
Per garantirlo, seguire questa guida:

Come attivare il supporto allo standard Matter su Home Assistant

Fatto ciò, la procedura per integrare una componente Matter over-Thread è semplice:

• accendere il componente Matter over-Thread (in caso sia già acceso, spegnerlo e riaccenderlo;
• aprire l’app Home Assistant Companion, recarsi alla voce Integrazioni, aggiungere nuovo componente Matter e seguire le istruzioni (che prevedono di inquadrare il QR Code del dispositivo e sostanzialmente… attendere).

Al termine della procedura, l’integrazione del componente Matter over-Thread sarà stata completata, ed esso utilizzerà la rete OpenThread Border Router appena creata.

Solo Thread

Per integrare componenti Thead “lisci” (ovvero senza compatibilità Matter over-Thread), è necessario utilizzare l’intefaccia web di OTBR, disponibile all’indirizzo:

http://IP_DI_OTBR:8080

Presso tale interfaccia, selezionare la voce “Commission” e seguire le istruzioni necessarie all’integrazione del componente Thread in questione.

⚠️ Se di Home Assistant ne sai poco ma sei interessato a capirne di più, ti suggeriamo di partire da qui.

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.