Home Assistant Integration¶

Kamerplanter lässt sich über eine Custom Integration in Home Assistant einbinden. Alle Pflanzendaten, Tankwerte, Aufgaben und Kalendereinträge erscheinen als native HA-Entities und können in Dashboards, Automationen und Benachrichtigungen genutzt werden.

Überblick¶

flowchart LR
    KP["Kamerplanter<br/>Backend"] -->|REST API<br/>Polling| HA["Home Assistant<br/>Custom Integration"]
    HA --> D["Dashboard<br/>Lovelace Cards"]
    HA --> A["Automations<br/>Blueprints"]
    HA --> N["Notifications<br/>Mobile Push"]

Installation¶

Via HACS (empfohlen)¶

1. Öffne HACS in Home Assistant
2. Klicke auf Integrationen > Custom Repositories
3. Füge das Repository kamerplanter/kamerplanter-ha hinzu
4. Suche nach Kamerplanter und klicke Installieren
5. Starte Home Assistant neu

Manuelle Installation¶

1. Lade die aktuelle Version von GitHub herunter
2. Kopiere custom_components/kamerplanter/ in dein HA config/custom_components/-Verzeichnis
3. Starte Home Assistant neu

Voraussetzungen: Bidirektionaler API-Zugriff¶

Für eine vollständige Integration müssen beide Systeme gegenseitig API-Zugriff haben. Das erfordert einen Token-Austausch:

flowchart LR
    KP["Kamerplanter"] -- "HA Long-Lived<br/>Access Token" --> HA["Home Assistant"]
    HA -- "Kamerplanter<br/>API Key (kp_...)" --> KP

Tokens einrichten¶

1. Kamerplanter API-Key erstellen (für HA → Kamerplanter):

1. In Kamerplanter: Einstellungen > API-Keys > Neuer Key
2. Den generierten Key (kp_...) kopieren
3. In Home Assistant: Bei der Kamerplanter-Integration im Config Flow eingeben

2. HA Access Token erstellen (für Kamerplanter → HA):

1. In Home Assistant: Profil (unten links) > Long-Lived Access Tokens > Token erstellen
2. Den Token kopieren
3. In Kamerplanter: Einstellungen > Home Assistant > URL und Token eintragen
   • Oder via Umgebungsvariablen: HA_URL und HA_ACCESS_TOKEN

Auto-Discovery via mDNS (empfohlen)¶

Mit aktivierter mDNS-Ankündigung erkennt Home Assistant das Kamerplanter-Backend automatisch im lokalen Netzwerk — die URL muss nicht mehr manuell eingegeben werden. Der Config Flow startet direkt beim Authentifizierungs-Schritt.

flowchart LR
    KP["Kamerplanter backend<br/>MDNS_ENABLED=true"]
    KP -->|_kamerplanter._tcp.local.| HA["Home Assistant"]
    HA --> D["Discovery notification<br/>Configure"]
    D --> CF["Config flow<br/>URL pre-filled<br/>API key only"]

Voraussetzungen¶

• Backend und Home Assistant laufen im gleichen L2-Netzwerk (Multicast UDP 5353 erreichbar).
• MDNS_ENABLED=true im Backend gesetzt (Default ist false).
• Empfohlen: feste INSTANCE_ID setzen (z. B. INSTANCE_ID=kp-homelab-01), damit der HA-Config-Entry über Backend-Neustarts hinweg stabil bleibt.

Aktivierung¶

Docker Compose / Bare Metal:

services:
  kamerplanter:
    environment:
      MDNS_ENABLED: "true"
      INSTANCE_ID: "kp-homelab-01"

Kubernetes (Homelab mit hostNetwork: true):

# values.yaml
env:
  MDNS_ENABLED: "true"
  INSTANCE_ID: "kp-homelab-01"
hostNetwork: true

Ablauf¶

1. Nach Backend-Start zeigt Home Assistant unter Einstellungen > Geräte & Dienste eine Benachrichtigung "Kamerplanter entdeckt".
2. Klick auf Konfigurieren öffnet den Config Flow mit vorausgefüllter URL und vorausgefüllter Instanz-ID.
3. Es bleibt nur der Authentifizierungs-Schritt — API-Key (kp_...) eingeben, fertig.

