busylight_modular/README.md

Busylight WLED Controller

Web-Anwendung zur Steuerung von WLED-Busylights basierend auf Microsoft Teams Presence-Status, Zeiterfassung und Telefonanlage (Webhook).

Jedes WLED-Geraet verfuegt ueber zwei Segmente (oben/unten), die jeweils einem Benutzer zugeordnet werden. Die Farbe des Segments wird automatisch anhand des Anwesenheitsstatus, des Teams-Status und des Telefonstatus gesetzt.

Features

• Dashboard mit Echtzeit-Uebersicht aller Busylights (Zeiterfassungs-, Teams- und Telefon-Status als Badges)
• Benutzer-Verwaltung mit automatischem Sync aus Microsoft Entra ID (Azure AD)
• WLED-Geraete hinzufuegen, bearbeiten, entfernen mit automatischem Status-Check (online/offline, LED-Anzahl, Firmware)
• Zuordnung von Benutzern zu WLED-Segmenten per Dropdown
• Farb-Regeln mit Color-Picker fuer jeden Status
• Telefon-Webhook fuer Telefonanlage (callstart/callend auf Port 8081)
• Modulare Zeiterfassung per CSV oder REST API - kompatibel mit jeder Zeiterfassung
• Webbasierte Azure-Authentifizierung direkt im Browser (kein Terminal noetig)
• Zentrale (Self-Service) - wechselnde Besetzung des Empfangs-Busylights per Durchwahl, ohne Admin-Passwort
• Eigenes Logo pro Kunde hochladbar, ueberlebt Updates
• Einstellungen fuer Azure, Polling-Intervall und Zeiterfassung
• Protokoll der letzten Statusaenderungen

Funktionsweise

Quelle	Beschreibung	Auswirkung auf WLED
Zeiterfassung	Anwesend / Abwesend / Homeoffice	Grundfarbe (gruen / aus / gelb)
Microsoft Teams	Verfuegbar / Beschaeftigt / Nicht stoeren / etc.	Farbe wenn anwesend
Telefonanlage (Webhook)	Telefoniert / Frei	Rot wenn aktiv, danach zurueck auf Zeiterfassungs-Status

Prioritaet: Telefon > Teams > Zeiterfassung. Die WLED-Farbe wird nur gesetzt wenn der Mitarbeiter laut Zeiterfassung anwesend oder im Homeoffice ist.

Voraussetzungen

• Linux-Server (Debian 13+ empfohlen)
• Python 3.10+
• Netzwerkzugriff auf die WLED-Geraete (HTTP Port 80)
• Microsoft Entra ID App-Registrierung (siehe Azure-Einrichtung)
• Optional: Zeiterfassung per CSV oder REST API
• Optional: Telefonanlage mit Webhook-Unterstuetzung (z.B. Starface)

Installation

Schnellinstallation (Debian 13)

curl -s https://git.cynfo.net/christian/busylight_modular/raw/branch/master/install.sh | bash

Manuelle Installation

# Repository klonen
git clone https://git.cynfo.net/christian/busylight_modular.git /opt/busylight
cd /opt/busylight

# Python Virtual Environment erstellen
python3 -m venv venv
source venv/bin/activate

# Abhaengigkeiten installieren
pip install -r requirements.txt

Einrichtung

1. Azure verbinden

Detaillierte Anleitung: docs/azure-einrichtung.md

Kurzfassung:

1. App-Registrierung in Azure erstellen
2. Oeffentliche Clientflows aktivieren
3. API-Berechtigungen setzen (User.Read.All, Presence.Read.All)
4. Im Web-Interface unter Einstellungen die IDs eintragen
5. Auf "Mit Azure verbinden" klicken und im Browser anmelden

2. Benutzer synchronisieren

Unter Benutzer auf "Aus Azure synchronisieren" klicken. Anschliessend:

