ha-ninstrip/README.md

# 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, Helligkeit, Farbe, Farbtemperatur, Übergangszeit |
| `select` | aufgeschaltete Szene (acht Plätze in der Firmware) |
| `select` | Einschaltverhalten (`last` / `on` / `off`) |
| `number` | Einblend-, Ausblend- und Übergangszeit in ms |
| `switch` | bei Änderung einschalten |
| `button` | Neustart |
| `sensor` | IP-Adresse, WLAN-Signal, Laufzeit, freier Speicher, Leistungsbegrenzung, letzter Update-Fehler, Startzeit |
| `switch` | sACN-Empfang an/aus |
| `number` | sACN-Universe und -Startslot |
| `select` | Verhalten nach Stromende (`release` / `hold`) |
| `binary_sensor` | sACN aktiv, Multicast beigetreten (letzterer standardmäßig aus) |
| `update` | Firmware-Aktualisierung aus dem Abbild-Ordner |

Standardmäßig an sind die **IP-Adresse** — sie ist das, was man im Alltag
sucht — und die **Leistungsbegrenzung**, weil sie verrät, ob die
Strombegrenzung gerade herunterregelt (100 % heißt: tut sie nicht). WLAN-
Signal, Laufzeit und freier Speicher sind aus; die braucht man erst im
Fehlerfall.

**Eine Lichtentität je Gerät, nicht je Segment.** `device/state` ist der
Hauptschalter und trägt keine Farbe — die steht je **Segment**. Die
Lichtentität schreibt eine gewählte Farbe deshalb in **alle** Segmente und
lässt deren Grenzen, Namen und Helligkeit stehen; die mühsam von Hand gemachte
Einteilung bleibt also erhalten.

Zeigen kann sie nur **eine** Farbe. Sind sich die Segmente nicht einig, meldet
sie gar keine, statt sich eine auszusuchen — jede Angabe wäre dann gelogen.
Farbtemperatur meldet sie nur, wenn **alle** Segmente auf `white` stehen;
sobald eines einen Effekt fährt, ist es RGB. Die Spanne ist 2700–6500 K, das
rechnet die Firmware auf die Weißkanäle um (`nl_ct.h`); Strips ohne
Weißkanäle bekommen dieselbe Spanne als RGB-Näherung.

Für einzelne Segmente gibt es noch keine Entitäten.

## Unterschiede zu ha-ninlight

Gleich sind: Einrichtung samt Neu-Konfigurieren und erneuter Anmeldung,
Diagnosedaten, Firmware-Aktualisierung, sACN, die Zeiten, das
Einschaltverhalten, „bei Änderung einschalten" und der Hinweis, wenn ein Gerät
noch auf dem Werks-Token steht.

Verschieden ist, was die Geräte verschieden macht:

- **Kein `sacn_layout`.** ninlight kann `dimmer` (Masterkanal plus Farben) und
  `rgb`; ein Strip hat keinen Masterkanal, ninstrip ist immer `rgb`. Die
  Firmware meldet das Feld trotzdem, damit dieselben Werkzeuge beide bedienen.
- **Farbe kommt aus den Segmenten**, bei ninlight aus `device/state`.
- **Szenen statt Farbmodi je Lampe**: acht Plätze in der Firmware, als
  Auswahl.
- **Leistungsbegrenzung als Sensor** — bei einer Lampe gibt es nichts zu
  begrenzen.

## Effekte

Die neun Effekte der Firmware (`device/effects`) stehen in der Lichtentität
zur Wahl — mit ihren **Namen**, nicht den Kennungen: angezeigt wird
„Regenbogen", geschickt wird `rainbow`. Ein gewählter Effekt läuft, wie eine
Farbe, in **allen** Segmenten; angezeigt wird er nur, wenn alle denselben
fahren.

Die Liste steht fest in der Firmware und wird deshalb **einmal** geholt, nicht
bei jeder Abfrage — erneut erst, wenn sich die Firmware-Version ändert.

Effekt-Parameter (Geschwindigkeit, Intensität, Palette) sind noch nicht
bedienbar; dafür braucht es Entitäten je Segment.

## Noch nicht drin

- Einzelne Segmente als eigene Entitäten
- Effekt-Parameter: Geschwindigkeit, Intensität, Palette

## Firmware-Aktualisierung

Aufbau wie ha-ninlight. Die Abbilder liegen im Ordner **`ninstrip_firmware`**
unterhalb des Konfigurationsverzeichnisses; `tools/release_images.sh` der
Firmware baut sie. Alle fünf Minuten wird der Ordner durchgesehen.

Home Assistant liefert das Abbild selbst aus, unter einer **einmaligen
Adresse**, die nur gilt, solange die Aktualisierung läuft. Das Gerät kann sich
bei Home Assistant nicht anmelden — der unratbare Schlüssel ist der Schutz.
Ausgeliefert werden genau die Bytes, die vorher geprüft wurden; wird die Datei
mittendrin überschrieben, ändert das nichts mehr an dem, was ankommt.

Drei Dinge entscheiden, ob ein Abbild angeboten wird:

