Integrare le gesture Xiaomi/LUMI (Magic) Cube con Home Assistant via deCONZ

5 minuti di lettura
Scopi della guida:
  • Integrare il (Magic) Cube di Xiaomi/LUMI alla propria domotica Home Assistant tramite deCONZ al fine di utilizzare le sue molte gesture come strumento di gestione e controllo
  • Livello di difficoltà: bassa
  • Categoria d’integrazione: Local Push
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere garanzia, omologazioni e certificazioni di qualità.
Revisione guida: 1.1

Aqara Cube - in mano

Abstract

Il (Magic) Cube della Xiaomi e della LUMI (lo producono i due noti cugini, ma si tratta sempre lo stesso oggetto) è per l’appunto un piccolo cubo in plastica, dotato di un suo discreto peso, che nasconde al suo interno l’elettronica che lo dota di accelerometri sui tre assi e di trasmissione su standard ZigBee.

Ma a cosa serve?

A una cosa specifica, ma declinata in modalità diverse.
In pratica il “Cube” è in grado di rilevare una serie di gesture, ovvero di movimenti, a cui viene sottoposto: ribaltamenti, rivoluzioni sull’asse, cadute: ognuna di queste specifiche condizioni può essere intercettata dalla propria domotica e utilizzata per attivare specifiche funzionalità.

Aqara Mi Cube
scuotere / rotazione 90-180 / rotazione asse / verticale / spostamento laterale

Inoltre, il “Cube” è in grado di distinguere ribaltamenti da faccia a faccia, per esempio ribaltamento dalla faccia 2 alla faccia 6, e così via.

Come sappiamo le modalità di integrazione di componenti ZigBee con Home Assistant passano sempre da un BRIDGE/Gateway che canalizza le comunicazioni da/per il componente e che le “trasformi” in chiamate utili a Home Assistant. Un “ponte”, per l’appunto, tra due mondi. Il “Cube” è compatibile con vari BRIDGE/Gateway: in primis, quello della propria linea prodotti, ovvero quello della famiglia LUMI Aqara (non integrabile a Home Assistant); è inoltre compatibile con quello Xiaomi Mijia (integrabile a Home Assistant) nonché ad altri considerati “jolly”, come zigbee2mqtt e deCONZ.

Bene: in questa guida vedremo come integrare il cube a Home Assistant tramite deCONZ e come sfruttare le tante, diverse rilevazioni possibili per attivare la nostra domotica.

Assunti

Si assume che Home Assistant ovviamente sia già operativo e che deCONZ sia già installato, in esecuzione e integrato a Home Assistant. Le guide su come realizzare questo secondo punto sono disponibili su inDomus per gli utenti che utilizzino Home Assistant installato su Raspbian@Raspberry e per gli utenti che utilizzino Home Assistant in distribuzione HASSIO.

N.b. La versione di Home Assistant dev’essere minimo la 0.104.x.

Si parte

Integrare il “Cube” a deCONZ

In primis è necessario far sì che il BRIDGE/Gateway deCONZ associ il “Cube” in questione.
Per farlo, la procedura è la solita che si effettua ogni qual volta di aggiunge un componente compatibile: si accede all’interfaccia deCONZ e, in questo caso alla voce “Switch” (sì, il “Cube” viene visto come un interruttore anziché come sensore, come invece ci si aspetterebbe) si clicca su “Add new switch“.

deCONZ - Ambiente operativo web
la comoda interfaccia web di deCONZ.

Una volta cliccato sul bottone a schermo premere il tasto presente sul “Cube” (dietro una delle facce, smontabile) e attendere che appaia a schermo l’ok sull’avvenuta associazione tra il sensore e deCONZ.

Terminata questa fase, riavviare Home Assistant.

Domini e ID

Differentemente da come capita con altre integrazioni (leggi focus sul tema), quella del “Cube” non dà vita alle entità che ci si aspetterebbe: in realtà ne genera soltanto una, un “Sensor” contenente nello stato il livello di batteria. Come sfruttare quindi il “Cube” nelle automazioni, se non ho un’entità a cui far riferimento nei miei trigger?

Utilizzando l’event bus.

L’event bus è in sostanza il canale dove tutti i cambi di stato all’interno di Home Assistant fluiscono. Ognuno di essi ha un “dominio”: per esempio “light” è un dominio, e ogni qual volta un’entità di questo tipo subisce un qualsiasi cambio di stato, tale cambiamento viene comunicato all’ambiente operativo tramite l’event bus.