• Benutzer aktivieren/deaktivieren (nur aktive Benutzer werden abgefragt)
• Personalnummer zuordnen (fuer Zeiterfassung)
• Telefon-Durchwahl zuordnen (fuer Starface-Webhook)

3. WLED-Geraete anlegen

Unter Tuerschilder die Hostnamen/IP-Adressen der WLED-Busylights eintragen. Der Status (online/offline, LEDs, Firmware) wird automatisch alle 4 Minuten geprueft.

4. Zuordnungen erstellen

Unter Zuordnungen jeden aktiven Benutzer einem WLED-Geraet und Segment zuweisen:

• Segment 0 = unten
• Segment 1 = oben

5. Farben anpassen

Unter Farb-Regeln die Farben fuer jeden Status per Color-Picker anpassen:

Status	Beschreibung
abwesend	Benutzer nicht anwesend
homeoffice	Benutzer im Homeoffice
phone_active	Benutzer telefoniert (Webhook)
teams_available	Teams: Verfuegbar
teams_busy	Teams: Beschaeftigt
teams_donotdisturb	Teams: Nicht stoeren
teams_inacall	Teams: In einem Anruf
teams_inameeting	Teams: In einer Besprechung
teams_presenting	Teams: Praesentiert
teams_away	Teams: Abwesend
teams_offline	Teams: Offline
teams_outofoffice	Teams: Abwesend (ganztaegig)
teams_inactive	Teams: Inaktiv
teams_offwork	Teams: Nicht bei der Arbeit

Zeiterfassung

Die Zeiterfassung ist modular - es gibt zwei Wege den Anwesenheitsstatus zu liefern:

Option A: CSV-Datei

Eine CSV-Datei mit dem Anwesenheitsstatus wird periodisch gelesen. Das Format:

~~00100~~,~~1~~
~~00101~~,~~0~~
~~00102~~,~~2~~

Status-Codes (konfigurierbar in den Einstellungen):

• ~~0~~ = Abwesend
• ~~1~~ = Anwesend
• ~~2~~ = Homeoffice

Die CSV kann von jedem Zeiterfassungssystem per Script erzeugt werden. In den Einstellungen den Pfad zur CSV eintragen.

Option B: REST API

Externe Systeme koennen den Status direkt per API setzen (Port 8081):

# Status setzen
curl -X POST -H "Content-Type: application/json" \
  -d '{"status":"anwesend"}' \
  http://SERVER:8081/api/attendance/00100

# Alle Status abfragen
curl http://SERVER:8081/api/attendance

Beide Optionen koennen parallel genutzt werden.

Telefonanlage (Webhook)

Die Anwendung startet automatisch einen Webhook-Server auf Port 8081 fuer die Anbindung einer Telefonanlage (z.B. Starface).

Webhook-Endpoints

GET/POST  http://SERVER:8081/{durchwahl}/callstart   - Anruf gestartet (WLED -> Rot)
GET/POST  http://SERVER:8081/{durchwahl}/callend     - Anruf beendet (WLED -> zurueck auf Zeiterfassungs-Status)

Einrichtung

1. Unter Benutzer im Web-Interface die Durchwahl pro User eintragen (z.B. 123)
2. In der Telefonanlage den Webhook konfigurieren:
   • Anrufbeginn: http://SERVER-IP:8081/123/callstart
   • Anrufende: http://SERVER-IP:8081/123/callend

Verhalten

• callstart: Setzt WLED auf Telefon-Farbe (Standard: Rot), aber nur wenn der Mitarbeiter laut Zeiterfassung anwesend oder im Homeoffice ist
• callend: Setzt WLED zurueck auf den Zeiterfassungs-Status. Der Teams-Status wird beim naechsten Polling-Zyklus (15s) automatisch aktualisiert
• Waehrend eines aktiven Telefonats ueberschreibt das Teams-Polling die Farbe nicht
• Die Telefon-Farbe (phone_active) ist unter Farb-Regeln konfigurierbar

