community italiana di domotica personale
 
Integrare componenti domotici Amazon Ring a Home Assistant via MQTT

Integrare componenti domotici Amazon Ring a Home Assistant via MQTT

Scopi della guida:
  • Integrare i componenti della linea Amazon Ring a Home Assistant
  • Livello di difficoltà: medio/bassa
  • Categoria d’integrazione: Cloud Push
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
Ambienti Home Assistant HassOS-Supervised-Core
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.2

Ring-MQTT - Logo

Abstract

I componenti della linea Amazon Ring sono particolarmente apprezzati per la gestione della sicurezza domestica smart e non solo. Telecamere wireless, sistemi d’allarme, videocitofoni e altro compongono un set di componenti adottati in tutto il mondo; noi per esempio abbiamo testato il fortunatissimo Ring Intercom, un componente semplicissimo per la domotizzazione degli impianti citofono tradizionali, nonché il rinomato sistema di sicurezza Ring Alarm.

Naturalmente, gli utenti che abbiano scelto Home Assistant come proprio HUB personale per la propria domotica che posseggano delle componenti Ring fronteggeranno la necessità di integrarne le funzioni all’interno dell’HUB, così da gestirle “sotto un unico tetto”, magari in concerto con altre, molti, servizi e componenti diversi, magari con automazioni e quant’altro.

Il componente software Ring-MQTT funge da ponte (o “bridge”) tra i dispositivi di allarme, illuminazione intelligente e fotocamera Ring e un broker MQTT, consentendo così a qualsiasi strumento di automazione in grado di sfruttare il protocollo MQTT (come appunto Home Assistant) di integrarsi efficacemente con questi dispositivi. Il progetto supporta anche lo streaming video fornendo un servizio gateway RTSP che consente a qualsiasi client multimediale che supporta il protocollo RTSP di connettersi allo streaming live di una telecamera Ring o di riprodurre eventi registrati (è richiesto l’abbonamento Ring Protect per la riproduzione della registrazione degli eventi). 

N.b. Ring-MQTT non trasforma le telecamere Ring in telecamere CCTV a streaming continuo h24. Le telecamere Ring sono progettate per funzionare con i server cloud Ring per lo streaming su richiesta in base agli eventi rilevati (movimento/scampanellata) o visualizzazione interattiva: anche quando si utilizza Ring-MQTT, tutto lo streaming passa comunque attraverso i server cloud Ring e non è locale. Non è quindi adatto per l’uso con strumenti di monitoraggio NVR come motionEye, Frigate, Zoneminder o altri.

Questa guida illustra come utilizzare Ring-MQTT per integrare a Home Assistant le componenti Amazon Ring.

Si parte

Broker e client MQTT

Come suggerisce il nome, il software Ring-MQTT, per funzionare, necessita della presenza di un broker MQTT sulla rete locale sulla quale il computer che lo esegue è connesso, nonché la presenza delle funzionalità di client MQTT presso Home Assistant.

Per configurare broker e/o client MQTT su Home Assistant OS/Supervised, si faccia riferimento a questa guida.

N.b. Procedere nella presente guida senza aver provveduto a installare correttamente broker e client MQTT causerà, ovviamente, un malfunzionamento di Ring-MQTT.

Istanziare Ring-MQTT

Siamo dunque pronti a instanziare Ring-MQTT, il quale potrà essere implementato in diverse modalità:

Su Home Assistant OS / Supervised

Ring-MQTT, in presenza di un’installazione Home AssistantOS/Supervised, può facilmente essere implementato tramite l’installazione di un add-on.

Per installare l’add-on, cliccare, presso il menu, la voce:

  • Configurazione” > “Componenti aggiuntivi”  e poi sul pulsante “Raccolta di componenti aggiuntivi“.

Si tratta di accedere ad una vera e propria “vetrina” di componenti aggiuntivi (gratuiti) che, proprio come mattoncini da costruzioni, andranno ad arricchire le funzionalità del nostro HUB. Per installarlo è dunque primariamente necessario aggiungere un repository alla lista di quelli già presenti, nello specifico questo indirizzo:

https://github.com/tsightler/ring-mqtt-ha-addon

Per farlo, recarsi alla voce di menu (i tre puntini in alto a destra) “Archivi digitali” > “Aggiungi“.

Immediatamente dopo nella lista degli add-on disponibili apparirà anche la voce “ring-mqtt”. Cliccarci sopra per accedere alla scheda di dettaglio, poi cliccare su “INSTALLA“:

Home Assistant - Ring-MQTT add-on

Attendere il tempo necessario per il completamento dell’installazione. Nel mentre, non chiudere la finestra.
Al termine dell’installazione e selezionare “ESEGUI ALL’AVVIO”, “Watchdog” e, importante, anche la voce “Mostra nella barra laterale“.

Al termine dell’installazione, non avviare l’add-on: è necessario, prima, configurarlo in dettaglio.

