Come installare e configurare Homebridge su Apple macOS

6 minuti di lettura
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
  • Un computer Apple 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:
  • Computer Apple con sistema operativo macOS
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 su Apple macOS è necessario prima installare XCode, homebrew e Node.js, dopodiché è possibile installarlo, configurarlo per il primo avvio, configurare il processo per l’auto avvio a fronte dell’accensione del computer Mac, prendere dimestichezza con i comandi più tipici.

Homebridge Logo


Logo Apple HomeKitATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica ad Apple Homekit, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

Procedimento

  1. Installare XCode
  2. Installare homebrew
  3. Installare Node.js
  4. Installare ed eseguire HomebridgeErrori di installazione e soluzioni
  5. Creare il file di configurazione config.json
  6. Aggiungere Homebridge al proprio iPhone e/o iPad
  7. Configurare Homebridge in autostart al boot
  8. ManutenzioneCome aggiornare i plugin
  9. Risoluzione dei problemiCreare e consultare i file di log
    1. L’applicazione “Casa” visualizzare sempre “in aggiornamento…”
    2. L’applicazione “Casa” segnala di inizializzare il dispositivo
  10. Configurazione

1. Installare XCode

Aprire il seguente link e cliccare su “View in Mac App Store“.
Scaricare e installare il software.

2. Installare homebrew

E’ ora necessario installare “homebrew”, un semplice software per la gestione dei package.
Eseguire l’applicazione “Terminale” (o “Terminal“) sul proprio Mac, dopodiché eseguire il seguente comando:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Nota: in caso di problemi durante l’installazione, è possibile effettuarla scaricando direttamente il package. Questa guida potrebbe tornar utile.

3. Installare Node.js

Sempre tramite “Terminale”, eseguire il seguente comando:

brew install node

4. Installare ed eseguire Homebridge

Al termine della precedente installazione, sempre da “Terminale” eseguire il seguente comando:

  • in caso si si macOS Sierra o precedenti:
npm -g install homebridge
  • ATTENZIONE: in caso si usi macOS High Sierra o macOS Mojave, usare invece questo comando:
npm -g install homebridge --unsafe-perm

attendere il termine della procedura.

Errori di installazione E SOLUZIONI

MDNS install script error

Durante il passo di installazione potrebbe emergere il seguente errore:

ERR! node-gyp rebuild","Failed at the mdns@2.3.3 install script.

Per risolverlo:

  1. Aprire XCode
  2. Dal menu di XCode, aprire “Open developer tool” > “More developer tools”
  3. Eseguire il login col vostro Apple ID
  4. Una volta autenticati, scaricate e installate gli “Xcode command line tools” relativi alla vostra versione di macOS
  5. Una volta terminata l’installazione, riavviate il Mac
  6. Ritentate il passo di installazione di Homebrid ge

Ora la procedura dovrebbe concludersi correttamente.

5. Creare il file di configurazione config.json

Da “Terminale”, eseguire il seguente comando:

nano /Users/YourUsername/.homebridge/config.json

dove “YourUsername” è il vostro nome utente presso macOS.

All’interno dell’editor che si aprirà, inserire la seguente configurazione:

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

Quindi uscire e salvare (command+X, yes, invio).

Nb. In caso si crei il file config.json in una locazione sbagliata, il path corretto verrà indicato (unitamente a un errore) al primo avvio di Homebridge.

6. Aggiungere Homebridge al proprio iPhone e/o iPad

Eseguire ora, per la prima volta, Homebridge.
Da “Terminale”, eseguire il seguente comando:

homebridge

Se non verrà segnalato alcun errore, sarà giunto il momento di collegare al proprio iPhone e/o iPad il BRIDGE appena creato con Homebridge.

All’avvio, Homebridge presenta sul terminale 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 computer che ospita l’Homebridge appena installato, eseguire l’applicazione “Casa” sul proprio iPhone e/o iPad.
Tappare poi “aggiungi accessorio”:

Luce Apple HomeKit - Fullscreen

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! 😉

7. Configurare Homebridge in autostart al boot

Ora che la prima configurazione e l’aggiunta su iPhone e/o iPad è completata, è necessario configurare Homebridge come servizio, in modo che non debba essere lanciato manualmente ma si avvii automaticamente (e rimanga avviato) all’accensione del computer.

Bloccare l’esecuzione di Homebridge precedentemente lanciato tramitecommand+X, tornando così al prompt dei comandi.

È necessario creare un file launchd ad hoc per Homebridge presso il path ~/Library/LaunchAgents.
Da Terminale eseguire il seguente comando:

nano ~/Library/LaunchAgents/com.homebridge.server.plist

e inserire nell’editor il seguente testo, avendo cura di sostituire username con il vostro nome utente presso macOS:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>RunAtLoad</key>
        <true/>
    <key>KeepAlive</key>
        <true/>
    <key>Label</key>
        <string>com.homebridge.server</string>
    <key>ProgramArguments</key>
        <array>
             <string>/usr/local/bin/homebridge</string>
             <string>-I</string>
        </array>
    <key>StandardOutPath</key>
        <string>/Users/username/.homebridge/logfile.log</string>
    <key>StandardErrorPath</key>
        <string>/Users/username/.homebridge/logfile.log</string>
    <key>EnvironmentVariables</key>
        <dict>
        <key>PATH</key>
            <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME</key>
            <string>/Users/username</string>
        </dict>
</dict>
</plist>

Chiudere e salvate (command+x, yes, invio).
Ora è necessario modificare i permessi della cartella ~/Library/LaunchAgents e del file ~/Library/LaunchAgents/com.homebridge.server.plist:

sudo chown $(whoami) ~/Library/LaunchAgents
sudo chown $(whoami) ~/Library/LaunchAgents/com.homebridge.server.plist
sudo chmod 700 ~/Library/LaunchAgents
sudo chmod 600 ~/Library/LaunchAgents/com.homebridge.server.plist

Ora riavviate il Mac.
Al riavvio, Homebridge si avvierà da solo e, in caso di crash, si riavvierà da solo.

Per avviare eventualmente Homebridge in modo manuale, utilizzare da Terminale il seguente comando:

launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist

Per fermarlo, invece:

launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist

Per effettuare uno start/stop manuale del servizio automatico, utilizzare il seguente comando:

launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist && launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist

8. Manutenzione

Come aggiornare i plugin

Periodicamente i plugin di Homebridge (se non Homebridge stesso!) hanno necessità di essere aggiornati.
Per verificare quali siano eventualmente in ritardo sull’aggiornamento, utilizzare il comando:

npm -g outdated

Per aggiornare un plugin specifico, utilizzare il comando:

sudo npm -g update [homebridge | name-of-plugin]

Per forzare un aggiornamento, è possibile reinstallare direttamente il plugin in questione:

sudo npm -g install [homebridge | name-of-plugin]

Nota: si consiglia sempre di effettuare gli aggiornamenti fermando prima Homebridge. Si ricorda che ogni aggiornamento può determinare cambiamenti a livello di sintassi e/o semantica di configurazione. È pertanto sano leggere con attenzione le release note delle nuove versioni dei plugin o di Homebridge stesso, prima di effettuare qualunque aggiornamento.

9. 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” visualizzare sempre “in aggiornamento…”

Talvolta può capitare che l’applicazione “Casa” visualizzi uno stato “in aggiornamento…” di durata indefinita. Questo può essere causato dall’entrata in “Sleep Mode” del Mac. Per evitare questo, eseguire il seguente comando:

sudo systemsetup -setcomputersleep Never
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.


Logo Apple HomeKitATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica ad Apple Homekit, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

🔻 Clicca QUI per commentare l'articolo. 🔻