Logo

Unter Einstellungen > Logo kann ein kundenspezifisches Logo hochgeladen werden. Es erscheint in der Seitenleiste, auf der Login-Seite und auf der Zentrale-Seite.

• Formate: PNG, JPG, SVG, WEBP, GIF, maximal 2 MB
• Dargestellt wird eine Hoehe von etwa 40 Pixeln. Die Seitenleiste ist dunkel, ein Logo mit heller Schrift oder transparentem Hintergrund wirkt dort am besten - die Einstellungsseite zeigt eine Vorschau auf hellem und dunklem Grund.
• Die Datei liegt unter static/custom/ und ist per .gitignore von der Versionierung ausgenommen. Ein git pull ueberschreibt das Kundenlogo nicht.
• Mit Zurueck zum Standardlogo wird die Datei entfernt und wieder static/logo.png aus dem Repository verwendet.

Zentrale (Self-Service)

Ein Busylight im Empfangsbereich wird wechselnd besetzt. Damit die Mitarbeiter das selbst umstellen koennen, gibt es eine eigene Seite, die ohne Admin-Passwort erreichbar ist und die Durchwahl als Kennung nutzt.

Einrichtung

1. Unter Benutzer die Durchwahl pro Mitarbeiter eintragen (dieselbe wie fuer den Telefon-Webhook)
2. Unter Einstellungen > Zentrale (Self-Service) das Busylight des Empfangs und das Segment auswaehlen
3. Die Seite http://SERVER:8080/zentrale an die Mitarbeiter geben

Bedienung

http://SERVER:8080/zentrale              - Durchwahl eingeben
http://SERVER:8080/zentrale/{durchwahl}  - Zustandsseite pro Person, als Lesezeichen
                                           oder QR-Code

Die Bedienung laeuft in zwei Schritten. Auf /zentrale gibt man seine Durchwahl ein und landet auf der eigenen Zustandsseite /zentrale/{durchwahl}. Dort steht, wer gerade auf der Zentrale sitzt und welche Knoepfe zur Verfuegung stehen - geaendert wird erst per Klick.

Die Zustandsseite ist die eigentliche Adresse fuer den Alltag und als Lesezeichen gedacht. Sie zeigt immer den echten Zustand, passt die Knoepfe daran an und ist gefahrlos neu ladbar:

Lage	Angebot
Zentrale frei	Zentrale besetzen, ohne Rueckfrage
jemand anderes sitzt darauf	Zentrale uebernehmen mit Rueckfrage, siehe unten
man sitzt selbst darauf	Zurueck auf mein Tuerschild
es ist der eigene Stammplatz	kein Knopf, nur der Hinweis dass nichts zu tun ist

Rueckfrage beim Verdraengen

Sitzt bereits jemand anderes auf der Zentrale, kommt vor der Uebernahme eine Rueckfrage. Sie nennt die betroffene Person und was mit ihr passiert:

• sie gehoert auf die Zentrale und kommt automatisch zurueck, sobald wieder freigegeben wird
• sie hat ein eigenes Tuerschild und wird dorthin zurueckgesetzt
• sie hat kein eigenes Tuerschild und wird als Stamm-Besetzer vermerkt

Eine Rueckgabe wird dagegen nicht erzwungen, und das ist Absicht: wer abends ohne Freigabe nach Hause geht, wuerde die Zentrale sonst sperren. Am naechsten Morgen koennte niemand den Empfang besetzen, weil der Vorgaenger nicht da ist um freizugeben, und es muesste jedes Mal ein Administrator eingreifen. Die Rueckfrage verhindert das versehentliche Verdraengen, ohne diese Sperre zu erzeugen.

Jede Aktion leitet auf diese Seite zurueck (POST/Redirect/GET). Man landet also nie auf einer Formular-Antwort, die beim Neuladen die Aktion wiederholen wuerde, und sieht nach jedem Klick den neuen Zustand samt Bestaetigung.

