Developer Feature Request: Local API + Official Home Assistant Integration

Sehr geehrtes GHL-Team,

ich möchte einen technisch fokussierten Feature Request für den ProfiLux 4 / 4e einreichen, mit dem Ziel einer offiziellen, lokal nutzbaren Integrationsschnittstelle sowie einer fertigen Home-Assistant-Integration (HAOS), die ohne Reverse Engineering eingesetzt werden kann.

1. Zielsetzung

Bereitstellung einer stabilen, versionierten Local API auf dem ProfiLux inkl. eines offiziellen Home-Assistant-Plugins, das über den HA Integration Store verfügbar ist und nach Installation lediglich:

einen API-Key oder

einen OAuth2-Flow

benötigt, um vollständig einsatzbereit zu sein.

2. Systemarchitektur (Vorschlag)
2.1 ProfiLux – Local API Layer

Transport: HTTPS (LAN only)

API-Versionierung: /api/v1/

Datenformat: JSON (strict schema)

Auth:

API-Key (Header-based) oder

OAuth2 (Authorization Code / Device Flow)

API-Scope-Management:

read:sensors

read:devices

write:outputs

admin (optional)

Konfiguration im Webinterface:
System ? Developer / Local API

API enable/disable

Key / Token management

Read-only Mode

Logging / Debug

2.2 Abstraktionsschicht für PAB-Geräte

Alle über das interne PAB-Protokoll angeschlossenen Geräte sollten intern normalisiert und über die API hardware-agnostisch bereitgestellt werden:

Powerbars / Steckdosenleisten

Pumpen

KH Director

ION Director / ION Tester

weitere PAB-Devices

? Wichtig: keine direkte PAB-Exposition, sondern API-seitige Objekt-Abstraktion (Device-Model).

3. API-Modelle (Beispiel)
3.1 Geräte-Discovery
GET /api/v1/devices

{
"id": "pab_kh_director_1",
"type": "kh_director",
"capabilities": ["measure", "status"],
"state": "ready"
}

3.2 Sensor-Daten
GET /api/v1/sensors

{
"id": "ph_1",
"device_id": "profilux_core",
"value": 8.03,
"unit": "pH",
"timestamp": "2025-09-16T18:12:44Z",
"quality": "valid"
}

3.3 Aktoren
POST /api/v1/outputs/{id}/set

{
"value": true,
"source": "home_assistant"
}

4. Event- & Push-Mechanismen (optional, aber empfohlen)
MQTT

Topics:

ghl/profilux/{device_id}/sensor/{sensor_id}
ghl/profilux/{device_id}/alarm


Retain + QoS Support

WebSocket

Push bei:

Messwertänderungen

Alarmen

Geräte-Statuswechsel

? reduziert Polling-Last und erhöht Reaktionsgeschwindigkeit

5. Home Assistant Integration (offiziell)
5.1 Integration-Typ

Offizielle HA Integration (Core bevorzugt)

Alternativ initial: HACS ? später Core

5.2 Setup-Flow

mDNS / SSDP Discovery (profilux.local)

API-Key oder OAuth Login

Capability-Scan

Automatische Entity-Generierung

5.3 Entity-Mapping
ProfiLux Home Assistant
Sensor sensor.*
Alarm binary_sensor.*
Steckdose switch.*
Pumpe switch.* / number.*
1-10 V light.* / number.*
KH / ION eigene Device-Klassen

Alle Entitäten:

eindeutig (device_id + channel_id)

state-driven

update-fähig (Push bevorzugt)

6. Sicherheit & Stabilität

LAN-only Zugriff

Token Revocation

Rate-Limiting

API-Schema-Stabilität über Firmware-Updates

Changelog bei Breaking Changes

7. Nachfrage / Markt-Signal

Es existiert bereits messbare Nachfrage nach einer ProfiLux–Home-Assistant-Integration:

Wiederkehrende Suchanfragen bei Google zu Begriffen wie
„ProfiLux Home Assistant“, „GHL HA Integration“, „Aquarium Controller Home Assistant“

Community-Diskussionen und DIY-Lösungen in Foren & Repositories

Diese Nachfrage ist zwar nischig, aber technisch versiert und sehr loyal – typisch für ProfiLux-Anwender. Eine offizielle Integration würde diese Nutzer langfristig binden und neue Zielgruppen erschließen.

8. Zusammenfassung

Eine offizielle, lokale API + fertige HA-Integration würde:

ProfiLux als First-Class-Citizen im Smart-Home-Umfeld positionieren

Drittanbieter-Reverse-Engineering überflüssig machen

Den Nutzen vorhandener PAB-Hardware deutlich erhöhen

Ich hoffe, dieser technisch detaillierte Vorschlag kann als Grundlage für eine mögliche Umsetzung oder interne Evaluierung dienen.