# Technische Details

## Hardware

### LED-Leiste

Die LED-Leiste besteht aus SK6812-LEDs, die einzeln angesteuert werden können. Jede LED enthält vier LED-Chips in verschiedenen Farben: rot, grün, blau und (neutral-)weiß. Es gibt auch Varianten mit warm- und kaltweiß zu kaufen, die neutralweiße hat jedoch den Vorteil, dass die Farbtemperatur der weißen LED ziemlich gut dem Sonnenlicht entspricht und sich damit gut zur Farbmischung eignet.

Die Leiste ist 5m lang und enthält 300 LEDs.

### Mikrocontroller

Zur Ansteuerung der LED-Leiste kommt ein ESP32 zum Einsatz. Dabei handelt es sich um einen netzwerkfähigen Dual-Core-Mikrocontroller. Netzwerkfähig heißt in diesem Fall, dass er WLAN, Bluetooth Low Energy und auch Ethernet unterstützt. Außerdem hat er genug Rechenleistung, um auch auf dem Mikrocontroller direkt Animationen für die LEDs berechnen zu können.

Die Firmware ist in C++ mit dem Arduino-Framework und der PlatformIO-IDE programmiert. Der Code kann [auf meinem Gitea](https://git.tkolb.de/Public/esp32-sk6812/src/branch/bnb) heruntergeladen werden (der Git-Branch `bnb` enthalt die für’s ZAM relevanten Anpassungen).

## Ansteuerung im Netzwerk

### Adresse

Die LED-Leiste ist unter der Adresse **zamusiclight.im.zam.haus** im ZAM-Netzwerk erreichbar.

### Dienste

Folgende Dienste laufen auf dem ESP32:

- Ein HTTP-Server, über den die fest einprogrammierten Funktionen gesteuert werden können (Animationswechsel, Anzeige einfacher Farben) => [http://zamusiclight.im.zam.haus/](http://zamusiclight.im.zam.haus/)
- Ein UDP-Server, der die Echtzeitansteuerung ermöglicht. Dieser wird weiter unten genauer beschrieben.

**⚠️ Wichtig: Eine Ansteuerung über UDP „gewinnt“ immer gegenüber den Einstellungen auf dem HTTP-Server.** Sobald ein Kommando über UDP empfangen wurde, wird die interne Animation unterbrochen und das „Live-Bild“ angezeigt. Die interne Animation wird fortgesetzt, wenn für 3 Sekunden kein UDP-Paket empfangen wurde.

#### Der HTTP-Server

Der ESP32 stellt per HTTP eine sehr spartanische Startseite bereit, auf der einige vordefinierte Animationen umgeschaltet werden können. Da die Firmware ursprünglich für einen anderen Aufbau geschrieben wurde, sind manche Animationen noch nicht an den Aufbau im ZAM angepasst, also bitte nicht wundern, wenn mal etwas komisch aussieht.

Zusätzlich bietet der HTTP-Server eine API an, die z.B. das Setzen von Farben für die ganze Leiste ermöglicht, z.B. setzt folgendes ein hübsches Frühlingsgrün:

[http://zamusiclight.im.zam.haus/api/color?color=20800010](http://zamusiclight.im.zam.haus/api/color?color=20800010)

Es gibt auch eine API für Textanzeige, die aber am ZAM-Aufbau nicht sinnvoll umsetzbar ist:

[http://zamusiclight.im.zam.haus/api/text?text=Hallo%20ZAM!&color=20800010](http://zamusiclight.im.zam.haus/api/text?text=Hallo%20ZAM!&color=20800010)

#### Echtzeit-Ansteuerung über UDP

Der ESP32 wartet auf **Port 2703** auf Kommandos.

Ein Kommando ist wie folgt aufgebaut:

<table border="1" id="bkmrk-byte-0-1-2-3-4-5-6-b" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 16.6667%;">**Byte**</td><td style="width: 16.6667%;">0</td><td style="width: 11.9753%;">1</td><td style="width: 11.3581%;">2</td><td style="width: 10.6173%;">3</td><td style="width: 11.0494%;">4</td><td style="width: 9.96914%;">5</td><td style="width: 11.6975%;">6</td></tr><tr><td style="width: 16.6667%;">**Bedeutung**</td><td style="width: 16.6667%;">Kommandotyp</td><td style="width: 11.9753%;">Strip-Index</td><td style="width: 11.3581%;">LED-Index</td><td style="width: 10.6173%;">Rot-Wert</td><td style="width: 11.0494%;">Grün-Wert</td><td style="width: 9.96914%;">Blau-Wert</td><td style="width: 11.6975%;">Weiß-Wert</td></tr></tbody></table>

Es gibt folgende Kommandos zum Setzen bzw. Verändern von Farben:

- **Farbe setzen** (Kommandotyp **0x00**): setzt die gegebene LED direkt auf die gegebene Farbe.
- **Farbe überblenden** (Kommandotyp **0x01**): blendet die LED linear auf die gegebene Farbe über.
- **Farbe aufhellen** (Kommandotyp **0x02**): addiert die gegebene Farbe auf die aktuelle Farbe der LED.

Außerdem gibt es folgende Steuerbefehle. Für diese werden die Index-Bytes und Farbwerte speziell interpretiert:

- **Überblendgeschwindigkeit setzen** (Kommandotyp **0x03**): Setzt die Schrittweite pro Frame bei der Überblendung. Diese ist im Rot-Wert (Byte 3) angegeben, alle anderen Bytes werden ignoriert. Schrittweite 1 ist am langsamsten, Schrittweite 255 setzt die Farbe direkt.
- **Frame beenden** (Kommandotyp **0xFE**): Schließt den aktuellen Frame nach diesem Paket ab. Sollte das Paket noch weitere Kommandos enthalten, werden diese noch verarbeitet, es werden aber keine weiteren Pakete für diesen Frame gelesen. Die Bytes 1 bis 6 werden ignoriert.
- **Bestätigung anfordern** (Kommandotyp **0xFF**): Fordert eine Antwort vom ESP an. Die Antwort ist ein UDP-Paket mit 2 Bytes: das erste ist der Rot-Wert aus dem Kommando, das zweite der Grün-Wert. Dieses Kommando ist nützlich, um eine Flusskontrolle umsetzen zu können, indem in den beiden Bytes ein Zähler mitgeschickt wird. Hinkt dieser Zähler in den Antworten hinterher, weiß man, dass der ESP die Pakete nicht schnell genug verarbeiten kann. Dann sollte die Senderate gedrosselt werden.

In einem UDP-Paket können bis zu 210 Kommandos aneinandergereiht werden. Bei mehr Kommandos müsste das UDP-Paket fragmentiert werden, was der ESP32 nicht unterstützt. Pro Frame verarbeitet der ESP32 jedoch bis zu 3 UDP-Pakete.