Verhalten

• Zentrale uebernehmen: Der Mitarbeiter wird auf das Segment der Zentrale gesetzt. Das eigene Tuerschild gibt er dabei ab, weil ein Mitarbeiter nur einer Zuordnung gleichzeitig zugewiesen sein kann. Der alte Platz wird gemerkt und das Segment ausgeschaltet.
• Zurueck auf mein Tuerschild: Der gemerkte Platz wird wiederhergestellt und die Zentrale freigegeben (Farbe abwesend, Standard: aus).
• Vorgaenger mit eigenem Tuerschild: Wer die Zentrale abgibt, wird dabei automatisch auf sein eigenes Tuerschild zurueckgesetzt. Er muss also nicht erst selbst "zurueck" klicken, damit der Nachfolger uebernehmen kann. Ist sein Tuerschild inzwischen jemand anderem zugeordnet, bleibt er ohne Zuordnung - die Meldung nennt dann, wer dort sitzt.
• Stamm-Besetzer der Zentrale: Wer normalerweise auf der Zentrale sitzt und kein eigenes Tuerschild hat, wird beim ersten Verdraengen als Stamm-Besetzer vermerkt. Er kommt automatisch zurueck, sobald die Zentrale wieder freigegeben wird - egal wie viele Vertretungen sich zwischenzeitlich abgewechselt haben. Sein Vermerk bleibt dauerhaft stehen, denn die Zentrale ist sein normaler Platz und keine Vertretung.
• Der Stamm-Besetzer selbst braucht "Zurueck auf mein Tuerschild" nicht: sein Platz ist die Zentrale. Klickt er es trotzdem, aendert sich nichts und die Seite sagt es ihm.
• Belegter Heimatplatz: Ist das eigene Tuerschild inzwischen jemand anderem zugeordnet, wird die Rueckkehr abgelehnt und nichts geaendert. Dann muss der Administrator die Zuordnung aufloesen.
• Sofortiges Umschalten: Die Farbe wird direkt ans Geraet geschickt. Das Polling allein wuerde nicht reichen, weil es nur bei einer Statusaenderung sendet und der Status des Mitarbeiters beim Platzwechsel unveraendert ist.
• Protokoll: Jeder Wechsel landet unter Protokoll (zentrale beim Uebernehmen, zentrale_frei beim Freigeben).
• Vorrang des Administrators: Wird ein Mitarbeiter unter Zuordnungen neu zugeordnet, verfaellt sein gemerkter Heimatplatz - die ausdrueckliche Zuordnung gilt. Wird seine Zuordnung dort nur geloescht, bleibt der gemerkte Platz erhalten, damit er von der Zentrale zurueckkehren kann.

Sicherheit

Die Durchwahl ist eine Kennung, kein Geheimnis. Wer Port 8080 erreicht, kann jeden Kollegen auf die Zentrale setzen. Fuer den internen Gebrauch ist das gewollt - die Aenderung ist sofort sichtbar, im Protokoll nachvollziehbar und mit einem Klick zurueckzunehmen. Die Seite gehoert deshalb nicht ins Internet.

Starten

Manuell (zum Testen)

cd /opt/busylight
source venv/bin/activate
python app.py

Dabei werden zwei Server gestartet:

• Port 8080: Web-Oberflaeche
• Port 8081: Webhook-Server (Telefonanlage + Zeiterfassungs-API)

Als systemd-Service (Produktivbetrieb)

# Service installieren (bei manueller Installation)
sudo cp busylight.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now busylight

# Status pruefen
sudo systemctl status busylight

# Logs anzeigen
sudo journalctl -u busylight -f

# Update
cd /opt/busylight && git pull
sudo systemctl restart busylight

Dashboard

Das Dashboard zeigt alle Busylights mit dem aktuellen Status in Echtzeit an und aktualisiert sich automatisch alle 10 Sekunden. Pro Benutzer werden drei Status-Badges angezeigt:

