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

Scopi della guida: Integrare il (Magic) Cube di Xiaomi/LUMI alla propria domotica Home Assistant tramite ZigBee2MQTT 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: Home Assistant ZigBee2MQTT Componente Home Assistant “MQTT“ Prerequisiti: Home Assistant configurato e funzionante ZigBee2MQTT configurato e funzionante Dispositivi fisici utilizzati: Il computer sul quale è in esecuzione Home Assistant Uno o più (Magic) Cube di Xiaomi/LUMI
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
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

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à.

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 per esempio il “solito noto” ZigBee2MQTT.

Bene: in questa guida vedremo come integrare il cube a Home Assistant tramite ZigBee2MQTT 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 ZigBee2MQTT sia già installato, in esecuzione e integrato a Home Assistant. 

Su inDomus sono disponibili guide dedicate sia all’installazione di Home Assistant che all’installazione di ZigBee2MQTT.

Dando per scontata l’installazione di ZigBee2MQTT, si dà implicitamente per scontata anche la presenza di un proprio broker MQTT (senza il quale ZigBee2MQTT, per l’appunto, non funziona) e relativa configurazione client presso Home Assistant.

Si parte

• Entità “Cube” su Home Assistant
• Come funziona

Entità “Cube” su Home Assistant

Com’è noto, integrare dispositivi ZigBee via ZigBee2MQTT su Home Assistant può avvenire in due modalità: automatica o manuale. Quella automatica prevede di utilizzare l’autodiscovery, il che evita configurazioni manuali; la seconda, manuale, prevede per l’appunto di configurare presso il file di configurazione dell’HUB il codice specifico relativo alle entità da generare.

Se si usa quella automatica, una volta associato un Magic Cube alla propria istanza di ZigBee2MQTT apparirà automaticamente, presso Home Assistant, un’entità di tipo “Sensor” la quale rappresenta il componente; viceversa, in caso si utilizzi la modalità manuale bisognerà, a tal scopo, aggiungere una configurazione del genere:

mqtt:
  - name: "cube"
    state_topic: "zigbee2mqtt/cube"
    availability_topic: "zigbee2mqtt/NOME_DEVICE/state"
    value_template: "{{ value_json.action| default('', true) }}"
    icon: "mdi:cube-outline"
    expire_after: 1

dove NOME_DEVICE sarà il nome associato al Macic Cube presso ZigBee2MQTT.

Quale che sia la strada che l’utente percorrerà, per gli esempi della presente guida assumeremo la presenza di un’entità chiamata sensor.cube. Starà poi all’utente adeguare le proprie configurazioni in funzione del nome dell’entità presente sul proprio HUB.

Come funziona

Per sfruttare a pieno le gesture di Magic Cube è necessario utilizzare le automazioni di Home Assistant, dove lo stato dell’entità rappresentante il componente funge da trigger (e da discriminante) per le stesse.

Gli stati possibili sono i seguenti (salvo ZigBee2MQTT non ne abbia inclusi di nuovi senza che poi questa guida sia stata aggiornata):

• shake (scuotimento);
• wakeup (risveglio);
• fall (caduta);
• tap (picchiettare);
• slide (scivolamento);
• flip180 (capovolgimento di 180 gradi);
• flip90 (capovolgimento di 90 gradi);
• rotate_left (rotazione sull’asse in senso antiorario);
• rotate_right (rotazione sull’asse in senso orario).

Tutte queste gesture possono essere gestite da un’unica automazione, ora vedremo come.

Automazione

Vediamo ora l’automazione “tipo” per gestire il Magic Cube:

automation:
  - alias: "Gestione Cube"
    id: "gestione_cube"
    trigger:
      - platform: state
        entity_id: sensor.cube
        to: ~
    condition: []
    action:
      - choose:
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'shake' }}"
            sequence:
              # qualcosa da fargli fare in caso di risveglio
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'wakeup' }}"
            sequence:
              # qualcosa da fargli fare al suo risveglio
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'fall' }}"
            sequence:
              # qualcosa da fargli fare se lo si lascia cadere
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'tap' }}"
            sequence:
              # qualcosa da fargli fare se lo si picchietta
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'slide' }}"
            sequence:
              # qualcosa da fargli fare se lo si fa scivolare
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'flip180' }}"
            sequence:
              # qualcosa da fargli fare se lo si ribalta di 180 gradi
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'flip90' }}"
            sequence:
              # qualcosa da fargli fare se lo si ribalta di 90 gradi
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'rotate_left' }}"
            sequence:
              # qualcosa da fargli fare se lo si gira in senso antiorario
          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'rotate_right' }}"
            sequence:
              # qualcosa da fargli fare se lo si gira in senso orario

In pratica, ogni sequence: è relativa a un innesco diverso, come si intende facilmente dal codice. Nel blocco si può quindi indicare qualsivoglia cosa; ipotizziamo di voler accendere/spegnere una Nanoleaf Hexagon integrata a Home Assistant tramite la rotazione in senso antiorario:

          - conditions:
              - condition: template
                value_template: "{{ trigger.to_state.state == 'rotate_left' }}"
            sequence:
              - service: light.toggle
                entity_id: light.nanoleaf_hexagon

e così via.

Specie con Magic Cube, il limite è la propria fantasia: lo si può utilizzare per governare, in modo gestuale, qualsivoglia servizio presente sull’HUB.