# 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**. Im Auslieferungszustand und nach jedem
Werksreset antwortet das Gerät mit dem öffentlichen Werks-Token
`aabbccddeeff0011223344` — dasselbe wie bei ninlight —, und der Dialog belegt
es vor. Wer ein eigenes gesetzt hat, trägt es dort ein.

### Vertrauensgrenze

Das Werks-Token steht öffentlich im Repo. **Wer im selben WLAN ist und es
kennt, kann das Gerät steuern, Einstellungen ändern und Firmware aufspielen.**
Das ist eine bewusste Entscheidung, gleich wie bei ninlight: Ziel ist, die
Geräte einfach nutzbar zu halten, nicht ein gehärtetes Sicherheitsmodell.

Wer das nicht will, setzt ein eigenes Token — über die Firmware-API mit
`PUT system/settings {"type": "token", "token": "..."}` — und trägt es hier
ein. Für einen gehärteten Bau lässt sich das Werks-Token in der Firmware auch
ganz abschalten (`NL_DEFAULT_TOKEN` leer); dann würfelt das Gerät beim ersten
Start und gibt das Token einmalig seriell aus.

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.