---
url: /de/home-assistant/integration.md
---

# Home Assistant Integration

Die **camera.ui Integration** verbindet einen bestehenden camera.ui Server mit Home Assistant. Deine Kameras, ihre Sensoren, Bewegungs- und Objekterkennung, PTZ-Steuerung und die komplette camera.ui Oberfläche erscheinen direkt in Home Assistant.

Sie spricht den Server direkt über dein lokales Netzwerk an, Ereignisse kommen per Push. Kein MQTT-Broker und kein Cloud-Dienst ist beteiligt. Die Domain der Integration ist `cameraui`. Um camera.ui selbst in Home Assistant OS laufen zu lassen, siehe die Seite [App](/de/home-assistant/app).

## Installation

Die Integration wird über [HACS](https://hacs.xyz) als Custom-Repository verteilt.

1. Füge in HACS `cameraui/homeassistant-integration` als Custom-**Integration**-Repository hinzu.
2. Installiere **camera.ui** aus HACS.
3. Starte Home Assistant neu.

## Verbinden

### Erkennung

camera.ui kündigt sich im lokalen Netz über mDNS an (`_camera-ui._tcp.local.`). Sobald Home Assistant den Server sieht, erscheint unter **Einstellungen → Geräte & Dienste** eine **camera.ui gefunden**-Karte. Öffne sie und gib deinen API-Token ein, Host und Port kommen aus der Erkennung.

### Manuelle Einrichtung

Wenn die Erkennung den Server nicht erreicht (zum Beispiel in einem anderen Subnetz), füge ihn von Hand hinzu:

1. Gehe zu **Einstellungen → Geräte & Dienste → Integration hinzufügen** und suche nach **camera.ui**.
2. Gib **Host**, **Port** (Standard `3443`) und deinen **API-Token** ein.

### API-Token

Beide Wege brauchen einen [API-Token](/de/admin/security#api-tokens). Erstelle einen in camera.ui unter **Einstellungen → Account → API-Tokens**.

Nimm den Token eines **Admin-Accounts**. Das Steuern von camera.ui-Sensoren aus Home Assistant (Schlösser, Tore, Lichter, Sirenen, Alarmanlagen, PTZ) braucht Admin-Rechte; mit einem Viewer-Token erscheinen die Entitäten zwar, ihre Befehle werden aber abgelehnt.

Die Einrichtung prüft den Token gegen den Server: ein abgelehnter Token ergibt einen Authentifizierungsfehler, ein unerreichbarer Server einen Verbindungsfehler.\[^ssl]

\[^ssl]: Der Server wird über HTTPS erreicht. Die Integration prüft das Zertifikat nicht, ein selbstsigniertes camera.ui Zertifikat funktioniert also ohne zusätzliche Einrichtung.

## Was du bekommst

Die Integration legt **ein Home Assistant Gerät pro Kamera** an und hält die Liste aktuell. Sie liest die Kameraliste alle 60 Sekunden neu, und eine Kamera, die du in camera.ui entfernst, wird automatisch aus Home Assistant entfernt.

### Kameras

Jedes Kameragerät trägt eine **Kamera-Entität**, die live streamt und Snapshots liefert. Das Gerät ist mit dem Hersteller `camera.ui` gekennzeichnet und verlinkt zurück auf die Weboberfläche des Servers.

### Sensoren

Jeder [freigegebene Sensor](/de/sensors/) in camera.ui wird auf der passenden Plattform in Home Assistant gespiegelt, egal ob er zu einer Kamera gehört oder nicht:

| camera.ui Sensor | Home Assistant Plattform |
|---|---|
| Binär / Kontakt | `binary_sensor` |
| Messwert | `sensor` |
| Schalter | `switch` |
| Licht | `light` |
| Sirene | `siren` |
| Schloss | `lock` |
| Abdeckung | `cover` |
| Alarmanlage | `alarm_control_panel` |

Kamera-Hardware (das eigene Spotlight, die Sirene oder die Batterie einer Kamera) landet am Gerät der Kamera. Jeder andere Sensor wird ein eigenes Gerät und hängt unter seiner Kamera, wenn er genau einer zugewiesen ist. Ob ein Sensor überhaupt rüberkommt, entscheidet der Schalter **Sensor freigeben** auf der [Sensoren-Seite](/de/sensors/setup#die-sensoren-seite). Kamera-Hardware hat keinen Schalter, sie folgt immer ihrer Kamera.

Die steuerbaren funktionieren in beide Richtungen: ein **switch** und eine **siren** schalten an und aus, ein **light** schaltet an und aus (und dimmt, wenn es Helligkeit meldet), ein **cover** öffnet und schließt, ein **lock** ver- und entriegelt, und ein **alarm\_control\_panel** aktiviert Home, Away oder Night und deaktiviert.

Fügst du in camera.ui einen Sensor hinzu, benennst ihn um, weist ihn neu zu, gibst ihn frei oder löschst ihn, folgt die passende Home Assistant Entität live, ohne Neustart. Ein Sensor, dessen Plugin offline ist, zeigt sich als nicht verfügbar.

### Bewegungs- und Objekterkennung

Jede Kamera bekommt einen **motion**-Binärsensor, der eingeschaltet ist, solange eine Erkennung aktiv ist.

Kameras mit Objekterkennung bekommen zusätzlich je einen Binärsensor für **person**, **vehicle**, **animal** und **package**. Jeder ist eingeschaltet, solange das Objekt im Bild ist, und geht aus, wenn die Erkennung endet.\[^objectclass]

\[^objectclass]: Bewegungs- und Objekt-Binärsensoren werden mit der Geräteklasse `motion` registriert, sie erscheinen in Home Assistant also als Bewegungssensoren und nicht als eigene Objektklasse.

### Erkennungssensoren

Kameras mit dem passenden Detektor bekommen Wert-Sensoren für **face**, **license plate** und **classification**. Der Wert des Sensors sind die erkannten Labels, die rohen Erkennungen liegen in seinen Attributen.

### Updates

Home Assistant bekommt außerdem **Update-Entitäten** für den camera.ui-Server und seine Plugins. Verfügbare Updates erscheinen in der Updates-Liste von Home Assistant und lassen sich von dort installieren. Der Update-Dialog bietet an, vorher eine Sicherung anzulegen: Dann schreibt camera.ui zuerst ein [Backup](/de/admin/backup) und bricht das Update ab, wenn das schiefgeht. Schalte **Updates aus Home Assistant erlauben** in den Optionen der Integration aus, um die Updates sichtbar zu lassen, aber ohne Installieren-Knopf.

## PTZ

Schwenken, Neigen und Zoomen wird als **Dienst** bereitgestellt, `cameraui.ptz`, nicht als Entität. Wähle eine oder mehrere Kamera-Entitäten als Ziel und eine Aktion:

* **continuous.** Mit fester Geschwindigkeit bewegen, bis gestoppt wird, `pan`, `tilt` und `zoom` sind dabei Geschwindigkeiten.
* **stop.** Eine laufende Bewegung stoppen.
* **move.** Um einen relativen Schritt bewegen.
* **absolute.** Zu einer absoluten Position fahren.
* **home.** Zur Home-Position zurückkehren.
* **preset.** Ein gespeichertes Preset per Name aufrufen.

Die Felder `pan`, `tilt` und `zoom` reichen von `-1` bis `1`. Die Aktion `preset` braucht einen Preset-Namen. Hat keine der Zielkameras PTZ, meldet der Dienst einen Fehler.

```yaml
action:
  - service: cameraui.ptz
    target:
      entity_id: camera.driveway
    data:
      action: preset
      preset: gate
```

## Automatisierungen

### Geräte-Trigger

Jedes Kameragerät bietet drei Trigger im Automatisierungs-Editor:

* **Detection started.** Eine Erkennung hat an der Kamera begonnen.
* **Detection ended.** Die Erkennung ist beendet.
* **Object recognized.** Ein Gesicht, Kennzeichen oder eine Klassifizierung wurde während einer Erkennung erkannt.

### Der Event-Bus

Die Integration feuert außerdem ein `cameraui_event` auf dem Home Assistant Event-Bus, mehrmals über den Verlauf einer Erkennung:

| `state` | Wann |
|---|---|
| `start` | Eine Erkennung beginnt. |
| `object` | Ein neues Objekt-Label taucht während der Erkennung auf. |
| `recognized` | Ein Gesicht, Kennzeichen oder eine Klassifizierung wird während der Erkennung erkannt. |
| `end` | Die Erkennung endet. |

Jedes Ereignis trägt diese Felder:

| Feld | Inhalt |
|---|---|
| `camera_id` | Die id der Kamera. |
| `camera_name` | Der Name der Kamera. |
| `state` | Einer der Werte oben. |
| `detection_types` | Die beteiligten Erkennungstypen. |
| `event_id` | Die id, die alle Ereignisse einer Erkennung teilen. |
| `labels` | Gesehene Objekt-Labels. |
| `faces` | Erkannte Gesichter. |
| `plates` | Erkannte Kennzeichen. |
| `classifications` | Weitere erkannte Attribute. |
| `attributes` | Die vollständige rohe Attributliste. |

Filtere auf `state`, um auf einen bestimmten Punkt im Verlauf zu reagieren:

```yaml
automation:
  - alias: Notify on recognized face
    trigger:
      - platform: event
        event_type: cameraui_event
        event_data:
          state: recognized
    action:
      - service: notify.mobile_app
        data:
          message: >-
            {{ trigger.event.data.faces | join(', ') }}
            seen at {{ trigger.event.data.camera_name }}
```

```yaml
automation:
  - alias: Turn on light when a person appears
    trigger:
      - platform: event
        event_type: cameraui_event
        event_data:
          state: object
    condition:
      - "{{ 'person' in trigger.event.data.labels }}"
    action:
      - service: light.turn_on
        target:
          entity_id: light.driveway
```

Für den Zustand `object` gibt es keinen Geräte-Trigger, nutze dafür den Event-Bus.\[^objecttrigger]

\[^objecttrigger]: Die drei Geräte-Trigger entsprechen `start`, `end` und `recognized`. Um auf ein bestimmtes Objekt-Label mitten in einer Erkennung zu reagieren, lausche wie oben gezeigt auf `cameraui_event` mit `state: object`.

## Sidebar-Panel

Die Einrichtung fügt der Home Assistant Seitenleiste einen **camera.ui**-Eintrag hinzu, der die komplette camera.ui Oberfläche einbettet. Das Panel ist **nur für Admins**: Es erscheint für Administrator-Konten und bleibt für alle anderen verborgen.

## Dashboard-Karten

Drei Karten kommen mit der Integration und melden sich selbst an: eine Kamera, eine Camview-Ansicht und ein Streifen mit den letzten Ereignissen. Ihre Optionen stehen unter [Dashboard-Karten](/de/home-assistant/card).

### Kartenzugriff

Die Optionen der Integration legen fest, wer sie nutzen darf: standardmäßig **nur Administratoren**, wahlweise **alle Home-Assistant-Nutzer**. Die Karten erreichen camera.ui über Home Assistant mit dem Token der Integration, wer sie freigibt, gibt also jedem Home-Assistant-Nutzer das, was dieses Token sehen darf. **Viewer-Token** nimmt ein zweites camera.ui-Token, das für alle ohne Home-Assistant-Adminrechte verwendet wird, damit lässt sich ein eingeschränktes camera.ui-Konto dahinter setzen.

## Aufnahmen im Medien-Browser

Ereignisse mit Aufnahme erscheinen im **Medien**-Browser von Home Assistant unter camera.ui: erst die Kameras, dazu ein Eintrag **Alle Kameras**, dann die Tage, dann die Ereignisse selbst, jedes mit Vorschaubild und benannt nach Uhrzeit und Erkanntem. Ein Klick spielt den Clip ab, und zwar schon während der Export noch läuft. Jeder Eintrag lässt sich per `media_player.play_media` auf einen Fernseher oder Lautsprecher schicken.

**Clip-Qualität** in den Optionen bestimmt, was diese Clips nutzen: den Sub-Stream, klein und schnell, oder den Haupt-Stream in voller Qualität.

## Nächste Schritte

* **[App](/de/home-assistant/app)** — camera.ui selbst als Home Assistant OS App betreiben.
* **[Dashboard-Karten](/de/home-assistant/card)** — die Karten auf einem Dashboard konfigurieren.
* **[Sensoren](/de/sensors/setup)** — einer Kamera Sensoren zuweisen, damit sie Home Assistant erreichen.