feat: erste Fassung der ninstrip-Integration fuer Home Assistant
Auf dem Geruest von ha-ninlight aufgebaut und bewusst parallel gehalten: gleiche Fehlerklassen in api.py, gleicher Coordinator mit Sperre und Fehlertoleranz, gleicher Einrichtungsablauf samt Zeroconf und Reauth. Eigenes Repo statt Erweiterung von ha-ninlight: die Geraete melden sich unter verschiedenen mDNS-Diensten, das Datenmodell unterscheidet sich deutlich (Segmente und Szenen gegen ein einzelnes Licht), und ha-ninlight laeuft produktiv mit vier Lampen - Verzweigungen dort haetten beide Produkte gefaehrdet. Entitaeten: light (Hauptschalter und Helligkeit), select (Szene), button (Neustart), vier Diagnosesensoren. In ha-dev eingebunden und am echten Geraet geprueft: Aus- und Einschalten, Helligkeit 40 Prozent, Szenenwechsel auf Regenbogen - das Geraet meldet jeweils genau das zurueck.
This commit is contained in:
@@ -0,0 +1,58 @@
|
||||
# ha-ninstrip
|
||||
|
||||
Home-Assistant-Integration für **ninstrip** — ESP32-C3-Firmware für
|
||||
IC-getriebene LED-Strips. Schwesterprojekt zu
|
||||
[ha-ninlight](https://gitea.zukunpht.de/ninharp/ha-ninlight).
|
||||
|
||||
## Warum eine eigene Integration
|
||||
|
||||
ninlight und ninstrip teilen sich das API-Gerüst (Port 3333, `/api/v1`,
|
||||
`Authorization: <token>`), beschreiben aber verschiedene Geräte: eine Lampe
|
||||
mit einem Licht gegen einen Strip mit Segmenten und Szenen. Beide Modelle in
|
||||
eine Integration zu zwingen hieße, in Coordinator und Entitäten dauernd zu
|
||||
verzweigen — und bei jedem Fehler beide Produkte zu gefährden. Dazu kommt,
|
||||
dass sich die Geräte unter verschiedenen mDNS-Diensten melden
|
||||
(`_ninlight._tcp` gegen `_ninstrip._tcp`) und ohnehin getrennt gefunden
|
||||
werden.
|
||||
|
||||
Das Gerüst ist aber bewusst **eins zu eins von ninlight übernommen**: gleiche
|
||||
Fehlerklassen, gleicher Coordinator-Aufbau, gleicher Einrichtungsablauf. Wer
|
||||
dort etwas korrigiert, findet es hier an derselben Stelle.
|
||||
|
||||
## Einrichtung
|
||||
|
||||
Das Gerät meldet sich per mDNS und wird von Home Assistant vorgeschlagen.
|
||||
Nötig ist nur das **API-Token** — es steht einmalig auf der seriellen Konsole,
|
||||
wenn das Gerät zum ersten Mal startet. Ein Werksreset erzeugt ein neues; dann
|
||||
fragt Home Assistant von selbst nach.
|
||||
|
||||
Ohne mDNS geht es auch von Hand über Adresse und Token.
|
||||
|
||||
## Entitäten
|
||||
|
||||
| Entität | |
|
||||
|---|---|
|
||||
| `light` | Hauptschalter und Helligkeit des ganzen Strips |
|
||||
| `select` | aufgeschaltete Szene (acht Plätze in der Firmware) |
|
||||
| `button` | Neustart |
|
||||
| `sensor` | WLAN-Signal, Laufzeit, freier Speicher, Leistungsbegrenzung |
|
||||
|
||||
Die Diagnose-Sensoren sind standardmäßig abgeschaltet; die
|
||||
Leistungsbegrenzung ist an, weil sie verrät, ob die Strombegrenzung gerade
|
||||
herunterregelt (100 % heißt: tut sie nicht).
|
||||
|
||||
**Eine Lichtentität je Gerät, nicht je Segment.** `device/state` ist der
|
||||
Hauptschalter und trägt keine Farbe — bei mehreren Segmenten gäbe es keine
|
||||
eine Farbe, die stimmen würde. Die Segmente stellt man über Szenen.
|
||||
|
||||
## Noch nicht drin
|
||||
|
||||
- Einzelne Segmente als eigene Entitäten
|
||||
- Firmware-Aktualisierung über eine `update`-Entität (die Firmware kann OTA
|
||||
mit Rückfallebene, die Integration nutzt es noch nicht)
|
||||
- sACN/E1.31 — in der Firmware geplant, siehe ninstrip-Repo
|
||||
|
||||
## Entwicklung
|
||||
|
||||
Die Integration wird in der gemeinsamen Dev-Instanz `ha-dev` per Mount
|
||||
eingebunden, der Quellcode bleibt in diesem Repo.
|
||||
Reference in New Issue
Block a user