Home Assistant Integration¶
Kamerplanter laesst sich ueber eine Custom Integration in Home Assistant einbinden. Alle Pflanzendaten, Tankwerte, Aufgaben und Kalendereintraege erscheinen als native HA-Entities und koennen in Dashboards, Automationen und Benachrichtigungen genutzt werden.
Ueberblick¶
flowchart LR
KP["Kamerplanter\nBackend"] -->|REST API\nPolling| HA["Home Assistant\nCustom Integration"]
HA --> D["Dashboard\nLovelace Cards"]
HA --> A["Automationen\nBlueprints"]
HA --> N["Benachrichtigungen\nMobile Push"] | Aspekt | Details |
|---|---|
| Repository | kamerplanter-ha (eigenstaendiges GitHub-Repo) |
| Installation | HACS (Home Assistant Community Store) oder manuell |
| Kommunikation | REST API Polling gegen Kamerplanter-Backend |
| Authentifizierung | API-Key (kp_-Prefix) oder Light-Modus (ohne Auth) |
| HA-Mindestversion | Home Assistant Core 2024.1+ |
Separates Repository
Die HA-Integration ist nicht Teil des Kamerplanter-Backends. Sie wird als eigenstaendiges HACS-Repository entwickelt und installiert.
Installation¶
Via HACS (empfohlen)¶
- Oeffne HACS in Home Assistant
- Klicke auf Integrationen > Custom Repositories
- Fuege das Repository
kamerplanter/kamerplanter-hahinzu - Suche nach Kamerplanter und klicke Installieren
- Starte Home Assistant neu
Manuelle Installation¶
- Lade die aktuelle Version von GitHub herunter
- Kopiere
custom_components/kamerplanter/in dein HAconfig/custom_components/-Verzeichnis - Starte Home Assistant neu
Voraussetzungen: Bidirektionaler API-Zugriff¶
Fuer eine vollstaendige Integration muessen beide Systeme gegenseitig API-Zugriff haben. Das erfordert einen Token-Austausch:
flowchart LR
KP["Kamerplanter"] -- "HA Long-Lived\nAccess Token" --> HA["Home Assistant"]
HA -- "Kamerplanter\nAPI-Key (kp_...)" --> KP | Richtung | Token | Wozu | Wo erstellen |
|---|---|---|---|
| HA → Kamerplanter | Kamerplanter API-Key (kp_-Prefix) | HA liest Pflanzendaten, Tankwerte, Aufgaben | Kamerplanter: Einstellungen > API-Keys |
| Kamerplanter → HA | HA Long-Lived Access Token | Kamerplanter liest Sensordaten, steuert Aktoren (REQ-005, REQ-018) | Home Assistant: Profil > Long-Lived Access Tokens |
Beide Tokens erforderlich
Ohne den Kamerplanter API-Key kann die HA-Integration keine Daten abfragen. Ohne den HA Access Token kann Kamerplanter keine Sensordaten aus Home Assistant lesen und keine Aktoren steuern. Fuer einen reinen Lese-Betrieb (nur HA-Dashboard) reicht der Kamerplanter API-Key allein.
Tokens einrichten¶
1. Kamerplanter API-Key erstellen (fuer HA → Kamerplanter):
- In Kamerplanter: Einstellungen > API-Keys > Neuer Key
- Den generierten Key (
kp_...) kopieren - In Home Assistant: Bei der Kamerplanter-Integration im Config Flow eingeben
2. HA Access Token erstellen (fuer Kamerplanter → HA):
- In Home Assistant: Profil (unten links) > Long-Lived Access Tokens > Token erstellen
- Den Token kopieren
- In Kamerplanter: Einstellungen > Home Assistant > URL und Token eintragen
- Oder via Umgebungsvariablen:
HA_URLundHA_ACCESS_TOKEN
- Oder via Umgebungsvariablen:
Einrichtung¶
Nach der Installation fuehrt ein 4-Schritte-Assistent durch die Konfiguration:
Schritt 1: Kamerplanter-URL¶
Gib die URL deiner Kamerplanter-Instanz ein:
- Lokal:
http://raspberry:8000oderhttp://192.168.1.50:8000 - Extern:
https://kamerplanter.example.com
Die Integration prueft die Erreichbarkeit automatisch via /api/health.
Schritt 2: Authentifizierung¶
| Modus | Beschreibung |
|---|---|
| Light-Modus | Keine Authentifizierung noetig (REQ-027) |
| API-Key | API-Schluessel mit kp_-Prefix eingeben (empfohlen) |
| Login | Benutzername und Passwort als Fallback |
Schritt 3: Tenant auswaehlen¶
Bei Multi-Tenant-Betrieb (z.B. Gemeinschaftsgarten) den gewuenschten Tenant aus der Liste waehlen. Bei Einzelnutzern wird dieser Schritt uebersprungen.
Schritt 4: Entities konfigurieren¶
Waehle aus, welche Pflanzen, Standorte und Tanks als HA-Entities angelegt werden sollen. Per Default werden alle verfuegbaren Entities erstellt.
Verfuegbare Entities¶
Die Integration erstellt automatisch Entities fuer alle ausgewaehlten Pflanzen, Standorte und Tanks.
Pflanzen-Entities¶
| Entity | Typ | Einheit | Beschreibung |
|---|---|---|---|
sensor.kp_{plant}_phase | Sensor | -- | Aktuelle Wachstumsphase |
sensor.kp_{plant}_days_in_phase | Sensor | Tage | Tage in aktueller Phase |
sensor.kp_{plant}_vpd_target | Sensor | kPa | VPD-Sollwert fuer aktuelle Phase |
sensor.kp_{plant}_ec_target | Sensor | mS/cm | EC-Sollwert fuer aktuelle Phase |
sensor.kp_{plant}_photoperiod | Sensor | h | Photoperiode (Licht/Dunkel) |
sensor.kp_{plant}_gdd_accumulated | Sensor | GDD | Akkumulierte Wachstumsgradtage |
sensor.kp_{plant}_harvest_readiness | Sensor | % | Erntebereitschaft |
sensor.kp_{plant}_karenz_remaining | Sensor | Tage | Verbleibende Wartezeit (IPM) |
sensor.kp_{plant}_next_watering | Sensor | -- | Naechster Giesstermin |
sensor.kp_{plant}_health_score | Sensor | % | Gesundheitsscore |
binary_sensor.kp_{plant}_needs_attention | Binary Sensor | -- | Pflanze braucht Aufmerksamkeit |
Tank-Entities¶
| Entity | Typ | Einheit | Beschreibung |
|---|---|---|---|
sensor.kp_{tank}_ec | Sensor | mS/cm | Elektrische Leitfaehigkeit |
sensor.kp_{tank}_ph | Sensor | pH | pH-Wert |
sensor.kp_{tank}_fill_level | Sensor | % | Fuellstand |
sensor.kp_{tank}_water_temp | Sensor | C | Wassertemperatur |
sensor.kp_{tank}_solution_age_days | Sensor | Tage | Alter der Naehrloesung |
binary_sensor.kp_{tank}_alert_active | Binary Sensor | -- | Tank-Alarm aktiv |
Standort-Entities¶
| Entity | Typ | Beschreibung |
|---|---|---|
sensor.kp_{location}_active_plants | Sensor | Anzahl aktiver Pflanzen |
sensor.kp_{location}_vpd_current | Sensor | Aktueller VPD-Wert |
Kalender & Aufgaben¶
| Entity | Typ | Beschreibung |
|---|---|---|
calendar.kp_tasks | Calendar | Alle Kamerplanter-Events (iCal-Feed) |
todo.kp_{location}_tasks | Todo | Faellige Aufgaben pro Standort |
Polling-Intervalle¶
Die Integration nutzt mehrere Coordinators mit unterschiedlichen Polling-Intervallen:
| Datentyp | Standard-Intervall | Minimum |
|---|---|---|
| Pflanzen | 5 Minuten | 2 Minuten |
| Standorte | 5 Minuten | 2 Minuten |
| Tanks | 2 Minuten | 1 Minute |
| Alarme | 1 Minute | 30 Sekunden |
| Aufgaben | 5 Minuten | 2 Minuten |
Die Intervalle koennen in den Integrations-Optionen angepasst werden.
Automations-Beispiele¶
Phasenwechsel: Lichtprogramm umstellen¶
Wenn Kamerplanter einen Phasenwechsel zu "Bluete" 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: Auffuell-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: Gewaechshaus-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 pruefen!
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 zusaetzliche 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') }}
# Naechste 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 Bluete. Trichome pruefen!
Attribut-Zugriff allgemein
Das Muster state_attr('sensor.kp_{id}_phase_timeline', states('sensor.kp_{id}_phase')) funktioniert fuer alle Kamerplanter-Pflanzen und Planting Runs. Bei Runs stehen zusaetzlich phase_week, phase_progress_pct und remaining_days als Attribute zur Verfuegung.
Lovelace Custom Cards¶
Neben den Standard-HA-Cards stellt das kamerplanter-ha-Repository optionale Custom Lovelace Cards bereit:
- Tank-Card -- Fuellstand, EC, pH und Wassertemperatur auf einen Blick
- Phasen-Timeline-Card -- Visueller Phasenverlauf einer Pflanze
- Duengemischungs-Card -- Aktuelle Mischung mit Einzelkomponenten
Die Cards werden ueber den Standard-HA-Editor konfiguriert (Entity-Picker, keine YAML-Pflicht).
Fehlerbehandlung¶
| Fehler | Ursache | Loesung |
|---|---|---|
| "Kamerplanter nicht erreichbar" | Backend offline oder URL falsch | URL pruefen, Backend starten |
| "API-Key ungueltig" | Key revoked oder falsch | Neuen API-Key in Kamerplanter generieren |
| Entity zeigt "unavailable" | Coordinator-Update fehlgeschlagen | Logs pruefen, Polling-Intervall erhoehen |
Diagnostics-Daten sind unter Einstellungen > Integrationen > Kamerplanter > Diagnostik verfuegbar.
Siehe auch¶
- Sensorik -- Hybrid-Sensorik mit HA als Datenquelle
- Kalender -- iCal-Feed fuer HA Calendar-Entity
- Tankmanagement -- Tank-Entities im Detail