# Wie Homebridge funktioniert: Architektur, Datenfluss & Stabilität (https://docs.homemanager-app.de/de/developer/architecture)
Homebridge bindet Smart-Home-Geräte in Apple Home ein, für die der Hersteller keine HomeKit-Zertifizierung anbietet. Als lokaler Übersetzer vermittelt die Software zwischen dem Apple HomeKit Accessory Protocol (HAP) und den herstellereigenen Schnittstellen der jeweiligen Geräte.
```text
┌─────────────────────────────────────────────────────────────────┐
│ Apple Home Ökosystem (Lokal) │
│ iPhone / iPad Apple TV / HomePod (Hub) │
└──────────────────────────────┬──────────────────────────────────┘
│
Lokales HAP über LAN (Verschlüsselt)
Bonjour / mDNS Discovery (_hap._tcp)
│
┌──────────────────────────────▼──────────────────────────────────┐
│ Homebridge Server (Node.js) │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ HAP-Protokollschicht (hap-nodejs) │ │
│ │ - Meldet Zubehöre und Dienste an Apple Home │ │
│ │ - Verarbeitet Lese-, Schreib- und Status-Events │ │
│ └───────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────────────┐ │
│ │ Homebridge Core & Plugin-Laufzeit │ │
│ │ - Hauptprozess (Koordination & Web-Schnittstelle) │ │
│ │ - Isolierte Child Bridges für einzelne Plugins │ │
│ └───────────────────────────┬───────────────────────────────┘ │
└──────────────────────────────┼──────────────────────────────────┘
│
Herstellerspezifische Kommunikation
│
┌────────────────────┴─────────────────────┐
│ │
┌─────────▼─────────────┐ ┌─────────▼─────────────┐
│ Lokale Geräte-APIs │ │ Hersteller-Clouds │
│ - Zigbee / Z-Wave │ │ - Ring, Nest, Tuya │
│ - MQTT / Shelly LAN │ │ - Roborock, SwitchBot│
│ - Lokales HTTP / UDP │ │ - Externe Cloud-APIs │
└───────────────────────┘ └───────────────────────┘
```
***
## Lokale Kommunikation und Cloud-Anbindung [#lokale-kommunikation-und-cloud-anbindung]
Die Kommunikation zwischen Apple-Geräten und Homebridge läuft im Heimnetzwerk direkt über WLAN oder Ethernet ab. Steuerbefehle werden zu Hause nicht über externe Server geleitet.
Homebridge meldet sich gegenüber Apple Home als Bridge an. Du bindest die Bridge einmal zentral ein, woraufhin alle Geräte aus den installierten Plugins automatisch in deinen Räumen erscheinen.
### Lokale im Vergleich zu Cloud-basierten Plugins [#lokale-im-vergleich-zu-cloud-basierten-plugins]
Wie unabhängig das Setup vom Internet arbeitet, hängt von der Geräteschnittstelle des jeweiligen Plugins ab:
| Eigenschaft | Lokale Plugins | Cloud-basierte Plugins |
| :---------------------- | :------------------------------------------------------ | :--------------------------------------------------------------- |
| **Beispiele** | `homebridge-hue`, `homebridge-z2m`, `homebridge-shelly` | `homebridge-ring`, `homebridge-nest`, `homebridge-tuya-platform` |
| **Übertragungsweg** | Lokales Netzwerk (LAN, Zigbee, MQTT) | Verschlüsseltes HTTPS oder WebSockets über das Internet |
| **Reaktionszeit** | Unter 50 ms | 200 bis 1.000 ms |
| **Bei Internetausfall** | Steuerung funktioniert im Heimnetzwerk weiter | Keine Steuerung möglich |
| **Schnittstellen** | Lokale REST-APIs, CoAP, MQTT | OAuth2, Hersteller-Clouds, Session-Logins |
Geräte mit lokaler Steuerung schalten schneller und bleiben auch dann erreichbar, wenn die Internetverbindung ausfällt oder der Hersteller Wartungsarbeiten durchführt.
***
## Das Datenmodell von Apple Home [#das-datenmodell-von-apple-home]
Apple HomeKit bildet Geräte in einer dreistufigen Struktur ab:
```text
Accessory (Zubehör: z. B. Stehleuchte)
└── Service (Dienst: z. B. Lightbulb)
├── Characteristic (Eigenschaft: On / Schaltzustand)
└── Characteristic (Eigenschaft: Brightness / Helligkeit)
```
1. **Accessory:** Das physische oder virtuelle Gerät. Jedes Zubehör besitzt Basisdaten wie Name, Hersteller, Modell und Seriennummer.
2. **Service:** Die konkrete Funktion. Eine Mehrfachsteckdose ist ein einzelnes Zubehör mit mehreren getrennten Steckdosen-Diensten (`Outlet`).
3. **Characteristic:** Der konkrete Mess- oder Steuerwert innerhalb eines Dienstes, etwa der Schaltzustand (`On`), die Helligkeit (`Brightness`) oder eine gemessene Temperatur.
### Statusänderungen in Echtzeit [#statusänderungen-in-echtzeit]
Apple Home fragt den Gerätestatus nicht in regelmäßigen Intervallen ab. Homebridge hält stattdessen eine dauerhafte Verbindung offen und meldet Änderungen, etwa durch einen Wandschalter, sofort als Ereignis an Apple Home weiter.
***
## Die Rolle der Steuerzentrale (Home Hub) [#die-rolle-der-steuerzentrale-home-hub]
Ein Apple TV oder HomePod dient als Steuerzentrale und ergänzt Homebridge um zwei Funktionen:
```text
Unterwegs (Mobiles Internet) Zuhause (Heimnetzwerk)
┌───────────────────────────┐ ┌────────────────────────────────┐
│ iPhone / iPad │ │ Apple TV / HomePod (Hub) │
│ │ │ │
│ Apple Home App │ │ - Führt Automationen aus │
│ │ │ │ - Hält Verbindung zu Bridges │
└────────────┼──────────────┘ └──────────────┬─────────────────┘
│ │
│ Verschlüsselter iCloud-Tunnel │ Lokales Netzwerk
└── (Keine Portweiterleitung nötig) ────────────┘ (HAP)
│
┌──────────────▼─────────────────┐
│ Homebridge Server │
└────────────────────────────────┘
```
Automationen laufen lokal auf dem Home Hub. Erkennt Homebridge eine Bewegung, meldet der Server das Ereignis an den Apple TV oder HomePod. Dieser sendet den Schaltbefehl direkt im lokalen Netzwerk zurück. Das funktioniert auch dann, wenn das iPhone ausgeschaltet oder unterwegs ist.
Der Fernzugriff kommt ohne Portweiterleitungen oder DynDNS aus. Der Home Hub hält eine gesicherte Verbindung zu den Apple-Diensten. Befehle vom iPhone werden verschlüsselt an die Steuerzentrale zu Hause übermittelt, die sie lokal an Homebridge weitergibt.
***
## Warum Child Bridges die Stabilität sichern [#warum-child-bridges-die-stabilität-sichern]
In einer Standard-Installation läuft Homebridge als ein einziger Node.js-Prozess, in dem alle Plugins denselben Event Loop teilen. Bei größeren Setups stößt dieses Modell an Grenzen.
```text
Klassisches Monolith-Modell:
┌────────────────────────────────────────────────────────┐
│ Homebridge Hauptprozess │
│ │
│ Plugin A (Zigbee) Plugin B (Kamera) Plugin C (IR) │
│ │ │ │ │
│ └───────────────────┴─────────────────┘ │
│ │ │
│ Gemeinsamer Event Loop │
│ (Ein Fehler blockiert alle Zubehöre) │
└────────────────────────────────────────────────────────┘
Modernes Child Bridge-Modell:
┌────────────────────────────────────────────────────────┐
│ Homebridge Hauptprozess │
│ Koordination & Web-Schnittstelle │
└──────────────┬───────────────────┬─────────────────────┘
│ │
┌──────────────▼─────────┐ ┌──────▼─────────────────────┐
│ Child Bridge 1 │ │ Child Bridge 2 │
│ Plugin: Kamera │ │ Plugin: Zigbee │
│ - Separater Prozess │ │ - Separater Prozess │
│ - Eigener QR-Code │ │ - Eigener QR-Code │
└────────────────────────┘ └────────────────────────────┘
```
### Das 150-Zubehöre-Limit [#das-150-zubehöre-limit]
Apple begrenzt jede Bridge auf 150 Zubehöre. Da die Bridge selbst eine Kennung belegt, lassen sich höchstens 149 Geräte anbinden. Werden weitere Geräte hinzugefügt, ignoriert Apple Home diese oder bricht das Einlesen ab.
### Grenzen des gemeinsamen Prozesses [#grenzen-des-gemeinsamen-prozesses]
Wenn alle Erweiterungen in einem Prozess laufen, führt ein unbehandelter Fehler in einem einzelnen Plugin zum Absturz des gesamten Servers. In Apple Home zeigen dann alle Geräte den Status "Keine Antwort". Da Node.js Code in einem einzelnen Thread ausführt, können rechenintensive Aufgaben (wie Video-Transkodierung bei Kameras) oder blockierende Netzwerkanfragen zudem die Schaltzeiten aller anderen Sensoren verzögern.
### Wie Child Bridges diese Probleme lösen [#wie-child-bridges-diese-probleme-lösen]
Homebridge kann Plugins über Child Bridges in getrennte Subprozesse auslagern. Das bringt vier handfeste Vorteile:
* Stürzt ein Plugin ab, betrifft das nur diesen Teilprozess. Der Hauptserver und alle übrigen Bridges laufen weiter, während Homebridge den beendeten Prozess automatisch neu startet.
* Jede Child Bridge agiert wie eine eigenständige Brücke mit einem eigenen Kontingent von 149 Geräten.
* Das Betriebssystem verteilt die getrennten Prozesse auf mehrere Kerne moderner Prozessoren (etwa auf einem Raspberry Pi 4 oder 5).
* Nach Konfigurationsänderungen genügt es, die betroffene Child Bridge innerhalb weniger Sekunden neu zu starten, statt das gesamte System neu zu laden.
Jede Child Bridge wird einmalig mit eigenem QR-Code oder 8-stelligem PIN in Apple Home gekoppelt.
***
## Homebridge im Alltag verwalten: Desktop und Mobil [#homebridge-im-alltag-verwalten-desktop-und-mobil]
Die Verwaltung unterscheidet sich je nach Situation:
### Homemanager für iOS und iPadOS [#homemanager-für-ios-und-ipados]
Die Homemanager App wurde für iPhone und iPad entwickelt und deckt die mobile Steuerung und Wartung ab:
* Schneller Zugriff auf separate QR-Codes und 8-stellige Setup-PINs einzelner Child Bridges zur direkten Kopplung mit der Kamera.
* Gezielter Neustart einzelner Child Bridges bei Störungen oder nach Konfigurationsanpassungen, ohne die Haupt-Bridge zu unterbrechen.
* Volle Unterstützung für den offiziellen Homebridge Custom UI Standard, inklusive grafischer Einrichtungsassistenten, OAuth-Anmeldungen und 2-Faktor-Authentifizierung direkt in der App.
* Überwachung von Prozessorauslastung, Arbeitsspeicher, Systemtemperaturen und Einsicht in Live-Logs zur schnellen Fehlersuche.
* Verwaltung mehrerer Homebridge- und HOOBS-Instanzen in einer gemeinsamen mobilen Oberfläche.
### Webinterface am Computer (`homebridge-config-ui-x`) [#webinterface-am-computer-homebridge-config-ui-x]
Die offizielle Weboberfläche läuft im Browser auf Port 8581 des Servers und eignet sich für Arbeiten am Schreibtisch:
* Dashboard-Widgets für Systemstatus und Plugin-Zustände.
* Formularbasierte Bearbeitung sowie direkter Zugriff auf den JSON-Editor der `config.json`.
* Integrierte Terminal- und Konsolen-Ansichten für System-Updates und Node.js-Wartung.
* Verwaltung globaler Netzwerkeinstellungen und Erstellung von System-Backups.
***
## Verwandte Themen [#verwandte-themen]