Sollte die Discovery-Benachrichtigung nicht erscheinen, nutze den manuellen Einrichtungs-Assistenten unten.

Einrichtung (manuell)¶

Wenn Auto-Discovery nicht verfügbar ist (Cloud, Kubernetes ohne hostNetwork, getrennte Netzwerksegmente), führt ein 4-Schritte-Assistent durch die Konfiguration:

Schritt 1: Kamerplanter-URL¶

Gib die URL deiner Kamerplanter-Instanz ein:

• Lokal: http://raspberry:8000 oder http://192.168.1.50:8000
• Extern: https://kamerplanter.example.com

Die Integration prüft die Erreichbarkeit automatisch via /api/health.

Schritt 2: Authentifizierung¶

Schritt 3: Tenant auswählen¶

Bei Multi-Tenant-Betrieb (z.B. Gemeinschaftsgarten) den gewünschten Tenant aus der Liste wählen. Bei Einzelnutzern wird dieser Schritt übersprungen.

Schritt 4: Entities konfigurieren¶

Wähle aus, welche Pflanzen, Standorte und Tanks als HA-Entities angelegt werden sollen. Per Default werden alle verfügbaren Entities erstellt.

Verfügbare Entities¶

Die Integration erstellt automatisch Entities für alle ausgewählten Pflanzen, Standorte und Tanks.

Pflanzen-Entities¶

Tank-Entities¶

Standort-Entities¶

Kalender & Aufgaben¶

Auswahl der veröffentlichten Elemente¶

Standardmäßig wird kein Element an Home Assistant übertragen. Erst wenn eine Pflanze, ein Tank oder ein Standort in Kamerplanter explizit aktiviert wird, erscheint sie als Entity in Home Assistant. Dieses Opt-in-Prinzip verhindert, dass alle Datensätze eines Gartens automatisch in Home Assistant landen.

Schalter auf der Detailseite¶

Öffne die Detailseite der gewünschten Pflanze, des Tanks oder des Standorts. Im Abschnitt Smart Home findest du den Schalter „Als Home-Assistant-Sensor veröffentlichen".

• Schalter ein — Das Element wird an Home Assistant übertragen; die zugehörigen Entities werden beim nächsten Coordinator-Update angelegt.
• Schalter aus (Standard) — Das Element wird nicht übertragen; bereits vorhandene Entities werden aus Home Assistant entfernt.

Zentraler Verwaltungs-Tab¶

Für die Verwaltung mehrerer Elemente auf einmal steht ein zentraler Tab bereit: Einstellungen → „HA-Veröffentlichung".

Der Tab gliedert sich in drei Bereiche — je einen für Pflanzen, Tanks und Standorte. Jeder Bereich zeigt alle vorhandenen Elemente in einer tabellarischen Ansicht. Einzelne Elemente lassen sich dort direkt per Schalter aktivieren oder deaktivieren, ohne die jeweilige Detailseite öffnen zu müssen.

Mandantenbezug¶

Die Auswahl gilt pro Tenant (Garten). In einem Gemeinschaftsgarten mit mehreren Tenants ist die Publikations-Einstellung je Tenant getrennt — derselbe Nutzer kann in Tenant A einen Tank veröffentlichen, in Tenant B nicht.

Technischer Hintergrund (für HA-Integrations-Entwickler)¶

Das Kamerplanter-Backend stellt die aktivierten Schlüssel pro Elementtyp über einen tenant-skoped Endpunkt bereit. Die kamerplanter-ha-Custom-Integration soll beim Aufbau der Entities ausschließlich diese Schlüssel berücksichtigen.

Aktivierte Schlüssel abrufen:

GET /api/v1/t/{tenant_slug}/ha-publish/enabled-keys/{entity_type}

entity_type ist einer von: plant, tank, location

Beispielantwort für entity_type=plant:

{
  "entity_type": "plant",
  "enabled_keys": ["345249", "a1b2c3", "f9e8d7"]
}

Einzelstatus lesen oder setzen:

