christianandClaude Opus 5
0867221a3c
Zwei Handhabungsprobleme, die zusammengehoeren.
Auf /zentrale gab es ueberhaupt keinen Knopf zum Zurueckgeben - den fand
man nur ueber den Direktlink, den man nach einer Uebernahme in der Hand
hatte. Wer stattdessen /zentrale aufrief, konnte nur weiter uebernehmen
und sah nicht, dass erst zurueckgesetzt werden muss.
Ausserdem rendern die POST-Endpunkte ihr Ergebnis direkt. Man blieb also
auf /api/zentrale/uebernehmen stehen: eine Adresse, die beim Neuladen die
Aktion wiederholt und den Zustand nicht widerspiegelt.
Neu:
- Zwei Schritte. /zentrale fragt nur die Durchwahl ab und leitet auf
/zentrale/{durchwahl} um. Diese Zustandsseite ist die Adresse fuer den
Alltag, als Lesezeichen oder QR-Code, und ist gefahrlos neu ladbar.
- Die Knoepfe richten sich nach der Lage: frei -> besetzen, fremd besetzt
-> uebernehmen samt Hinweis was mit dieser Person passiert, selbst
besetzt -> zurueck auf mein Tuerschild, eigener Stammplatz -> kein
Knopf, nur der Hinweis dass nichts zu tun ist.
- Alle Aktionen antworten mit POST/Redirect/GET auf die Zustandsseite und
uebergeben nur einen kurzen Code fuer die Bestaetigung. Die Einzelheiten
- wer sitzt drauf, wer wartet, wer blockiert den Heimatplatz - leitet
die Seite bei jedem Aufruf frisch aus dem echten Zustand ab.
- Die allgemeine Seite nennt den aktuellen Besetzer und, falls vorhanden,
wer bei einer Freigabe automatisch zurueckkommt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
392 lines
15 KiB
Markdown
392 lines
15 KiB
Markdown
# 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](docs/azure-einrichtung.md))
|
|
- Optional: Zeiterfassung per CSV oder REST API
|
|
- Optional: Telefonanlage mit Webhook-Unterstuetzung (z.B. Starface)
|
|
|
|
## Installation
|
|
|
|
### Schnellinstallation (Debian 13)
|
|
|
|
```bash
|
|
curl -s https://git.cynfo.net/christian/busylight_modular/raw/branch/master/install.sh | bash
|
|
```
|
|
|
|
### Manuelle Installation
|
|
|
|
```bash
|
|
# 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](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):
|
|
|
|
```bash
|
|
# 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** |
|
|
| jemand anderes sitzt darauf | **Zentrale uebernehmen**, mit Hinweis was mit dieser Person passiert |
|
|
| man sitzt selbst darauf | **Zurueck auf mein Tuerschild** |
|
|
| es ist der eigene Stammplatz | kein Knopf, nur der Hinweis dass nichts zu tun ist |
|
|
|
|
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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
# 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](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`
|