Scopi della guida:
Concetti affrontati:
Componenti software utilizzate:
|
Prerequisiti:
Dispositivi fisici utilizzati:
|
GUIDA maggiormente indicatA per:
|
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 4.1 | |
Abstrac
Come noto, la linea Xiaomi Mi Smart Home (Mijia) è composta da moltissimi dispositivi diversi tra loro, i quali – nella maggior parte dei casi, nello specifico quelli basati su protocollo ZigBee – fanno capo a un BRIDGE/Gateway ZigBee↔︎TCP/IP.
Integrare questo gateway a Home Assistant significa, innanzitutto, integrarne le caratteristiche proprie (una luce LED multicolore, un riproduttore di suoni, un sensore di luminosità) quali singole entità, atomiche, sfruttabili nelle nostre automazioni e/o via frontend. Secondariamente – ma in modo altresì importante, se non di più – questa integrazione permette a Home Assistant di ereditare, quali ulteriori nuove entità, tutti gli accessori collegati al gateway stesso quali elementi “satellite” (sensori, attuatori eccetera).
Per far questo è necessario utilizzare il componente Home Assistant “Xiaomi Gateway“, concepito proprio per questo scopo. In questa guida capiremo come integrare il gateway sfruttando questo componente.
| ATTENZIONE: Per far sì che il gateway venga integrato nelle modalità descritte in questa guida è necessario che esso sia già configurato presso l’app “Xiaomi Home” come prodotto localizzato presso “Mainland China” e non, come solitamente si sceglierebbe, “Italy“. In caso li si abbia già configurato (come sarebbe logico) come “Italy” è necessario resettarlo e rifare la procedura di installazione, stavolta indicando “Mainland China”.
Per effettuare tale integrazione è necessario che la versione del firmware del componente sia uguale o inferiore alla 1.41.159. e che la versione del componente sia quella asiatica. Con quella europea l’integrazione per lo più non funziona. Firmware superiori non consentono l’integrazione qui descritta, salvo l’attuazione di questa guida. Infine, ci è stato segnalato che per la maggioranza degli esemplari europei prodotti negli ultimi mesi non ci sia nulla da fare in termini di integrabilità: semplicemente, non supportano l’integrazione. In questo sfortunato caso la strada è una sola: mantenere i propri componenti ZigBee (sensori, attuatori o quel che è) e abbandonare il gateway Xiaomi in luogo di deConz o ZigBee2MQTT (o progetti analoghi). |
Il BRIDGE/Gateway
Esistono due modelli diversi di BRIDGE/Gateway che spesso vengono confusi tra loro: il Mijia e l’Aqara. Quest’ultimo è in realtà parte della linea LUMI “Aqara Smart Automation”, è compatibile con Apple HomeKik e non è possibile integrarlo con Home Assistant (né con altri HUB) in quanto non è possibile attivare in alcun modo la modalità LAN (o dev mode).
Nel primo – nodo principale della linea Xiaomi Mi Smart Home (Mijia) – è invece possibile attivare tale modalità, come descritto nel paragrafo che segue.
N.b. Alternative (standard) al gateway Xiaomi per l’integrazione su HUB personali di componenti ZigBee sono i BRIDGE/Gateway ZigBee↔︎TCP/IP software come deCONZ, ZigBee2MQTT, ZigBee2Tasmota o altri.
Modalità LAN e KEY d’integrazione
Il gateway Xiaomi, per funzionare, sfrutta il cloud del produttore. Questo significa che la comunicazione tra l’app “Xiaomi Home” e il gateway (e i dispositivi ad esso connessi) avviene utilizzando la rete Internet – il che garantisce anche un implicito controllo da remoto di questi componenti.
Per far sì che Home Assistant “raggiunga” il gateway è necessario che quest’ultimo abbia attivata una funzione segreta, nascosta, chiamata modalità LAN (o dev-mode). Tale modalità abilita la discovery del gateway attraverso la rete LAN/Wi-Fi tramite l’apertura della porta TCP 9898, permettendo così di bypassare in toto il cloud del produttore e di collegarsi direttamente al gateway.
Una volta abilitata la modalità LAN è necessario fornire al soggetto che vuole contattare il gateway (nel nostro caso Home Assistant) una chiave, una sorta di password, tale da permettere il controllo del gateway.
Questi due passi operativi vengono effettuati dall’applicazione “Xiaomi Home” (disponibile per Android e iOS), la quale non solo permette la configurazione iniziale dei dispositivi Xiaomi, ma anche la configurazione del gateway in modalità LAN nonché il recupero della key di accesso.
| N.b. ATTENZIONE: in alcuni frangenti l’app potrebbe non consentire l’attivazione della modalità LAN. Se il modello lo prevede, non c’è da disperare: basta seguire quest’altra guida (spoiler: sì, c’è da rimboccarsi le maniche).
N.b. ATTENZIONE: in alcuni altri frangenti l’integrazione potrebbe non funzionare a causa della porta TCP 9898 chiusa lato gateway e non attivabile tramite l’app. Questo capita spesso con i gateway che abbiano indirizzo MAC che inizi con 04:CF:8C (ma non solo): per verificare che la porta sia stata effettivamente aperta eseguire il comando linux sudo nmap -sU IP_DEL_GATEWAY -p 9898
Nel caso la procedura di attivazione modalità LAN spiegata di seguito (apertura della porta TCP 9898) NON funzioni, è necessario provvedere a farlo manualmente tramite connessione fisica al gateway. |
Eseguire l’applicazione “Mi Home” e premere sull’icona relativa al gateway (ovvero “Mi Control Hub”):
Successivamente, cliccare sui tre puntini (…) in alto a destra per accedere ai dettagli del gateway:
Fatto ciò, premere su “About”:
A questo punto apparirà un menu abbastanza scarno. Ora, in base all’uso di Android o iPhone sarà necessario effettuare azioni diverse:
- su iPhone, cliccare 4-5 volte nella zona bianca sotto il menu;
- su Android, cliccare 4-5 volte sull’ultima voce di menu (“Gameplay tutorial”):
Fatto questo apparirà un menu nascosto in cinese. Per proseguire, cliccare sulla terza voce:
La schermata che si aprirà fornirà la possibilità di attivare un selettore che attiverà la modalità LAN. Inoltre, una volta attivata, poche righe sotto verrà visualizzata la tanto ambita KEY di integrazione:
In questo caso la KEY di integrazione è “41D49ED97B487373“.
A questo punto, cliccare su OK per rendere la modalità LAN permanente e la KEY fissata.
| N.b. ATTENZIONE: in alcuni frangenti l’app potrebbe non consentire l’attivazione della modalità LAN. Se il modello lo prevede, non c’è da disperare: basta seguire quest’altra guida (sì, c’è da rimboccarsi le maniche). |
Integrazione
A questo punto sarà possibile provvedere all’integrazione presso Home Assistant. Prima dell’avvento dell’aggiornamento 0.112, tale procedura si effettuava inserendo in configurazione: del codice YAML; ora, l’integrazione si effettua accedendo, tramite l’interfaccia dell’HUB, via web, alla sezione “Configurazione” > “Dispositivi e servizi“, cliccando su “+” e cercando Xiaomi:
| N.b. Nel nome è ditato “Aqara”, ma si tratta di un errore. Come spiegato sopra, i gateway Aqara NON son integrabili). |
A questo punto sarà sufficiente seguire la procedura guidata fornendo indirizzo IP del gateway efornire la KEY di integrazione precedentemente ottenuta.
Salvare la configurazione e riavviare Home Assistant.
| ATTENZIONE: assicurarsi – per garantire che l’integrazione funzioni – che il protocollo Multicast DNS (mDNS) sia attivo sul router che fornisce la connettività Wi-Fi domestica. |
Se al riavvio sarà andato tutto bene presso l’elenco completo delle entità di Home Assistant (“Developer tools / States” presso il frontend web) apparirà almeno una nuova entità di tipo “luce”, vale a dire “light.gateway_light_xxxxxxxxxxxx“, dove “xxxxxxxxxxxx” è una stringa che identifica il gateway. Questo starà a significare che il gateway è stato raggiunto e censito da Home Assistant. Per inciso, tale “luce” rappresenta il LED multicromatico disponibile sul gateway.
In caso il gateway abbia componenti “satelliti” ad esso associati, post-integrazione essi saranno riscontrabili (sempre nell’elenco entità di HA) come entità di tipologia variabile in base alla loro natura.
Se per esempio al gateway ci fosse un associato un sensore di allagamento, nella lista delle entità si troverà un nuovo sensore chiamato “binary_sensor.water_leak_sensor_xxxxxxxxxxxx” dove “xxxxxxxxxxxx” è una stringa che identifica il numero hardware del sensore. E così via.
Problemi
Può capitare di trovare sui log di Home Assistant voci di questo tipo:
2017-08-20 16:51:19 ERROR (SyncWorker_0) [homeassistant.components.xiaomi] No gateway discovered
2017-08-20 16:51:20 ERROR (MainThread) [homeassistant.setup] Setup failed for xiaomi: Component failed to initialize.
Questo significa che il gateway non è stato riconosciuto da Home Assistant.
Per tentare di risolvere, appurare i seguenti aspetti:
- Assicurarsi di aver attivato l’accesso LAN sul gateway (oggetto della guida all’integrazione su Home Assistant).
- Disattivare il firewall sul dispositivo dove è in esecuzione Home Assistant.
- Assicurarsi che il router Wi-Fi supporti (e abbia attivato) il servizio multicast (mDNS).
- Provare a impostare il campo “mac” vuoto.
- Provare a impostare il campo “discovery_retry” a 10.
- Provare a disattivare e riattivare l’accesso LAN sul gateway.
- Effettuare un hard reset del gateway: premere il suo pulsante per 30 secondi ed effettuare la procedura di pairing sull’app “Xiaomi Mi Home”.
- In caso Home Assistant sia in esecuzione su Docker, assicurarsi di usare l’impostazione “–net=host” (va aggiunta nel file “/boot/cmdline.txt“).
- In caso si riceva, in caso di tentativo di controllo della luce del gateway, l’errore
{"error":"Invalid key"}, rigenerare la chiave (oggetto della guida all’integrazione su Home Assistant) usando uno smartphone Android (alcune istanze hanno problemi con le chiavi generate da iOS) o, alternativamente, un emulatore come bluestacks. - In caso la libreria richiesta “PyXiaomiGateway” non possa essere installata, andranno installate prima alcune dipendenze necessarie come
python3-dev,libssl-dev,libffi-devin modo manuale (e.g.,$ sudo apt-get install python3-dev libssl-dev libffi-dev).
|
⚠️ 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. |