GET  /api/v1/t/{tenant_slug}/ha-publish/{entity_type}/{entity_key}
PUT  /api/v1/t/{tenant_slug}/ha-publish/{entity_type}/{entity_key}

PUT-Body:

{ "enabled": true }

Polling-Intervalle¶

Die Integration nutzt mehrere Coordinators mit unterschiedlichen Polling-Intervallen:

Die Intervalle können in den Integrations-Optionen angepasst werden.

Automations-Beispiele¶

Phasenwechsel: Lichtprogramm umstellen¶

Wenn Kamerplanter einen Phasenwechsel zu "Blüte" meldet, wird das Lichtprogramm automatisch auf 12h/12h umgestellt:

alias: "KP: Bluete-Start - 12/12 Licht"
trigger:
  - platform: state
    entity_id: sensor.kp_northern_lights_phase
    to: "flowering"
action:
  - service: automation.turn_off
    target:
      entity_id: automation.licht_18_6_veg
  - service: automation.turn_on
    target:
      entity_id: automation.licht_12_12_bloom
  - service: notify.mobile_app_phone
    data:
      title: "Kamerplanter: Bluete gestartet"
      message: "Northern Lights wechselt in Bluete. Licht auf 12/12 umgestellt."

VPD-Regelung mit Kamerplanter-Sollwert¶

Kamerplanter liefert den optimalen VPD-Sollwert pro Phase. Home Assistant regelt den Befeuchter:

alias: "KP: VPD-Regelung"
trigger:
  - platform: template
    value_template: >
      {{ states('sensor.growzelt_vpd') | float(0) >
         (states('sensor.kp_northern_lights_vpd_target') | float(1.0) + 0.2) }}
    id: vpd_too_high
  - platform: template
    value_template: >
      {{ states('sensor.growzelt_vpd') | float(0) <
         (states('sensor.kp_northern_lights_vpd_target') | float(1.0) - 0.1) }}
    id: vpd_ok
action:
  - choose:
      - conditions:
          - condition: trigger
            id: vpd_too_high
        sequence:
          - service: switch.turn_on
            target:
              entity_id: switch.befeuchter_zelt_1
      - conditions:
          - condition: trigger
            id: vpd_ok
        sequence:
          - service: switch.turn_off
            target:
              entity_id: switch.befeuchter_zelt_1

Tank niedrig: Auffüll-Erinnerung¶

alias: "KP: Tank nachfuellen"
trigger:
  - platform: numeric_state
    entity_id: sensor.kp_haupttank_fill_level
    below: 20
action:
  - service: notify.mobile_app_phone
    data:
      title: "Tank fast leer!"
      message: >
        Fuellstand: {{ states('sensor.kp_haupttank_fill_level') }}%.
        EC: {{ states('sensor.kp_haupttank_ec') }} mS/cm,
        pH: {{ states('sensor.kp_haupttank_ph') }}

Frostwarnung: Gewächshaus-Heizung¶

alias: "KP: Frostwarnung - Heizung ein"
trigger:
  - platform: state
    entity_id: binary_sensor.kp_gewaechshaus_frost_warning
    to: "on"
action:
  - service: switch.turn_on
    target:
      entity_id: switch.gewaechshaus_heizung
  - service: climate.set_temperature
    target:
      entity_id: climate.gewaechshaus
    data:
      temperature: 5
  - service: notify.mobile_app_phone
    data:
      title: "Frostwarnung!"
      message: "Heizung eingeschaltet (Frostschutz 5 Grad C)."

Erntebereitschaft: Push-Benachrichtigung¶

alias: "KP: Ernte bald bereit"
trigger:
  - platform: numeric_state
    entity_id: sensor.kp_white_widow_harvest_readiness
    above: 80
condition:
  - condition: template
    value_template: >
      {{ states('sensor.kp_white_widow_karenz_remaining') | int(99) == 0 }}
action:
  - service: notify.mobile_app_phone
    data:
      title: "Ernte bereit!"
      message: >
        Readiness: {{ states('sensor.kp_white_widow_harvest_readiness') }}%.
        Karenz abgelaufen. Trichome prüfen!

