Scopi della guida:
Concetti affrontati:
|
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
|
GUIDA INDICATA A UTENTI CON ISTALLAZIONE: |
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 1.2 | |
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
- Istanziare Ring-MQTT
- Su Home Assistant OS / Supervised
- Su Docker (su Linux/Raspeberry Pi OS)
- Uso ordinario
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à:
- tramite add-on Home Assistant OS / Supervised;
- su Docker (su host Linux, Raspberry Pi OS e altro).
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“:
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à:
inserire le proprie credenziali Ring.
Al termine della procedura automatica, la seguente schermata
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.
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:
questo è 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. |