HomemanagerHomemanager Docs
Download on the App Store
GuideEntwickler

Child Bridges

Plugins isolieren, Abstürze verhindern und das 150-Geräte-Limit umgehen. Schritt-für-Schritt-Anleitung für Homemanager, Webinterface und config.json.

Child Bridges

Standardmäßig führt Homebridge alle installierten Plugins gemeinsam in einem einzigen Node.js-Prozess aus. Kommt es bei einem Plugin zu einem unbehandelten Fehler oder bricht eine Verbindung ab, kann der gesamte Server abstürzen. In Apple Home sind dann alle Zubehöre gleichzeitig nicht mehr erreichbar.

Mit einer Child Bridge lagert Homebridge ein Plugin in einen eigenständigen Betriebssystem-Prozess aus. Homebridge überwacht diesen Unterprozess: Stürzt das Plugin ab, startet Homebridge nur diesen Teilprozess neu. Das restliche Zuhause bleibt ohne Unterbrechung erreichbar.

Warum Child Bridges sinnvoll sind

  1. Ausfallsicherheit im Alltag: Stürzt ein Plugin ab oder blockiert eine Netzwerkanfrage, betrifft das nur diesen einen Unterprozess. Alle anderen Schalter, Sensoren und Lampen bleiben erreichbar.
  2. Kürzere Reaktionszeiten in Apple Home: Beim Öffnen der Apple Home App fragt iOS den Status aller Geräte einer Bridge ab. Befinden sich alle Plugins auf der Haupt-Bridge, verzögert ein langsamer Cloud-Dienst die Antwort aller übrigen Geräte. Child Bridges fragt Apple Home parallel ab, sodass lokale Geräte sofort schalten.
  3. 150-Geräte-Limit in Apple Home umgehen: Apple begrenzt jede HAP-Bridge auf 149 Zubehöre (150 inklusive der Bridge selbst). Mit Child Bridges lässt sich diese Grenze aufteilen, da jedes ausgelagerte Plugin in Apple Home als separate Bridge zählt.
  4. Bessere Lastverteilung: Node.js verarbeitet Aufgaben in einem einzelnen Thread. Child Bridges verteilen rechenintensive Aufgaben wie Kamera-Transcoding (FFmpeg) oder häufige Statusabfragen auf mehrere Prozessorkerne.
  5. Schnellere Neustarts nach Änderungen: Wer Einstellungen an einem Plugin ändert, startet nur dessen Prozess neu, statt die gesamte Homebridge-Instanz kurzzeitig vom Netz zu trennen.

Am wenigsten Aufwand macht die Auslagerung direkt bei der Installation. Homemanager fragt nach jedem Plugin-Download automatisch, ob dafür eine eigene Child Bridge angelegt werden soll. Das spart das spätere Neuzuweisen von Räumen in Apple Home.

Child Bridge einrichten

Jede Child Bridge benötigt einen eigenen TCP-Port sowie eine eigene virtuelle MAC-Adresse im Netzwerk und wird separat in Apple Home gekoppelt.

Einrichtung in Homemanager

In Homemanager gibt es zwei Wege, um eine Child Bridge einzurichten:

  • Direkt bei der Plugin-Installation: Lädst du eine Erweiterung über den Integration Store, fragt dich Homemanager nach dem Download automatisch, wie das Plugin betrieben werden soll: auf der Haupt-Bridge oder als isolierte Child Bridge. Bestätigst du die Child Bridge, sichert die App vorab die Konfiguration und richtet den Prozess ein.
  • Nachträglich über den Tab System: Bereits vorhandene Integrationen lassen sich jederzeit manuell über die Bridge-Verwaltung auslagern.
Bridges Übersicht im Tab System in Homemanager
1. Tab System mit Bridges-Liste
Neuer Bridge Assistent mit automatischem Backup und Integrationsauswahl
2. Automatisches Backup & Auswahl
Bridge-Detailansicht mit Status, Steuerung und Apple Home Kopplung
3. Status, Neustart & Kopplung

Ablauf für das Auslagern bestehender Integrationen:

  1. Öffne in Homemanager den Tab System. Im Bereich Bridges siehst du deine Haupt-Bridge sowie alle aktiven Child Bridges.
  2. Tippe im Bereich Bridges auf das Menü (Drei-Punkte-Symbol) und wähle Neue Bridge hinzufügen.
  3. Homemanager legt im ersten Schritt automatisch ein Backup deiner Homebridge-Konfiguration an.
  4. Wähle im zweiten Schritt die installierte Integration aus, die du auslagern möchtest.
  5. Nach dem Speichern startet die Bridge. In der Detailansicht weist der gelbe Hinweis Pending pairing darauf hin, dass die Bridge noch mit Apple Home verbunden werden muss.
  6. Tippe auf Apple Home Pairing, um den QR-Code anzuzeigen und die Bridge in Apple Home hinzuzufügen. Ausführliche Details dazu findest du in der Kopplungs-Anleitung für Apple Home.
Download on the App StoreHomemanager kostenlos im App Store laden