• Zeiterfassung: Anwesend (gruen) / Abwesend (grau) / Homeoffice (gelb)
• Teams: Verfuegbar / Beschaeftigt / Nicht stoeren / Offline / etc.
• Telefon: Telefoniert (rot) / Frei (grau)

Hintergrund-Jobs

Job	Intervall	Beschreibung
Status-Polling	15 Sekunden (konfigurierbar)	Teams-Presence und Zeiterfassungs-Status abfragen, WLED aktualisieren
Device-Check	240 Sekunden	Alle WLED-Geraete auf Erreichbarkeit pruefen

Projektstruktur

busylight/
├── app.py              # FastAPI Web-Anwendung + Azure Auth + Startup
├── webhook.py          # Webhook-Server + Zeiterfassungs-API (Port 8081)
├── database.py         # SQLite Datenbank-Schema und Hilfsfunktionen
├── graph_client.py     # Microsoft Graph API Client
├── wled_client.py      # WLED HTTP API Client
├── scheduler.py        # Hintergrund-Jobs (Polling + Device-Check)
├── install.sh          # Installer fuer Debian 13
├── requirements.txt    # Python-Abhaengigkeiten
├── busylight.service   # systemd Service-Datei
├── docs/               # Dokumentation
├── static/
│   └── style.css       # CSS Styles
└── templates/          # Jinja2 HTML-Templates (u.a. zentrale.html)

Ports und Firewall

Port	Richtung	Zweck
8080/tcp	Eingehend	Web-Oberflaeche
8081/tcp	Eingehend	Webhook-API (Telefon + Zeiterfassung)
80/tcp	Ausgehend	WLED HTTP API
443/tcp	Ausgehend	Microsoft Graph API

Troubleshooting

Dashboard zeigt nur graue Segmente

• Zeiterfassung pruefen (CSV-Pfad oder API-Status)
• Benutzer muessen aktiviert sein UND eine Personalnummer haben
• Zuordnung Benutzer -> WLED-Geraet + Segment muss vorhanden sein

Teams-Status wird nicht angezeigt

• Azure-Authentifizierung pruefen (Sidebar zeigt "Azure verbunden")
• API-Berechtigungen in Azure pruefen (Presence.Read.All)

Telefon-Webhook reagiert nicht

• Port 8081 erreichbar? curl http://SERVER:8081/
• Durchwahl beim Benutzer eingetragen?
• Benutzer muss laut Zeiterfassung anwesend oder im Homeoffice sein

Azure Auth schlaegt fehl

• "Oeffentliche Clientflows zulassen" muss in der Azure App aktiviert sein
• Siehe docs/azure-einrichtung.md fuer Details

WLED-Geraete offline

• Unter Tuerschilder den Status pruefen ("Alle jetzt pruefen")
• Netzwerkverbindung pruefen: curl http://HOSTNAME/json/info

Auf /zentrale fehlt der Knopf zum Zurueckgeben

Der ist absichtlich erst auf der Zustandsseite /zentrale/{durchwahl} zu sehen, denn vorher weiss die Anwendung nicht, wer zurueckgeben will. Durchwahl eingeben, Weiter klicken - dann erscheint der passende Knopf.

Zentrale-Seite sagt "noch nicht eingerichtet"

Unter Einstellungen > Zentrale (Self-Service) ist kein Busylight ausgewaehlt. Ohne diese Einstellung weiss die Anwendung nicht, welches Geraet der Empfang ist.

Durchwahl wird auf der Zentrale-Seite nicht erkannt

Die Durchwahl muss unter Benutzer exakt so eingetragen sein wie eingegeben, und der Benutzer muss aktiv sein. Inaktive Benutzer werden bewusst abgewiesen.

Nach git pull aendert sich nichts

• Service neustarten: sudo systemctl restart busylight