ninharp
8c9a9210d9
Die README behauptete noch, das Token stehe einmalig auf der seriellen Konsole - seit der Umstellung auf das Werks-Token wie ninlight falsch. Dazu die Vertrauensgrenze, die bisher nur in der Firmware stand: wer im selben WLAN ist und das oeffentliche Token kennt, kann das Geraet steuern und Firmware aufspielen. Bewusst so, wie bei ninlight. Eine automatische Sicherheitspruefung hatte die Vorbelegung im Dialog beanstandet - die Begruendung gehoert deshalb auch hierher, nicht nur in die Firmware.
73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
# 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.
|