Einrichtung über die Weboberfläche (Config UI X)

  1. Öffne die Homebridge-Weboberfläche im Browser.
  2. Wechsle zum Reiter Plugins.
  3. Klicke beim gewünschten Plugin auf das Schraubenschlüssel-Symbol (Einstellungen).
  4. Wähle den Menüpunkt Bridge-Einstellungen.
  5. Aktiviere die Option Als Child Bridge ausführen und klicke auf Speichern.
  6. Nach dem automatischen Neustart des Prozesses erscheint auf dem Dashboard eine Kachel für die neue Child Bridge.
  7. Klicke auf das Bridge-Symbol, um den QR-Code anzuzeigen, und scanne ihn mit der Apple Home App.

Manuelle Konfiguration in der config.json

Wer Homebridge ohne Webinterface verwaltet, richtet Child Bridges direkt in der config.json ein. Dazu kommt ein _bridge-Block in den jeweiligen Eintrag unter platforms oder accessories:

/var/lib/homebridge/config.json
{
  "platforms": [
    {
      "platform": "Shelly",
      "name": "Shelly",
      "_bridge": {
        "username": "0E:8A:2B:3C:4D:5E",
        "port": 51830,
        "name": "Shelly Bridge"
      }
    }
  ]
}
  • username: Eine eindeutige, frei gewählte MAC-Adresse im Format XX:XX:XX:XX:XX:XX. Sie darf im Netzwerk noch nicht von einer anderen Bridge verwendet werden.
  • port: Ein freier TCP-Port für die Kommunikation mit Apple Home.
  • name: Ein optionaler Anzeigename für die Bridge in Apple Home.

Starte Homebridge nach der Bearbeitung neu. Der Kopplungscode entspricht standardmäßig der PIN deiner Haupt-Bridge (aus dem Bereich bridge.pin der config.json).

Wichtig bei nachträglicher Umstellung

Auswirkungen auf Räume, Szenen und Automationen:
Wird ein bereits gekoppeltes Plugin nachträglich in eine Child Bridge umgewandelt, stuft Apple Home die Zubehöre als neu ein.
Raumzuordnungen, Gerätenamen, Favoriten sowie alle bestehenden Szenen und Automationen, die diese Geräte nutzen, gehen in Apple Home verloren. Sie müssen einmalig neu konfiguriert werden.

Verwaltung im laufenden Betrieb

  • Status und Steuerung: Ein grüner Indikator in Homemanager signalisiert, dass der Prozess läuft. Über die Buttons Neustart und Stopp lässt sich die Bridge isoliert steuern, ohne den Hauptserver anzurühren.
  • Pending pairing: Dieser Hinweis erscheint, solange die Bridge zwar auf dem Server gestartet, aber noch nicht in Apple Home gekoppelt ist. Die Geräte des Plugins tauchen erst in deinem Zuhause auf, sobald der QR-Code gescannt wurde.
  • Arbeitsspeicher beachten: Jeder Child-Bridge-Prozess belegt etwa 20 bis 30 MB RAM. Bei Servern mit knappem Arbeitsspeicher (wie älteren Raspberry-Pi-Modellen) sollte die Gesamtzahl der Unterprozesse im Blick behalten werden.
  • Netzwerk und Ports: Jede Child Bridge öffnet einen eigenen Port. Wer Homebridge in Docker betreibt, sollte den Host-Netzwerkmodus (--net=host) nutzen, damit die Ports der Child Bridges ohne manuelle Portweiterleitungen erreichbar sind. Treten Erkennungsprobleme auf, hilft oft das Anpassen des mDNS-Advertisers wie in der Anleitung zu „Keine Antwort“ beschrieben.

Kopplung mit Apple Home

Schritt-für-Schritt-Anleitung zum Koppeln von Haupt- und Child Bridges mit deinem Apple-Zuhause.

Keine Antwort in Apple Home

Ursachen und Lösungen, wenn Zubehöre oder Bridges als nicht erreichbar angezeigt werden.

Startprobleme beheben

Hilfe bei Abstürzen, fehlerhafter Syntax und Boot-Loops anhand der Server-Logs.

Homebridge Wiki: Child Bridges

Offizielle Dokumentation des Homebridge-Entwicklerteams auf GitHub.

Plugins finden & einrichten

Kriterien für stabile Homebridge-Plugins: Verified-Siegel, Node.js-Kompatibilität und Anleitungen für Homemanager, Webinterface und Terminal-CLI.

System & Software aktualisieren

So aktualisierst du Homebridge Core, Homebridge UI, Node.js LTS und Plugins sicher: Schritt-für-Schritt-Anleitung für Homemanager, Webinterface und Terminal.

Auf dieser Seite

Child BridgesWarum Child Bridges sinnvoll sindChild Bridge einrichtenEinrichtung in HomemanagerEinrichtung über die Weboberfläche (Config UI X)Manuelle Konfiguration in der config.jsonWichtig bei nachträglicher UmstellungVerwaltung im laufenden BetriebWeiterführende Links