Configurazione

La configurazione di Ring-MQTT non è particolarmente complessa ma importante. È in questa fase, infatti, che si definisco le caratteristiche di connessione del software verso il cloud Ring e dall’altra parte verso il broker MQTT.

Tale configurazione si effettua sempre dalla pagina di dettaglio dell’add-on Ring-MQTT; presso la sezione “Configurazione“, cliccando poi sui tre puntini in alto a destra, infine alla voce “Modifica in YAML“, l’add-on riporta una configurazione di default pressapoco così:

mqtt_url: mqtt://auto_username:auto_password@auto_hostname
mqtt_options: ""
livestream_user: ""
livestream_pass: ""
disarm_code: ""
enable_cameras: true
enable_modes: false
enable_panic: false
branch: addon
debug: ring-*
location_ids: []

A questo punto, se si vogliono attuare configurazioni specifiche (tutte le voci sono spiegate qui), effettuarle e salvare la configurazione, altrimenti tornare sulla scheda principale dell’add-on e avviarlo.

Autenticazione (passaggio obbligatorio)

Cliccare ora sulla barra laterale destra dell’interfaccia di Home Assistant alla voce “Ring-MQTT with video streaming“.

La pagina che si aprirà permette all’utente di creare un token di autenticazione tra il software e il cloud Amazon Ring, cosa necessaria per garantire le comunicazioni sicure.

Nella finestra che si aprirà:

Home Assistant - Ring-MQTT add-on Auth - 1

inserire le proprie credenziali Ring.
Al termine della procedura automatica, la seguente schermata

Home Assistant - Ring-MQTT add-on Auth - 2

indicherà il completamento della procedura.

Complimenti! Ring-MQTT è ora connesso con la propria configurazione cloud Amazon Ring.

N.b. Volendo è ora possibile tornare alla pagina di dettaglio dell’add-on per rimuovere la spunta “Mostra nella barra laterale“, in quanto non servirà più.

Arrivati sin qui, è possibile passare all’uso ordinario.

Vetrina - Offerte del giorno

Su Docker (su Linux/Raspeberry Pi OS)

Istanziare Ring-MQTT è piuttosto semplice, quando si usa Docker il quale, ovviamente, deve essere precedentemente installato. Installare Docker è piuttosto semplice. Ecco, a seguire, alcune guide utili ai casi più tipici:

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

N.b. Per informazioni specifiche alla configurazione presso Docker di Ring-MQTT, far riferimento alla documentazione ufficiale.

Arrivati a questo punto è possibile provvedere all’instanziamento di Ring-MQTT, il quale viene eseguito come container Docker tramite un’istanza specifica.

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.

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

Autenticazione (passaggio obbligatorio)

Prima di implementare Ring-MQTT, però, è necessario creare un token di autenticazione tra il software e il cloud Amazon Ring, cosa necessaria per garantire le comunicazioni sicure.

Creiamo innanzitutto una cartella la quale conterrà la sua configurazione.

Una volta collegati via SSH a Linux Debian o a Raspberry Pi OS tramite la propria utenza (eg. “deb“, o “pi” o altro), provvedere a creare a cartella “ring-mqtt

mkdir -p ~/ring-mqtt

A questo punto eseguiamo il seguente comando:

docker run -it --rm --mount type=bind,source=~/ring-mqtt,target=/data --entrypoint /app/ring-mqtt/init-ring-mqtt.js tsightler/ring-mqtt