- **Die Platine muss passen.** Verglichen wird `device_type` aus
  `system/info` mit dem Typ im NINL-Anhänger des Abbildes
  (`ninstrip-rgbc3`, `ninstrip-k1y`). `product` ist bei allen Platinen
  `ninstrip` und taugt dafür nicht: ein K1Y-Abbild invertiert das
  Datensignal, ein KL-RGBC3-Abbild nicht — die falsche Wahl lässt den Strip
  dunkel. Firmware vor `v0.1.0` meldet kein `device_type` und bekommt
  deshalb gar kein Angebot.
- **Die Version muss vergleichbar und neuer sein.** Gerechnet wird nach
  `git describe`, nicht mit der Versionslogik von Home Assistant: die hält
  `0.1.0-12-g71a57` und `0.1.0-47-g71a57` für denselben Versionskern.
  Firmware vor dem Tag `v0.1.0` meldete nur einen Hash — daran lässt sich
  keine Reihenfolge ablesen, also gibt es auch kein Angebot.
- **Die WLAN-Zugangsdaten müssen drin sein**, solange das Gerät sein WLAN
  nur aus der Firmware kennt (`wifi.source` = `compiled`). Sonst verlöre es
  nach dem Update seine Netzverbindung. Fehlen sie, erscheint ein Hinweis in
  den Reparaturen statt eines Angebots. Wer das Gerät über das Onboarding ins
  WLAN gebracht hat (`stored`), bekommt das Update ohne diesen Vorbehalt.

Die Geräte laden nur über **schlichtes http**. Erreichen sie die interne
Adresse von Home Assistant nicht so, trägt man in den Einstellungen der
Integration eine eigene ein (`http://…`, höchstens so lang, dass die ganze
Firmware-Adresse unter 255 Zeichen bleibt — mehr nimmt das Gerät nicht an).

## sACN / E1.31

Aufbau wie ha-ninlight: die Einstellungen kommen aus `system/settings`, der
Zustand aus `system/info`, und nach jedem Schreiben wird **zurückgelesen**
statt angenommen — das Gerät prüft selbst, und eine Entität, die das
Gewünschte statt des Gespeicherten zeigt, lügt genau dann, wenn beides
auseinanderläuft.

Zwei Unterschiede zu ninlight:

- **Kein Layout-Feld.** ninstrip nutzt fest drei Kanäle je Pixel (R, G, B), so
  wie LedFx, xLights und Resolume senden.
- **Der Startslot gilt in jedem Universe**, nicht nur im ersten — ein Strip
  verteilt sich über mehrere. Die Obergrenze ist deshalb `513 − 3 = 510`:
  dahinter passt kein ganzes Pixel mehr hinein.

Jede Änderung über Home Assistant holt einem laufenden oder gehaltenen Strom
die Kontrolle ab — das erledigt die Firmware.

**Multicast über VLAN-Grenzen:** „beigetreten" heißt nur, dass das Gerät der
Gruppe beigetreten ist. Ob das Netz sie weiterreicht, steht auf einem anderen
Blatt; ohne Multicast-Router kommt sie über eine VLAN-Grenze nie an. Unicast
geht dann trotzdem.

## Entwicklung

Die Integration wird in der gemeinsamen Dev-Instanz `ha-dev` per Mount
eingebunden, der Quellcode bleibt in diesem Repo.

### Markenbilder

Die vier PNGs unter `custom_components/ninstrip/brand/` sind **dieselben wie
in ha-ninlight**: die beiden Integrationen gehören zusammen, und zwei
verschiedene Motive in derselben Geräteübersicht stiften nur Verwirrung. Ab
Home Assistant 2026.3 liefert HA sie für eine eigene Integration von dort
aus; ohne sie bleibt ein Platzhalter.

`scripts/make_brand.py` zeichnet ein eigenes Motiv (ein Band mit fünf
leuchtenden Pixeln) und liegt als Ausgangspunkt bereit, falls doch einmal
eines gewünscht ist — in Gebrauch ist es nicht.

### Tests

```
uv venv -p /opt/homebrew/opt/python@3.14/bin/python3.14 .venv
uv pip install --python .venv/bin/python -r requirements_dev.txt
./scripts/check.sh
```

`scripts/check.sh` ersetzt die CI — das Repo liegt in einem privaten Gitea
ohne Actions — und läuft über ruff, die Tests samt Abdeckung (mindestens 95 %)
und die Übersetzungen.

Die Tests liegen in zwei Ordnern: **`tests_unit/`** kommt ohne
Home-Assistant-Instanz aus (API-Client gegen einen echten lokalen Server,
Anhänger, Versionsreihenfolge, Adressen), **`tests/`** fährt eine
Home-Assistant-Instanz hoch. Die Nutzdaten in `tests_unit/samples.py` sind an
echten Geräten abgefragt, keine erfundenen.

Die Python-Version ist nicht beliebig: Home Assistant 2026.9 verlangt
mindestens 3.14.2, und auf PyPI liegt diese HA-Version nur für uv bereit.