“config.json”: capire il file di configurazione di Homebridge

Abstract

Homebridge basa per intero la propria configurazione – ovvero, in ultima analisi, gli accessori messa a disposizione di HomeKit (quindi sull’applicazione “Casa” di Apple iOS) – su un singolo file di testo scritto in notazione json dal nome “config.json”, indipendentemente dal tipo di installazione effettuata (su Raspberry, Windows, Docker ecc.).

Tale file si compone sostanzialmente di tre blocchi (tutti e tre contemporaneamente necessari, ognuno sequenziale all’altro):

• il blocco che definisce le impostazioni dell’istanza Homebridge (nome, MAC Address, porta TCP/IP, PIN HomeKit);
• il blocco che definisce eventuali “piattaforme” e relativi “accessori”;
• il bocco che definisce eventuali “accessori” che non necessitino di “piattaforme”.

ATTENZIONE. Nella stragrande maggioranza dei casi se Homebridge non funziona più dopo la modifica al config.json è perché al suo interno sono stati commessi uno o più errori di semantica o di sintassi. Per lo più, spesso si tratta di virgole mancanti (o in eccesso) o di parentesi erronee (graffe e quadre aperte e non chiuse, o viceversa). Fare SEMPRE riferimento a jsonlint.com per la validazione del proprio config.json.

N.b. Clicca qui per scaricare un unico file già pronto valido come traccia iniziale.

Impostazioni dell’istanza Homebridge

Le impostazioni dell’istanza Homebridge sono solitamente in testa al file config.json.
Un esempio:

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

Il campo Name è dedicato alla descrizione che il bridge otterrà all’interno di HomeKit, quindi dentro l’applicazione “Casa” di Apple iOS:

Il campo Username identifica invece il MAC Address del BRIDGE virtuale rappresentato da Homebridge; la Porta, quella sulla quale comunicherà tramite rete domestica. Infine, il PIN, necessario per aggiungere il BRIDGE a HomeKit presso l’applicazione “Casa” di Apple iOS.

Blocco “piattaforme”

Per piattaforma si intende solitamente un insieme di sensori/attuatori/dispositivi della stessa famiglia.
Il (secondo) blocco di codice json presso il file di configurazione è solitamente analogo al seguente esempio:

"platforms": [
  {
    "platform" : "PhilipsHue",
    "name" : "Hue"
  }
]

Solitamente, all’interno di questo blocco trovano posto uno o più accessori per ogni piattaforma definita.

Nb. ogni aggiunta di elementi all’interno della configurazione ovviamente prevede che il relativo plugin (in questo caso quello dedicato a “PhilipsHue”) sia debitamente installato sul sistema.

Nb. questi blocchi vanno assemblati in un unico file json. Clicca qui per scaricare un unico file già pronto.

Blocco “accessori”

Gli accessori sono singoli elementi definiti a livello di configurazione:

"accessories": [
  {
    "accessory": "WeMo",
    "name": "Coffee Maker"
  }
]

Ogni accessorio definisce se stesso e nient’altro.

Nb. ogni aggiunta di elementi all’interno della configurazione ovviamente prevede che il relativo plugin (in questo caso quello dedicato a “WeMo”) sia debitamente installato sul sistema.

Nb. questi blocchi vanno assemblati in un unico file json. Clicca qui per scaricare un unico file già pronto.

Dove trovare il file di configurazione

Dipende, a questa domanda non c’è una sola risposta.
Innanzitutto, per scaricare un file di configurazione “di base” (vuoto ma funzionante per il primo avvio di Homebridge), clicca qui.

In caso si sia installato Homebridge su Raspberry seguendo in toto questa nostra guida, il file di configurazione si troverà in due posizioni diverse:

/var/homebridge/

per la configurazione del servizio con avvio automatico al boot, mentre presso

~/.homebridge/

per l’istanza da lanciare manualmente per effettuare test e sperimentazioni.

Su Windows, invece, è possibile trovare il file di configurazione presso:

%userprofile%\.homebridge

Infine, su Apple Mac OS X il file config.json è solitamente posizionato presso il percorso:

/Users/YourUsername/.homebridge

Ovviamente qualsiasi personalizzazione in fase di installazione (su qualsiasi ambiente) può determinare un cambiamento dei percorsi sopracitati.

Consigli utili

In primis, si consiglia di decidere a priori le informazioni da includere nel blocco iniziale di definizione delle impostazioni di Homebridge: modifiche in fasi successive causeranno il malfunzionamento del BRIDGE presso l’applicazione “Casa”, obbligando a ripetere l’operazione di inserimento del BRIDGE nell’applicazione e obbligando di conseguenza l’utente a riconfigurare eventuali personalizzazioni e/o automazioni precedentemente definite.

Si ricordi sempre che qualsiasi modifica effettuata al file di configurazione è valida a partire dalla successiva esecuzione di Homebridge.

Si consiglia inoltre di effettuare sempre backup del file di configurazione man mano che “evolve” nel tempo. Infine, prima di effettuare qualsiasi modifica, è sempre bene “validare” il file utilizzando l’interfaccia del sito jsonlint.com.