Per oltre dieci anni Homebridge è stato il modo non ufficiale ma più affidabile per portare nell’app Casa di Apple tutti i dispositivi smart che i produttori, per pigrizia o per scelta commerciale, hanno deciso di non rendere compatibili con HomeKit. Si tratta di un server Node.js leggero, da girare su un Raspberry Pi, una NAS Synology, un Mac sempre acceso o un container Docker, che dialoga con HAP (HomeKit Accessory Protocol) e fa apparire ai dispositivi Apple un finto bridge zeppo di accessori, costruiti tramite oltre quattromila plugin community.
La versione 2.0, dopo una beta lunghissima, cambia il quadro in modo netto. Adesso Homebridge non è più solo un bridge HomeKit, ma anche un bridge Matter, costruito sulla libreria open source matter.js. Questo significa che gli stessi plugin che fino a ieri esponevano i tuoi sensori Xiaomi o le tue luci Tuya solo a Siri possono ora pubblicarli, simultaneamente, anche su Google Home, Amazon Alexa, Samsung SmartThings e Home Assistant.
Sotto il cofano cambia anche il motore, ovvero HAP-NodeJS v1.0.0, Node.js 22 o 24 come minimo, avahi come MDNS advertiser di default sui sistemi Linux, e una serie di API che obbligano i plugin a essere aggiornati. Per chi gestisce un setup importante con venti o trenta plugin attivi, vale la pena capire cosa va davvero verificato prima di lanciare l’aggiornamento.
L’architettura che regge tutto, Node.js, plugin e child bridges
Homebridge gira come un singolo processo Node.js che agisce da bridge HAP, mantenendo aperta una connessione mDNS sulla rete locale e rispondendo alle richieste dell’app Casa quando questa interroga i dispositivi. Ogni plugin viene caricato dinamicamente da npm, dichiara una platform o uno o più accessory tramite l’API di Homebridge, e parla con i servizi del produttore (cloud Tuya, MQTT broker, API ZigBee2MQTT, qualsiasi cosa) per tradurre stato e comandi nel formato che HomeKit si aspetta.
Il limite duro imposto da Apple è di 150 accessori per ogni singolo bridge, ed è qui che entra in gioco il sistema dei child bridges, introdotto nelle ultime versioni della 1.x e diventato fondamentale nella 2.0. Ogni plugin può essere isolato in un proprio processo Node.js separato, con una propria coppia username/port nel config.json, e si presenta a HomeKit come un bridge indipendente da accoppiare con un suo QR code.
Il vantaggio è duplice. Se un plugin va in crash, non trascina con sé tutto Homebridge, e il tempo di risposta al comando “apri l’app Casa” non è più limitato dal plugin più lento del lotto, perché ogni child bridge risponde in parallelo. Il costo è in termini di RAM, perché ogni processo aggiuntivo consuma 20-30 MB, e su un Raspberry Pi 4 da 4 GB con quindici child bridge attivi questo significa un buon mezzo gigabyte solo per la base.
Matter come opt-in per bridge, non come modalità globale
Il cambio principale della 2.0 è la pubblicazione su Matter. Matter non sostituisce HAP, non riscrive nulla, e non costringe a ripensare la configurazione esistente. Si tratta di un blocco aggiuntivo, opzionale, che puoi inserire in bridge (il bridge principale) oppure dentro _bridge di uno specifico plugin che gira in child bridge, e che fa partire un server Matter separato sulla porta che decidi tu, annunciato sulla LAN tramite mDNS.
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"matter": {
"enabled": true,
"port": 5540
}
}
}
Da quel momento il bridge espone un secondo QR code Matter, scansionabile da Casa di Apple, Google Home, Amazon Alexa, SmartThings o qualsiasi altro controller compatibile, e grazie alla logica multi-admin di Matter più controller possono adottare contemporaneamente lo stesso bridge senza esclusione. I plugin decidono autonomamente se pubblicare anche su Matter chiamando api.matter invece (o in aggiunta) ad api.hap, e quelli che non sono stati aggiornati continuano a funzionare solo via HAP, esattamente come prima.
I tipi di dispositivo già supportati lato Matter coprono lampadine on/off, dimmerabili e RGBW, switch, prese, sensori (movimento, contatto, temperatura, umidità, luce, perdite, fumo/CO, qualità dell’aria), serrature, termostati, ventilatori e tapparelle, mentre telecamere e TV restano per ora solo via HAP perché Matter non li copre ancora.
Cosa rompe l’aggiornamento, HAP-NodeJS v1, mDNS e plugin vecchi
Sotto il cofano, Homebridge 2.0 monta HAP-NodeJS v1.0.0, e qui arrivano i cambiamenti più scomodi per chi gestisce molti plugin. Il pattern storico di accedere agli enum direttamente dalla classe Characteristic, ad esempio Characteristic.Perms, è stato rimosso. Ora bisogna passare per api.hap.Perms, api.hap.Formats e api.hap.Units, e i plugin non aggiornati semplicemente non caricano più.
Anche Characteristic.getValue() è scomparso a favore di Characteristic.value, mentre BatteryService è stato sostituito da Battery, accessory.updateReachability() non esiste più (la reachability non è più supportata da HomeKit) e Accessory.getServiceByUUIDAndSubType() è finito dentro il più semplice accessory.getService(name).
Per i requisiti runtime, Homebridge 2.0 chiede Node.js 22.12 o successivo, oppure Node.js 24, e i plugin ready for v2 dichiarano nel loro package.json la stringa "homebridge": "^1.6.0 || ^2.0.0" dentro il campo engines. Sul lato discovery di rete, il default su Linux passa da Bonjour HAP ad avahi, con fallback su ciao se avahi non è disponibile, e questo cambia il comportamento del no response su alcune reti, soprattutto quelle con WiFi mesh aggressivo o con segmentazione VLAN.
Se prima dell’upgrade preferisci mantenere Bonjour HAP, la voce Settings → mDNS Advertiser nella UI Homebridge ti permette di forzarlo prima ancora di aggiornare al ramo 2.0, evitando sorprese al primo riavvio.
Il workflow per aggiornare senza spegnere casa
Il workflow consigliato dal team Homebridge per chi ha venti o trenta plugin attivi si articola in tre passaggi.
- Backup completo della config. Dalla UI vai su
Backup/Restore, scarichi un archivio.tar.gzconconfig.json, persist storage e accessori cached, e lo metti in un posto separato dal Pi. - Verifica della readiness dei plugin. Sempre nella UI, sotto
Plugins, ogni plugin mostra un badge che indica se è già compatibile con la 2.0 (presenza di^2.0.0nel campoengines.homebridgedel suopackage.json). I plugin che non hanno il green tick sono candidati a smettere di funzionare dopo l’upgrade. - Isolamento dei plugin a rischio in child bridge. Se un plugin critico, ad esempio quello che controlla la serratura della porta, non ha ancora il green tick, attivalo come child bridge dalla sua schermata di configurazione, in modo che un suo eventuale crash non blocchi tutto Homebridge.
Solo a questo punto si procede con l’upgrade vero e proprio, idealmente prima sostituendo Node.js (hb-service update-node) e poi Homebridge (hb-service update). Per chi gira su Docker, l’immagine homebridge/homebridge:latest è già allineata alla 2.0 stabile, e il flag -e HOMEBRIDGE_INSECURE=1 rimane indispensabile se vuoi continuare a controllare gli accessori dalla web UI invece che solo dall’app Casa.
Conviene passare alla versione 2.0?
Per chi usa Homebridge come ponte solo su HomeKit, la 2.0 non è strettamente obbligatoria nel breve termine. La branch 1.x continua a ricevere security update e la maggior parte dei plugin funziona ancora benissimo, soprattutto se non hai voglia di rimettere mano alla config.
Il vero argomento a favore dell’upgrade è il supporto Matter, perché significa smettere di pagare il tax di duplicazione tipico di chi mantiene plugin paralleli per Casa di Apple e per Google Home o Alexa, e iniziare a esporre un singolo bridge a tutti gli ecosistemi attraverso un protocollo standard, sostenuto dalla Connectivity Standards Alliance.
In una casa mista, dove convivono iPhone e Android, Apple TV e dongle Chromecast, watchOS e Wear OS, questo cambia la qualità della vita digitale. Un comando vocale a Google Assistant da uno smart display in cucina e un automatismo HomeKit sull’iPhone leggono lo stesso stato dispositivo, senza incoerenze, senza ritardi, senza la classica scena dello smart bulb che è “spento” in un’app e “acceso” in un’altra.
Il consiglio è di procedere a tappe. Prima ti aggiorni a Homebridge 2.0 mantenendo solo HAP attivo, ti dai una settimana per verificare il comportamento dei plugin, poi attivi Matter prima sul bridge principale e infine, uno alla volta, sui child bridge dei plugin più maturi. La parte più delicata non è il codice, è il pairing, perché ogni controller Matter chiede un riaccoppiamento con un nuovo QR code, e questo va pianificato con calma.
