Come installare e configurare Homebridge su Raspberry Pi

SCOPI DELLA GUIDA:
  • Installare e configurare Homebridge, quindi dotarsi di un HUB personale compatibile Apple HomeKit
  • Livello di difficoltà: medio
CONCETTI AFFRONTATI:
  • installazione e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
  • Rete Wifi connessa ad Internet
  • Raspberry Pi configurato e collegato alla rete domestica
  • Almeno un dispositivo Apple con versione di sistema operativo iOS superiore alla 8 collegato alla rete Wifi
DISPOSITIVI FISICI UTILIZZATI:
GUIDA MAGGIORMENTE INDICATA PER:

Apple-200x200

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.

Abstract

Come spiegato nella guida dedicata alla scelta di quale HUB personale implementare, in caso si posseggano almeno un dispositivo Apple iOS è possibile, tramite l’adozione di Homebridge, dotarsi di un HUB personale personale per realizzare la propria domotica self-made.

Per installare Homebridge è necessario prima installare Node.js, una componente software fondamentale, dopodiché è possibile installare Homebridge stesso, configurarlo per il primo avvio, configurare il processo per l’auto avvio a fronte dell’accensione del Raspberry, prendere dimestichezza con i comandi più tipici.

Homebridge Logo


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

Procedimento

  1. Installare Node.js
  2. Installare ed eseguire Homebridge
  3. Aggiungere Homebridge al proprio iPhone e/o iPad
  4. Configurare Homebridge in autostart al boot
  5. Consigli operativi
    1. multiconfigurazione
    2. aggiornamento
    3. modifiche alle coordinate del BRIDGE
    4. validazione della sintassi della configurazione
  6. Risoluzione dei problemi
    1. L’applicazione “Casa” segnala di inizializzare il dispositivo

1. Installare Node.js

Una volta collegati via ssh al proprio Raspberry (utilizzando l’utenza “pi”), eseguire i seguenti due comandi:

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs

I quali provvedono ad installare la versione 8 di Node.js (ndr. ad momento della redazione della presente guida, la versione 8 è quella più stabile per l’uso Homebridge, malgrado ne esistano di più recenti).

2. Installare ed eseguire Homebridge

Installato Node.js, è ora possibile installare il software tramite il seguente comando:

sudo npm install -g homebridge --unsafe-perm

Al termine della procedura automatica, avviare per la prima volta il software (al fine di creare la directory home, anche se il comando genererà un errore) tramite il seguente comando:

homebridge

Il comando causerà un errore, come detto, perché la directory home ancora non esiste. Non bisogna preoccuparsene: a valle dell’errore, verrà creata automaticamente.

Ora è necessario creare un file di configurazione di base. Per brevità clicca qui per scaricare un unico file già pronto, il quale andrà copia-incollato dentro l’editor, il quale si esegue con:

sudo nano /home/pi/.homebridge/config.json

Dopo il copia incolla, uscire tramite control/command+X (premendo poi “Y” per salvare).

A questo punto, lanciare una seconda volta Homebridge tramite il comando:

homebridge

3. Aggiungere Homebridge al proprio iPhone e/o iPad

Ora è giunto il momento di collegare al proprio iPhone e/o iPad il BRIDGE appena creato.
Al primo (corretto) avvio, sul terminale appare una schermata analoga a questa:

Homebridge prima esecuzione

il grosso QRCode sullo schermo serve per trasmettere all’iPhone e/o iPad le “coordinate” del BRIDGE appena creato. Avendo ORA cura di trovarsi nella stessa wifi del Raspberry che ospita l’Homebridge appena installato, eseguire l’applicazione “Casa” sul proprio iPhone e/o iPad.
Tappare poi “aggiungi accessorio”:

Apple HomeKit iOS start page

Ora, con l’ausilio della telecamera del telefono/tablet, inquadrare il QRCode di cui sopra. Dopo pochi istanti, l’applicazione chiederà conferma per l’inserimento di un nuovo BRIDGE quale accessorio non certificato. Non preoccuparsene, dare consenso e terminare così la procedura.

Homebridge icon su Apple HomeKit Home appComplimenti! Se sull’app “Casa” sarà apparsa l’icona che vedete a sinistra, avete terminato la primissima configurazione del vostro BRIDGE personale.
Da qui in poi, è tutta discesa! 😉

