docs: add README with installation and usage instructions
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
5267baf0b4
commit
a41849ff7d
209
README.md
Normal file
209
README.md
Normal file
@ -0,0 +1,209 @@
|
|||||||
|
# Busylight WLED Controller
|
||||||
|
|
||||||
|
Web-Anwendung zur Steuerung von WLED-Busylights basierend auf Microsoft Teams Presence-Status und AIDA-Zeiterfassung.
|
||||||
|
|
||||||
|
Jedes WLED-Gerät verfügt über zwei Segmente (oben/unten), die jeweils einem Benutzer zugeordnet werden. Die Farbe des Segments wird automatisch anhand des Anwesenheitsstatus (AIDA) und des Teams-Status gesetzt.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Dashboard** mit Echtzeit-Übersicht aller Busylights und deren aktuellem Status
|
||||||
|
- **Benutzer-Verwaltung** mit automatischem Sync aus Azure AD
|
||||||
|
- **WLED-Geräte** hinzufügen, bearbeiten und entfernen
|
||||||
|
- **Zuordnung** von Benutzern zu WLED-Segmenten per Dropdown (statt UUID-Mapping in einer Config-Datei)
|
||||||
|
- **Farb-Regeln** mit Color-Picker für jeden Teams-/Anwesenheitsstatus
|
||||||
|
- **Einstellungen** für Azure AD, Polling-Intervall und AIDA-CSV-Pfad
|
||||||
|
- **Protokoll** der letzten Statusänderungen
|
||||||
|
|
||||||
|
## Voraussetzungen
|
||||||
|
|
||||||
|
- Python 3.10+
|
||||||
|
- Netzwerkzugriff auf die WLED-Geräte (HTTP)
|
||||||
|
- Azure AD App-Registrierung mit folgenden Berechtigungen:
|
||||||
|
- `User.Read`, `User.Read.All`, `Presence.Read`, `Presence.Read.All`
|
||||||
|
- Zugriff auf die AIDA-Zeiterfassungs-CSV (lokal oder per SMB-Mount)
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Repository klonen
|
||||||
|
git clone https://git.cynfo.net/christian/busylight.git /opt/busylight
|
||||||
|
cd /opt/busylight
|
||||||
|
|
||||||
|
# Python Virtual Environment erstellen
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
|
||||||
|
# Abhängigkeiten installieren
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration von der alten config.cfg
|
||||||
|
|
||||||
|
Falls das System vorher mit dem alten Python-Script und `config.cfg` betrieben wurde, können alle Daten (User, Geräte, Segmente, Farben, Azure-Credentials) automatisch importiert werden:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# config.cfg ins Projektverzeichnis kopieren
|
||||||
|
cp /pfad/zur/alten/config.cfg .
|
||||||
|
|
||||||
|
# Migration ausführen
|
||||||
|
python migrate.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Die alte `config.cfg` wird danach nicht mehr benötigt.
|
||||||
|
|
||||||
|
## Azure Authentifizierung
|
||||||
|
|
||||||
|
Die Authentifizierung gegen Microsoft Graph erfolgt einmalig über den Device-Code-Flow im Terminal:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source venv/bin/activate
|
||||||
|
python app.py --auth
|
||||||
|
```
|
||||||
|
|
||||||
|
Es wird ein Code angezeigt, der unter https://microsoft.com/devicelogin eingegeben werden muss. Nach erfolgreicher Anmeldung wird das Token in der Datenbank gespeichert und automatisch erneuert.
|
||||||
|
|
||||||
|
## AIDA-CSV auf Linux bereitstellen
|
||||||
|
|
||||||
|
Die Zeiterfassungs-CSV liegt typischerweise auf einem Windows-Server. Für den Zugriff von Linux gibt es mehrere Möglichkeiten:
|
||||||
|
|
||||||
|
### Option A: SMB/CIFS-Mount (empfohlen)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Paket installieren
|
||||||
|
sudo apt install cifs-utils
|
||||||
|
|
||||||
|
# Mount-Punkt erstellen
|
||||||
|
sudo mkdir -p /mnt/zeiterfassung
|
||||||
|
|
||||||
|
# Eintrag in /etc/fstab
|
||||||
|
# //SERVERNAME/Zeiterfassung /mnt/zeiterfassung cifs credentials=/etc/samba/creds,uid=busylight,gid=busylight,ro 0 0
|
||||||
|
|
||||||
|
# Credentials-Datei erstellen
|
||||||
|
sudo bash -c 'cat > /etc/samba/creds << EOF
|
||||||
|
username=DOMAIN\user
|
||||||
|
password=geheim
|
||||||
|
EOF'
|
||||||
|
sudo chmod 600 /etc/samba/creds
|
||||||
|
|
||||||
|
# Mounten
|
||||||
|
sudo mount /mnt/zeiterfassung
|
||||||
|
```
|
||||||
|
|
||||||
|
In den Web-Einstellungen dann als CSV-Pfad eintragen:
|
||||||
|
```
|
||||||
|
/mnt/zeiterfassung/Aida/profiles/aida/Transfer/Export/Status.csv
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option B: Regelmäßiger Kopiervorgang
|
||||||
|
|
||||||
|
Per Cronjob die CSV regelmäßig auf den Linux-Server kopieren (z.B. via `scp` oder `rsync`).
|
||||||
|
|
||||||
|
## Starten
|
||||||
|
|
||||||
|
### Manuell (zum Testen)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source venv/bin/activate
|
||||||
|
python app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Die Web-Oberfläche ist dann erreichbar unter: **http://localhost:8080**
|
||||||
|
|
||||||
|
### Als systemd-Service (Produktivbetrieb)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Service-User anlegen
|
||||||
|
sudo useradd -r -s /usr/sbin/nologin busylight
|
||||||
|
sudo chown -R busylight:busylight /opt/busylight
|
||||||
|
|
||||||
|
# Service installieren
|
||||||
|
sudo cp busylight.service /etc/systemd/system/
|
||||||
|
sudo systemctl daemon-reload
|
||||||
|
sudo systemctl enable --now busylight
|
||||||
|
|
||||||
|
# Status prüfen
|
||||||
|
sudo systemctl status busylight
|
||||||
|
|
||||||
|
# Logs anzeigen
|
||||||
|
sudo journalctl -u busylight -f
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benutzung
|
||||||
|
|
||||||
|
### 1. Einstellungen konfigurieren
|
||||||
|
|
||||||
|
Unter **Einstellungen** die Azure AD Credentials (Client ID, Client Secret, Tenant ID) und den CSV-Pfad eintragen.
|
||||||
|
|
||||||
|
### 2. Benutzer synchronisieren
|
||||||
|
|
||||||
|
Unter **Benutzer** auf „Aus Azure synchronisieren" klicken. Alle Azure AD Benutzer werden importiert. Anschließend:
|
||||||
|
- Benutzer aktivieren/deaktivieren (nur aktive Benutzer werden abgefragt)
|
||||||
|
- AIDA-Personalnummer zuordnen (Format: `~~00341~~`)
|
||||||
|
|
||||||
|
### 3. WLED-Geräte anlegen
|
||||||
|
|
||||||
|
Unter **WLED-Geräte** die Hostnamen/IP-Adressen der WLED-Busylights eintragen und die Anzahl der Segmente festlegen (Standard: 2).
|
||||||
|
|
||||||
|
### 4. Zuordnungen erstellen
|
||||||
|
|
||||||
|
Unter **Zuordnungen** jeden aktiven Benutzer einem WLED-Gerät und Segment zuweisen:
|
||||||
|
- Segment 0 = oben
|
||||||
|
- Segment 1 = unten
|
||||||
|
|
||||||
|
### 5. Farben anpassen
|
||||||
|
|
||||||
|
Unter **Farb-Regeln** die Farben für jeden Status per Color-Picker anpassen:
|
||||||
|
|
||||||
|
| Status | Beschreibung |
|
||||||
|
|--------|-------------|
|
||||||
|
| `abwesend` | Benutzer laut AIDA nicht anwesend |
|
||||||
|
| `homeoffice` | Benutzer im Homeoffice |
|
||||||
|
| `teams_available` | Teams: Verfügbar |
|
||||||
|
| `teams_busy` | Teams: Beschäftigt |
|
||||||
|
| `teams_donotdisturb` | Teams: Nicht stören |
|
||||||
|
| `teams_inacall` | Teams: In einem Anruf |
|
||||||
|
| `teams_inameeting` | Teams: In einer Besprechung |
|
||||||
|
| `teams_presenting` | Teams: Präsentiert |
|
||||||
|
| `teams_away` | Teams: Abwesend |
|
||||||
|
| `teams_offline` | Teams: Offline |
|
||||||
|
|
||||||
|
### 6. Dashboard
|
||||||
|
|
||||||
|
Das **Dashboard** zeigt alle Busylights mit dem aktuellen Status in Echtzeit an und aktualisiert sich automatisch alle 10 Sekunden.
|
||||||
|
|
||||||
|
### 7. Protokoll
|
||||||
|
|
||||||
|
Unter **Protokoll** werden die letzten 200 Statusänderungen mit Zeitstempel, WLED-URL und Ergebnis angezeigt.
|
||||||
|
|
||||||
|
## Projektstruktur
|
||||||
|
|
||||||
|
```
|
||||||
|
busylight/
|
||||||
|
├── app.py # FastAPI Web-Anwendung + CLI Auth
|
||||||
|
├── database.py # SQLite Datenbank-Schema und Hilfsfunktionen
|
||||||
|
├── graph_client.py # Microsoft Graph API Client
|
||||||
|
├── wled_client.py # WLED HTTP API Client
|
||||||
|
├── scheduler.py # Hintergrund-Polling (AIDA + Teams → WLED)
|
||||||
|
├── migrate.py # Import aus alter config.cfg
|
||||||
|
├── requirements.txt # Python-Abhängigkeiten
|
||||||
|
├── busylight.service # systemd Service-Datei
|
||||||
|
├── static/
|
||||||
|
│ └── style.css # CSS Styles
|
||||||
|
└── templates/
|
||||||
|
├── base.html # Basis-Layout mit Sidebar
|
||||||
|
├── dashboard.html # Status-Übersicht
|
||||||
|
├── users.html # Benutzer-Verwaltung
|
||||||
|
├── devices.html # WLED-Geräte-Verwaltung
|
||||||
|
├── assignments.html # Zuordnungen User → Segment
|
||||||
|
├── colors.html # Farb-Regeln
|
||||||
|
├── settings.html # Einstellungen
|
||||||
|
└── log.html # Aktivitäts-Protokoll
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ports und Firewall
|
||||||
|
|
||||||
|
| Port | Richtung | Zweck |
|
||||||
|
|------|----------|-------|
|
||||||
|
| 8080/tcp | Eingehend | Web-Oberfläche |
|
||||||
|
| 80/tcp | Ausgehend | WLED HTTP API |
|
||||||
|
| 443/tcp | Ausgehend | Microsoft Graph API |
|
||||||
Loading…
x
Reference in New Issue
Block a user