Phasen-Attribute per Jinja2-Template abfragen¶

Die Sensoren phase_timeline und phase stellen strukturierte Attribute bereit, die sich in Jinja2-Templates kombinieren lassen. So kann man Detail-Informationen zur aktuellen oder einer beliebigen Phase direkt im Dashboard oder in Automationen nutzen.

Aktuelle Phasen-Details abrufen¶

Der phase_timeline-Sensor speichert jede Phase als Attribut mit Status, Startdatum und Dauer. Der phase-Sensor liefert den Namen der aktuellen Phase -- kombiniert ergibt sich ein dynamischer Zugriff:

# Tage in aktueller Phase (dynamisch)
{{ state_attr('sensor.kp_345249_phase_timeline',
              states('sensor.kp_345249_phase')).days }}

# Startdatum der aktuellen Phase
{{ state_attr('sensor.kp_345249_phase_timeline',
              states('sensor.kp_345249_phase')).started }}

# Status der aktuellen Phase (current/completed)
{{ state_attr('sensor.kp_345249_phase_timeline',
              states('sensor.kp_345249_phase')).status }}

Bestimmte Phase direkt abfragen¶

# Wann hat die vegetative Phase begonnen?
{{ state_attr('sensor.kp_345249_phase_timeline', 'vegetative').started }}

# Wie viele Tage hat die Keimung gedauert?
{{ state_attr('sensor.kp_345249_phase_timeline', 'germination').days }}

Fortschritts-Attribute¶

Der phase_timeline-Sensor stellt zusätzliche Fortschritts-Attribute bereit:

# Name der aktuellen Phase
{{ state_attr('sensor.kp_345249_phase_timeline', 'current_phase_name') }}

# Tage in aktueller Phase
{{ state_attr('sensor.kp_345249_phase_timeline', 'days_in_phase') }}

# Nächste geplante Phase (bei Planting Runs)
{{ states('sensor.kp_345249_next_phase') }}

Beispiel: Markdown-Card mit Phasen-Info¶

type: markdown
content: >
  **{{ states('sensor.kp_345249_phase') | title }}** seit
  {{ state_attr('sensor.kp_345249_phase_timeline',
                 states('sensor.kp_345249_phase')).days }} Tagen
  (Start: {{ state_attr('sensor.kp_345249_phase_timeline',
                         states('sensor.kp_345249_phase')).started }})

  Naechste Phase: **{{ states('sensor.kp_345249_next_phase') | default('--') }}**

Beispiel: Bedingte Automation nach Phasen-Dauer¶

alias: "KP: Bluete-Erinnerung nach 8 Wochen"
trigger:
  - platform: template
    value_template: >
      {{ state_attr('sensor.kp_345249_phase_timeline',
                     states('sensor.kp_345249_phase')).days | int(0) >= 56 }}
condition:
  - condition: state
    entity_id: sensor.kp_345249_phase
    state: "flowering"
action:
  - service: notify.mobile_app_phone
    data:
      title: "8 Wochen Bluete erreicht"
      message: >
        Pflanze ist seit
        {{ state_attr('sensor.kp_345249_phase_timeline', 'flowering').days }}
        Tagen in der Blüte. Trichome prüfen!

Lovelace Custom Cards¶

Neben den Standard-HA-Cards stellt das kamerplanter-ha-Repository optionale Custom Lovelace Cards bereit:

• Tank-Card -- Füllstand, EC, pH und Wassertemperatur auf einen Blick
• Phasen-Timeline-Card -- Visueller Phasenverlauf einer Pflanze
• Düngmischungs-Card -- Aktuelle Mischung mit Einzelkomponenten

Die Cards werden über den Standard-HA-Editor konfiguriert (Entity-Picker, keine YAML-Pflicht).

Fehlerbehandlung¶

Diagnostics-Daten sind unter Einstellungen > Integrationen > Kamerplanter > Diagnostik verfügbar.

Siehe auch¶

• Sensorik -- Hybrid-Sensorik mit HA als Datenquelle
• Kalender -- iCal-Feed für HA Calendar-Entity
• Tankmanagement -- Tank-Entities im Detail