Integrare il gateway Xiaomi “Mi Smart Home” (Mijia) – e relativi accessori – a Home Assistant

6 minuti di lettura
Scopi della guida:
Concetti affrontati:
  • Utilizzo software
Componenti software utilizzate:
Prerequisiti:
  • Home Assistant configurato e funzionante
  • un BRIDGE/Gateway Xiaomi già configurato in Wi-Fi (quindi già censito dall’app mobile “Xiaomi Home”) e che monti una versione firmware ≤ 1.41.159
  • eventuali accessori ZigBee compatibili già connessi al gateway previa configurazione tramite app “Xiaomi Home”
Dispositivi fisici utilizzati:
  • Il dispositivo sul quale risiede Home Assistant;
  • il gateway Xiaomi da integrare (no LUMI Aqara);
  • eventuali accessori ZigBee ad esso connessi;
  • uno smartphone.
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere effettuata da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (la presente guida ha puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere la garanzia.
Revisione guida: 3.7

Abstract

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. Firmware superiori non consentono l’integrazione qui descritta, salvo l’attuazione di questa guida.

Il gateway

Esistono due modelli diversi di 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 e zigbee2mqtt, 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”):

Xiaomi Gateway - LAN e KEY - 1

Successivamente, cliccare sui tre puntini (…) in alto a destra per accedere ai dettagli del gateway:

Xiaomi Gateway - LAN e KEY - 2

Fatto ciò, premere su “About”:

Xiaomi Gateway - LAN e KEY - 3

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”):

Xiaomi Gateway - LAN e KEY - 4

Fatto questo apparirà un menu nascosto in cinese. Per proseguire, cliccare sulla terza voce:

Xiaomi Gateway - LAN e KEY - 5

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:

Xiaomi Gateway - LAN e KEY - 6

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, semplicemente inserendo in configurazione:

xiaomi_aqara:
  discovery_retry: 5
  gateways:
    - key: xxxxxxxxxxxxxxxx

Dove “key: xxxxxxxxxxxxxxxx” rappresenta 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 comepython3-dev,libssl-dev,libffi-dev in modo manuale (e.g., $ sudo apt-get install python3-dev libssl-dev libffi-dev).


Home Assistant Official LogoATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.


Please comment below