Für Entwickler
HyperLED ist Open Source (EUPL-1.2) und freut sich über Beiträge. Diese Seite zeigt, wo was liegt. Die ausführliche, stets aktuelle technische Dokumentation steht im Ordner docs/ des Repositorys.
Die Teile
| Teil | Wo | Was |
|---|---|---|
| Master-Firmware | HyperLED (Wurzel dieses Repositorys) | PlatformIO-Projekt für den ESP32-S3: LED-Engine, WLAN, Webserver, MQTT, Updates, Plugins. |
| Weboberfläche | data/ im selben Repository |
Schlichtes HTML, CSS und JavaScript. Kein Build-Schritt; sie wird mit pio run -t uploadfs auf das Board geschrieben. |
| Slave-Firmware | HyperLED-Slave | Ein eigenes Repository und PlatformIO-Projekt für Slave-Boards. |
| Plugins | plugins/ und zum Beispiel Klipper Status Display |
Kleine JSON-Dateien, wahlweise mit Lua-Skript. |
Bauen und flashen
pio run # bauen (Standard-Umgebung: esp32-s3) pio run -t upload # bauen und Firmware flashen pio run -t uploadfs # bauen und Weboberfläche (data/) flashen pio device monitor # serieller Monitor, 115200 Baud
Hardware: der Waveshare ESP32-S3-Zero (ESP32-S3FH4R2, 4 MB Flash und 2 MB PSRAM) für Master und Slave. Die Partitionstabelle hat zwei Update-Plätze und ein kleines Dateisystem; siehe partitions.csv.
Es gibt keine Unit-Tests; Änderungen werden auf echter Hardware geprüft, indem man die serielle Ausgabe und die Weboberfläche beobachtet.
Wie die Firmware aufgebaut ist
src/main.cpp startet eine feste Reihe von Singleton-„Managern“, jeder mit begin() und loop(), in dieser Reihenfolge:
LEDManager → WiFiManager → WebServerManager → MqttManager → UpdateManager → SlaveManager → ButtonManager
- LEDManager: LED-Treiber, Segmente, Effekt-Engine, Matrix-Abbildung und Helligkeitsbegrenzer.
- WiFiManager: Verbindung als Station mit einem Captive-Portal-Zugangspunkt als Rückfall.
- WebServerManager: der Webserver und die
/api/-Routen. - MqttManager: MQTT und Home-Assistant-Erkennung.
- UpdateManager: Online-Updates von Firmware und Weboberfläche.
- SlaveManager: findet Slaves und schickt ihnen Konfiguration und Daten über den HyperBus.
- ButtonManager: die zwei physischen Eingänge.
- PluginManager (mit Plugin-Parser, Ausdruckssprache und Lua-Host): das Plugin-System.
HyperBus
Das Master/Slave-Protokoll: Rahmen mit Startbyte, Kopf, Nutzdaten und CRC16, über eine UART-Verbindung oder ESP-NOW. Die Kopfdatei HyperBus.h gibt es in beiden Repositories, und sie muss identisch bleiben. Beschreibung: Master/Slave-Architektur.
HTTP-API
Alles, was die Weboberfläche tut, läuft über eine JSON-API, die du aus Skripten nutzen kannst: Zustand, Segmente, Presets, Panels und Elemente, Slaves, Plugins, Netzwerk, Updates, MQTT und Sicherung. Die ganze Liste: API-Referenz.
Ein Vorgeschmack:
curl http://hyperled.local/api/state # Zustand aller Segmente
curl -X POST http://hyperled.local/api/state \
-H "Content-Type: application/json" -d '{"on": "t"}' # alles umschalten
curl http://hyperled.local/api/log # die letzte Minute des Logs
Plugins und Skripte
- Plugins nutzen
- Plugins entwickeln: Dateiformat, Einstellungen, Werte und Regeln und die Ausdruckssprache
- Plugin-Skripte: Lua-Skripte, die ein Segment Pixel für Pixel zeichnen, auf dem Master oder auf einem Slave
Ein Plugin wird auf dem Controller vollständig geprüft, bevor es installiert wird (POST /api/plugins/preview prüft es, ohne etwas zu speichern).
Mitmachen
- Melde Fehler und Ideen als Issues.
- Quelldateien tragen den EUPL-Kopf; behalte ihn in neuen Dateien bei.
- Änderungen am Funkprotokoll gehören in beide Repositories.
- Die Texte der Weboberfläche stehen in
data/i18n.jsauf Deutsch, Englisch und Russisch. - Halte die Dokumentation in
docs/im Gleichschritt mit Änderungen an der API oder am Netzwerkcode.