4. Configurare Homebridge in autostart al boot

Se “fin qui tutto bene”, ovvero se l’esecuzione di Homebridge manuale viene eseguita correttamente e il bridge appare correttamente presso l’applicazione iOS “Casa”, possiamo configurare Homebridge come servizio, in modo che non debba essere lanciato manualmente ma si avvii automaticamente (e rimanga avviato) all’accensione del Raspberry.

Bloccare quindi l’esecuzione di Homebridge precedentemente lanciato tramite control/command+X, tornando così al prompt dei comandi.

Iniziamo col creare le opzioni di default per il futuro servizio:
Eseguire:

sudo nano /etc/default/homebridge

e copiare, dentro l’editor, il seguente testo:

# Defaults / Configuration options for homebridge
# The following settings tells homebridge where to find the config.json file and where to persist the data (i.e. pairing and others)
HOMEBRIDGE_OPTS=-U /var/homebridge

# If you uncomment the following line, homebridge will log more 
# You can display this via systemd's journalctl: journalctl -f -u homebridge
# DEBUG=*

Salvare ed uscire dall’editor (solitamente con cntr+X, yes, invio).
Eseguire poi il seguente comando

sudo nano /etc/systemd/system/homebridge.service

e copiare, dentro l’editor, il seguente testo:

[Unit]
Description=Node.js HomeKit Server 
After=syslog.target network-online.target

[Service]
Type=simple
User=homebridge
EnvironmentFile=/etc/default/homebridge
ExecStart=/usr/local/bin/homebridge $HOMEBRIDGE_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

ATTENZIONE: il path ExecStart è relativo al path di installazione del vostro Homebridge, il quale può essere verificato tramite il comando:

which homebridge

Corretto eventualmente l’ExecStart, salvare e uscire dall’editor.
Creare ora l’utente per eseguire il servizio, lo chiameremo “homebridge”:

sudo useradd --system homebridge

Dopodiché, creare la cartella home e copiarvi dentro l’attuale configurazione, ovvero quella che il vostro iPhone e/o iPad ha “imparato” nel passaggio precedente:

sudo mkdir /var/homebridge
sudo cp ~/.homebridge/config.json /var/homebridge/

Infine, sistemare i permessi:

sudo chmod -R 0777 /var/homebridge

Infine, abilitare il servizio e avviarlo:

sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge

Il BRIDGE è ora funzionante e in esecuzione automatica.

Per verificarlo è sufficiente aprire l’app “Casa” e verificare che l’icona del BRIDGE non riporti la dicitura “non disponibile”. A prescindere, è possibile verificare lo stato del servizio tramite il comando:

sudo systemctl status homebridge

Solitamente, il servizio è in normale esecuzione a fronte di una risposta simile:

Active: active (running)

5. Consigli operativi

Multiconfigurazione

La configurazione descritta in questa guida presenta un vantaggio operativo importante: così configurato, homebridge viene eseguito come servizio automatico a partire dalla cartella /var/homebridge, oppure come applicativo lanciato manualmente da /home/pi/homebridge (oppure ~/.homebridge) – previo stop dell’eventuale istanza eseguita automaticamente.
Così configurato, Homebridge presenta due file di configurazione (entrambi nominati config.json) nei due rispettivi percorsi sopra elencati: il primo, per l’esecuzione automatica, il secondo per quella manuale.

Dato che in esecuzione automatica il software non dà (se non presso i file di log) alcun feedback testuale, la possibilità di utilizzare l’esecuzione manuale “isolata” – anche come configurazione – permette a quest’ultima di essere utilizzata come laboratorio per le sperimentazioni, mentre quella automatica come di esercizio ordinario.

A fronte di un bisogno di variazione di configurazione di Homebridge (aggiunta e/o modifica di un plugin e/o di un accessorio), è utile eseguire la seguente mini procedura:

  1. fermare Homebridge dell’istanza automatica
  2. modificare la configurazione di quella manuale ai propri scopi
  3. eseguire quella manuale, verificando se gli effetti siano quelli attesi
  4. copiare la configurazione dell’istanza manuale sopra quella automatica
  5. riavviare l’istanza automatica.