Quando si integra deCONZ a Home Assistant viene creato un nuovo dominio chiamato per l’appunto “deconz“. Per quei componenti gestiti via deCONZ (ma anche in altri casi) che per motivi squisitamente tecnici non danno origine a entità, la soluzione per definire automazioni è rimanere in ascolto del loro dominio per intercettarne i cambi di stato che, comunque, fluiscono dal BRIDGE/Gateway. Tali cambi di stato sono associati, oltre al dominio, a un ID device e un ID evento (e a volte un ID sub-evento).

Conoscendo dominio, ID device e ID evento/sub-evento è dunque possibile utilizzarli nei propri trigger d’automazione.

Prima dell’avvento della gestione diretta dei “Devices” di Home Assistant riuscire a identificare non tanto i domini quanto i due ID era piuttosto complicato: bisognava accedere a degli specifici file, scovare delle chiavi, insomma una cosa lunga e macchinosa. Ora, per fortuna, la gestione diretta permette non solo di identificare facilmente questi parametri, ma anche di definire direttamente delle automazioni senza bisogno di mettere mano ai file di configurazione.

Ovviamente percorreremo questa nuova ed efficiente strada.

Home Assistant

Per accedere alle informazioni di cui sopra è necessario recarsi, presso l’interfaccia di Home Assistant, alla voce “Configurazione” > “Integrazioni” di Home Assistant, poi scegliere “deCONZ“. Apparirà l’elenco dei dispositivi (non delle entità, ma proprio dei dispositivi fisici) sin qui integrati tramite deCONZ.

Identificare e selezionare con un click la riga relativa al “Cube” (si riconosce solitamente dalla dicitura “sensor_cube“):

Home Assistant - Integrazioni - deCONZ - Elenco dispositivi - Xiaomi Cube

Una volta entrati nella scheda di dettaglio del “Device” si noteranno sostanzialmente due cose:

  • la lista delle entità ad esso associate;
  • la lista degli eventi ad esso associati.

Di entità, come già detto prima, ce ne sarà soltanto una, un sensore relativo allo stato di carica della batteria:

Home Assistant - Integrazioni - deCONZ - Elenco dispositivi - Xiaomi Cube - Dettagli entità

Ciò che invece maggiormente ci interessa è la sezione che troviamo successivamente, ovvero l’elenco completo degli stati forniti dal Cube attraverso deCONZ:

Home Assistant - Integrazioni - deCONZ - Elenco dispositivi - Xiaomi Cube - Stati

Come si può facilmente constatare, nella lista sono presenti tutti i cambi di stato possibili: rotazioni, ribaltamenti da faccia a faccia, ribaltamenti generici di 90 o 180 gradi, scuotimenti e quant’altro.


Per definire un’automazione è sufficiente cliccare su uno o più dei tasti proposti per ottenere automaticamente il trigger voluto; quindi, in sostanza, non è necessario far altro che seguire l’interfaccia. A scopo puramente didattico vediamo però come scoprire gli ID evento e device (qualora ci servisse il codice YAML o comunque tali coordinate.

Dopo aver cliccato su uno dei tasti (diciamo a mo’ di esempio “Device shaken“, ovvero scuotimento) si accede alla maschera di definizione dell’automazione. Cliccando i tre puntini in alto a destra nel box trigger sarà possibile senezionare “Edit as YAML”:

Home Assistant - Integrazioni - deCONZ - Elenco dispositivi - Xiaomi Cube - Automazione trigger

il che permette di dare accesso all’equivalenza in notazione YAML:

Home Assistant - Integrazioni - deCONZ - Elenco dispositivi - Xiaomi Cube - Automazione trigger YAML

Nell’esempio, questi sono i dati derivati:

device_id: 159b79bcc6ae408188ac377245e76c60
domain: deconz
platform: device
type: remote_gyro_activated
subtype: ''

Identifichiamo facilmente:

  • dominio: deconz
  • ID device: 159b79bcc6ae408188ac377245e76c60
  • ID evento (type): remote_gyro_activated

A questo punto laddove definissimo un’automazione, il trigger sarebbe:

automation:
  alias: "automazione scuotimento cube"
  trigger:
    - platform: device
      device_id: 159b79bcc6ae408188ac377245e76c60
      domain: deconz
      type: remote_gyro_activated
      subtype: ""
  condition: []
  action: []

Consentendoci quindi la libertà di scrittura che eventualmente possiamo cercare.

Ringraziamenti

Si ringrazia Mauro per averci ispirato la redazione della presente guida.


Home Assistant Official Logo ATTENZIONE: 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.


Telegram News Channel