LED-Uhr – Duality Seven mit Twitch & Stream Deck Steuerung

Interaktive 7-Segment LED-Uhr auf Basis des Duality Seven Modular LED Clock and Display System (3D-gedruckt, ESP32, 120x WS2812B NeoPixel), erweitert um eine HTTP-API für Stream Deck und einen Twitch-Bot, der Channel Points Redemptions in Echtzeit auf die Uhr überträgt.

Überblick

Twitch Chat (Channel Points)
    ↓
Twitch EventSub – WebSocket
    ↓
Bot-Service (Node.js, bot/)
    ↓
HTTP-Request → ESP32 (firmware/)
    ↓
LED-Uhr aktualisiert Ziffernfarbe
    ↑
    └─ Stream Deck (direkter HTTP-Request, gleiches Netz wie die Uhr)

Ordnerstruktur

• firmware/ – Arduino-Sketch für den ESP32 (Original Duality-Seven-Firmware + eigene HTTP-API-Erweiterung für Stream Deck/Twitch-Bot, Blynk-Steuerung bleibt als Fallback erhalten)
• bot/ – Node.js Twitch-EventSub-Bot (WebSocket-basiert, kein öffentlicher Endpoint nötig)
• 3d-models/ – STL-Dateien für den 3D-Druck (Segmente, Connectors, Gehäuse für ESP32-S/ESP32-S3-Mini, Skins)
• docs/ – Original-Anleitungen und Referenz-PDFs (Guide, Pixel-Layout, Connector-/Segment-Layout, Blynk-Widgets/Datastreams)

Hardware

• ESP32 Microcontroller (Varianten für ESP32-S und ESP32-S3-Mini im Gehäuse-STL enthalten)
• 120x WS2812B addressable LEDs
• 3D-gedrucktes modulares Gehäuse (Duality Seven System)

Firmware: HTTP-API

Die Firmware läuft parallel mit Blynk und stellt zusätzlich eine eigene HTTP-API bereit (via ESPAsyncWebServer), abgesichert mit einem Token-Header:

GET  /api/status                          # Aktuelle Farben, Modus, IP
POST /api/color?r=255&g=0&b=0&slot=1      # Farbe setzen (slot 1, 2 oder beide)
POST /api/mode?display=1                  # Display-Modus (1=Zeit, 2=Datum)
POST /api/preset?name=red                 # Farb-Preset (red, green, blue, yellow, redgreen, redblue, yellowblue, pinkred, chaos)

Alle Requests brauchen den Header X-API-Token: <dein-token>.

Wichtig: Presets ändern nur die Farbe der Ziffern (Vordergrund) – die Uhrzeit bleibt immer ablesbar. Die Farbe bleibt dauerhaft bestehen, bis der nächste Reward/Request eine neue Farbe setzt (kein Auto-Revert) – außer beim chaos-Preset: 30 Sekunden lang wechseln die Farben zufällig alle 150ms, danach automatischer Sprung zurück zur vorherigen Farbe. Jeder andere Request bricht ein laufendes Chaos sofort ab.

Vor dem Flashen anpassen

bool USE_STATIC_IP = true;
IPAddress local_IP(10, 10, 10, 60);   // eigene IP anpassen
IPAddress gateway(10, 10, 10, 254);   // eigenes Gateway anpassen
const char* API_TOKEN = "CHANGE_ME_SECRET_TOKEN";  // eigenes Token setzen

Benötigte Libraries: AsyncTCP, ESPAsyncWebServer, ArduinoJson, NeoPixelBus, ezTime, BlynkSimpleEsp32.

Bot: Twitch EventSub Integration

Node.js-Service, der per WebSocket mit Twitch EventSub verbunden bleibt (kein Webhook, keine öffentliche IP nötig) und Channel-Points-Redemptions an die ESP32-HTTP-API weiterleitet.

Features:

• EventSub via WebSocket, automatischer Reconnect
• Token-Refresh automatisiert
• Live-Check: Redemptions wirken nur, wenn der Kanal tatsächlich streamt (stream.online/stream.offline)
• Globaler Cooldown: 10s Mindestabstand zwischen JEDER Redemption, unabhängig vom Reward (verhindert Farb-Chaos durch schnelles Durchklicken verschiedener Rewards)
• Cleanup verwaister EventSub-Subscriptions bei jedem Neustart

Setup

cd bot
npm install
cp .env.example .env
nano .env   # Twitch Client ID/Secret, Tokens, Broadcaster-ID, ESP32-URL + Token eintragen
nano reward-mapping.json   # Reward-Titel exakt wie im Twitch-Dashboard eintragen
node index.js

Für Dauerbetrieb: led-uhr-twitch-bot.service als systemd-Unit einrichten (z.B. in einem LXC-Container im Heimnetz).

Twitch App registrieren

1. https://dev.twitch.tv/console/apps → Neue App, Redirect URL http://localhost:3000/callback, Category "Chat Bot"
2. Autorisierungs-Link öffnen: https://id.twitch.tv/oauth2/authorize?client_id=<ID>&redirect_uri=http://localhost:3000/callback&response_type=code&scope=channel:read:redemptions
3. Code aus der Redirect-URL gegen Access + Refresh Token tauschen (POST https://id.twitch.tv/oauth2/token)
4. Broadcaster-ID per GET https://api.twitch.tv/helix/users?login=<name> ermitteln

Reward-Mapping

bot/reward-mapping.json verknüpft den exakten Reward-Titel aus dem Twitch-Dashboard mit einem API-Aufruf:

{
  "Mein Reward-Titel": { "endpoint": "/api/preset", "params": { "name": "red" } }
}

Cooldown-Empfehlung im Twitch-Dashboard: 60 Sekunden pro Reward.

Stream Deck Steuerung

Plugin "HTTP Requests" (BarRaider) aus dem Stream-Deck-Store installieren. Pro Button:

• URL: http://<esp32-ip>/api/preset?name=red (oder /api/mode?display=1 etc.)
• Method: POST (bzw. GET für /api/status)
• Headers: X-API-Token: <dein-token>

Alle verfügbaren Endpoints/Presets siehe Abschnitt "Firmware: HTTP-API" oben. Stream Deck und ESP32 sollten im selben Netzwerk hängen für direkten, latenzarmen Zugriff ohne Umweg über den Bot.

3D-Druck

Alle STLs im 3d-models/-Ordner, basierend auf dem Duality Seven System. Vollständige Bauanleitung, Pixel-Layout und Connector-/Segment-Layout in docs/.

Netzwerk-Hinweis

Bot und ESP32-Uhr müssen sich gegenseitig erreichen können. In der Referenz-Installation läuft die Uhr im WLAN-Netz, der Bot in einem separaten Server-Netz (LXC-Container) – geroutet über eine gemeinsame Firewall. Bei Einzel-Netz-Installationen entfällt dieser Schritt.