All’esecuzione verrà richieste:

  • l’email e la password di accesso al cloud Ring;
  • l’url del proprio broker mqtt inclusivo di username e password d’accesso (eg. http://username:password@192.168.1.100:1883)

Il tutto verrà salvato nel file config.json all’interno della cartella appena creata (quindi in caso di errori o correzoni basterà accedere a quel file e modificarlo).

Al termine della procedura guidata, il token necessario sarà stato creato e salvato nella cartella di cui sopra.

N.b. Attenzione a non usare, nella configurazione dell’indirizzo del broker MQTT, indirizzi come 127.0.0.1:1883 o localhost:1883.

Ora siamo pronti a istanziare davvero Ring-MQTT.

Tramite comando “docker run”

Istanziamo definitivamente Ring-MQTT su Docker tramite il comando:

docker run -d --name ring-mqtt -p 8554:8554 -p 55123:55123 --mount type=bind,source=~/ring-mqtt,target=/data tsightler/ring-mqtt

Lanciato il comando, attendere il completamento del primo avvio.

Per verificare i log in tempo reale, eseguire:

docker logs ring-mqtt -f

poi, leggendo nel log un responso come il seguente:

1980-01-01T00:00:00.000Z ring-mqtt ------------------------------------------------------------------------------------------
1980-01-01T00:00:00.000Z ring-mqtt This account has access to the following locations:
1980-01-01T00:00:00.000Z ring-mqtt            XXXXXXX (XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX)
1980-01-01T00:00:00.000Z ring-mqtt                                                                                           
1980-01-01T00:00:00.000Z ring-mqtt IMPORTANT: If *ANY* alarm or smart lighting hubs at these locations are *OFFLINE* 
1980-01-01T00:00:00.000Z ring-mqtt            the device discovery process below will hang and no devices will be    
1980-01-01T00:00:00.000Z ring-mqtt            published!                                                             
1980-01-01T00:00:00.000Z ring-mqtt                                                                                           
1980-01-01T00:00:00.000Z ring-mqtt            If the message "Device Discovery Complete!" is not logged below, please
1980-01-01T00:00:00.000Z ring-mqtt            carefully check the Ring app for any hubs or smart lighting devices    
1980-01-01T00:00:00.000Z ring-mqtt            that are in offline state and either remove them from the location or  
1980-01-01T00:00:00.000Z ring-mqtt            bring them back online prior to restarting ring-mqtt.                  
1980-01-01T00:00:00.000Z ring-mqtt                                                                                           
1980-01-01T00:00:00.000Z ring-mqtt            If desired, the "location_ids" config option can be used to restrict   
1980-01-01T00:00:00.000Z ring-mqtt            discovery to specific locations. See the documentation for details.    
1980-01-01T00:00:00.000Z ring-mqtt ------------------------------------------------------------------------------------------
1980-01-01T00:00:00.000Z ring-mqtt Starting Device Discovery... 

il container sarà correttamente in esecuzione.

Complimenti! Ring-MQTT è ora connesso con la propria configurazione cloud Amazon Ring.
Arrivati sin qui, è possibile passare all’uso ordinario.

Tramite Docker Compose

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

  ring-mqtt:
    container_name: ring-mqtt
    restart: unless-stopped
    image: tsightler/ring-mqtt
    ports:
      - 8554:8554
      - 55123:55123
    volumes:
      - ~/ring-mqtt:/data 

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

docker compose up -d ring-mqtt

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

Lanciato il comando, attendere il completamento del primo avvio.

Per verificare i log in tempo reale, eseguire:

docker logs ring-mqtt -f

poi, leggendo nel log un responso come il seguente:

1980-01-01T00:00:00.000Z ring-mqtt ------------------------------------------------------------------------------------------
1980-01-01T00:00:00.000Z ring-mqtt This account has access to the following locations:
1980-01-01T00:00:00.000Z ring-mqtt            XXXXXXX (XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX)
1980-01-01T00:00:00.000Z ring-mqtt                                                                                           
1980-01-01T00:00:00.000Z ring-mqtt IMPORTANT: If *ANY* alarm or smart lighting hubs at these locations are *OFFLINE* 
1980-01-01T00:00:00.000Z ring-mqtt            the device discovery process below will hang and no devices will be    
1980-01-01T00:00:00.000Z ring-mqtt            published!                                                             
1980-01-01T00:00:00.000Z ring-mqtt                                                                                           
1980-01-01T00:00:00.000Z ring-mqtt            If the message "Device Discovery Complete!" is not logged below, please
1980-01-01T00:00:00.000Z ring-mqtt            carefully check the Ring app for any hubs or smart lighting devices    
1980-01-01T00:00:00.000Z ring-mqtt            that are in offline state and either remove them from the location or  
1980-01-01T00:00:00.000Z ring-mqtt            bring them back online prior to restarting ring-mqtt.                  
1980-01-01T00:00:00.000Z ring-mqtt                                                                                           
1980-01-01T00:00:00.000Z ring-mqtt            If desired, the "location_ids" config option can be used to restrict   
1980-01-01T00:00:00.000Z ring-mqtt            discovery to specific locations. See the documentation for details.    
1980-01-01T00:00:00.000Z ring-mqtt ------------------------------------------------------------------------------------------
1980-01-01T00:00:00.000Z ring-mqtt Starting Device Discovery... 

il container sarà correttamente in esecuzione.

Complimenti! Ring-MQTT è ora connesso con la propria configurazione cloud Amazon Ring.
Arrivati sin qui, è possibile passare all’uso ordinario.

Uso ordinario

Il grosso è fatto.

Con Ring-MQTT correttamente avviato e l’auto-discovery MQTT correttamente configurato presso Home Assistant (vedi sempre la solita guida), automaticamente presso la lista dei device e delle entità di Home Assistant cominceranno ad apparire nuovi elementi, forniti automaticamente dall’integrazione Ring-MQTT, e proiezioni digitale delle componenti Amazon Ring configurate presso il cloud Ring e relativa applicazione di gestione originale.

Per esempio:
Ring Intercom - Home Assistantquesto è l’elenco dell’entità relative ad Amazon Ring Intercom integrato su Home Assistant via Ring-MQTT.


Per tutte le informazioni di dettaglio relative all’integrazione di altre componenti (sopratutto le IP Cam), far riferimento al sito Wikipedia del componente Ring-MQTT.

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