Per far ciò:

fermare Homebridge dell’istanza automatica

sudo systemctl stop homebridge

modificare la configurazione di quella manuale ai propri scopi

sudo /home/pi/homebridge/config.json

(modificare il file, poi uscire salvando)
eseguire quella manuale, verificando se gli effetti sono quelli siano quelli attesi (tipicamente usando l’app “Casa” del telefono/tablet)

homebridge

(fermare Homebridge con ctrl/command+x)
copiare la configurazione dell’istanza manuale sopra quella automatica

sudo cp ~/.homebridge/config.json /var/homebridge/
sudo cp -r ~/.homebridge/persist /var/homebridge
sudo chmod -R 0777 /var/homebridge

riavviare l’istanza automatica

sudo systemctl daemon-reload
sudo systemctl start homebridge

Rilanciare ora l’applicazione “Casa” per verificare che il BRIDGE risponda in modo corretto.

AGGIORNAMENTO

Per effettuare l’aggiornamento di Homebridge è necessario prima interromperne l’esecuzione. In caso sia stato configurato (come sopra spiegato) come servizio automatico, il comando è il seguente:

sudo systemctl stop homebridge

Il comando da eseguire successivamente per provvedere all’update è il seguente:

sudo npm update -g homebridge
Modifiche alle coordinate del BRIDGE

La parte iniziale del file di configurazione config.json riporta solitamente un blocco simile al seguente:

"bridge": {
           "name": "Homebridge",
           "username": "CC:22:3D:E3:CE:30",
           "port": 51826,
           "pin": "031-45-154"
},

E’ importante sapere che tali informazioni, se modificate DOPO l’aggiunta del BRIDGE sull’applicazione “Casa” causano il più delle volte un blocco del funzionamento presso l’applicazione stessa. Per risolvere, è sufficiente rimuovere il BRIDGE dall’applicazione e riaggiungerlo come spiegato in questa guida (paragrafo 3).

Tale configurazione è consultabile, per l’istanza manuale, tramite il comando:

sudo nano /home/pi/homebridge/config.json

mentre per l’istanza automatica:

sudo nano /var/homebridge/config.json
Validazione della sintassi deLLA configurazione

Una delle cause più classiche del mancato funzionamento di Homebridge è il mancato rispetto delle regole semantiche del file di configurazione config.json. Tale file è scritto, per l’appunto, in notazione json, la quale può essere approfondita qui.

Prima di qualsiasi modifica al file di configurazione si consiglia sempre di effettuarne un backup e di sottoporre sempre il nuovo file alla validazione del sito Jsonlint.

Alla configurazione di Homebridge e relativo file “config.json” dedichiamo un ampia sezione a riguardo.

In base all’installazione da voi appena effettuata su Windows, il file che andrete a modificare (“config.json”) sarà posizionato presso il percorso:

/home/pi/.homebridge

6. Risoluzione dei problemi

Creare e consultare i file di log

In caso si utilizzi una configurazione di lancio automatico come da paragrafo 7, i log di esecuzione sono disponibili presso:

/Users/username/.homebridge/logfile.log

Nota: sostituire “username con il nome utente in uso su macOS.

Per consultare il file di log in tempo reale durante l’esecuzione di Homebridge, utilizzare il seguente comando:

tail -f ~/.homebridge/logfile.log
L’APPLICAZIONE “CASA” SEGNALA DI INIZIALIZZARE IL DISPOSITIVO

Questo caso, che si presenta talvolta al momento di aggiungere Homebridge all’applicazione “Casa”, si risolve banalmente modificando il campo “username” del file “config.json” e impostandolo con un valore diverso (casuale). Basterà anche solo modificare un singolo carattere, (eg. da “CC:22:3D:E3:CE:30” a “C1:22:3D:E3:CE:30“), rilanciare Homebridge ed effettuare nuovamente l’aggiunta del BRIDGE all’applicazione “Casa”.

10. Personalizzazione della configurazione

Ora è necessario provvedere alla personalizzazione della configurazione, alla quale dedichiamo un ampia sezione a riguardo.


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

🔻 Clicca QUI per commentare l'articolo. 🔻