From f89b9b4626da25770512119f9df6020c38edafde Mon Sep 17 00:00:00 2001 From: Christian Mueller Date: Fri, 24 Apr 2026 17:14:29 +0200 Subject: [PATCH] docs: detailed Starface module rebuild guide using HttpRequest --- docs/starface-modul-umbau.md | 234 +++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 docs/starface-modul-umbau.md diff --git a/docs/starface-modul-umbau.md b/docs/starface-modul-umbau.md new file mode 100644 index 0000000..973150f --- /dev/null +++ b/docs/starface-modul-umbau.md @@ -0,0 +1,234 @@ +# Starface Modul "Busylight 2" → Umbau auf HTTP-Webhook + +## Übersicht + +Das bestehende Modul "Busylight 2" schreibt Telefonstatus in eine MS SQL Datenbank. +Wir bauen es so um, dass es stattdessen HTTP-Requests an den Busylight-Webhook sendet. + +**Vorher:** Starface → MS SQL DB → altes Python-Script → WLED +**Nachher:** Starface → HTTP-Webhook → Busylight-Server → WLED + +## Was wir ändern + +1. Die Funktion `UpdateDB` durch eine neue Funktion `CallWebhook` ersetzen +2. Die GUI-Variablen vereinfachen (kein DB-Server/User/Passwort mehr) +3. Im switch/case nur noch INCOMING/OUTGOING/CONNECTED → callstart und HANGUP → callend + +## Schritt-für-Schritt Anleitung + +### Schritt 1: Modul im Modulcreator öffnen + +1. Starface Admin → Module → Modulcreator +2. Modul "Busylight 2" öffnen +3. Tab **Development** auswählen + +--- + +### Schritt 2: GUI-Tab anpassen + +1. Tab **GUI** öffnen +2. Folgende Felder **löschen** (werden nicht mehr gebraucht): + - GUI_SERVER + - GUI_PORT + - GUI_USERNAME + - GUI_PASSWORT + - GUI_RINGING (brauchen wir nicht für Webhook) + - GUI_RINGBACK + - GUI_PARKED + - GUI_CONFERENCE_ACTIVE + - GUI_LOGIN_LOGOUT + - GUI_MUSICONHOLD_TEST + - GUI_VOICEMAIL_MAIN + - GUI_VOICEMAIL_LINKED + - GUI_CONSULT + - GUI_CONFERENCE_CONSULT + - GUI_CONFERENCE_INACTIVE + - GUI_CCBS + +3. **Neues Feld hinzufügen:** + - Name: `GUI_WEBHOOK_URL` + - Typ: String + - Standardwert: `http://100.95.224.14:8081` + - Beschreibung: `URL des Busylight Webhook-Servers (ohne / am Ende)` + +4. Die verbleibenden Felder behalten: + - `GUI_INCOMING` = `1` (aktiv) + - `GUI_OUTGOING` = `1` (aktiv) + - `GUI_CONNECTED` = leer (nicht nötig, da INCOMING/OUTGOING schon callstart senden) + - `GUI_HANGUP` = `0` (aktiv, sendet callend) + +--- + +### Schritt 3: Neue Funktion "CallWebhook" erstellen + +1. Tab **Development** → Links unter "Functions" auf **+** klicken +2. Name: `CallWebhook` +3. **Function Settings** → Input-Variablen anlegen: + - `loginId` (Typ: String) – Die Durchwahl des Users + - `action` (Typ: String) – "callstart" oder "callend" + +4. In den **Edit**-Bereich wechseln und folgende Bausteine nacheinander einfügen: + +#### Baustein 1: Append (URL zusammenbauen) + +- Aus **Components** → **String** → **Append** in den Edit-Bereich ziehen +- Konfiguration der Input-Variable "Strings" (mehrere Werte): + - Wert 1: `GUI_WEBHOOK_URL` (By Reference ✓ – auf die Modul-Variable zeigen) + - Wert 2: `/` (By Reference ✗ – fester Text) + - Wert 3: `loginId` (By Reference ✓ – auf die Input-Variable der Funktion zeigen) + - Wert 4: `/` (By Reference ✗ – fester Text) + - Wert 5: `action` (By Reference ✓ – auf die Input-Variable der Funktion zeigen) +- Output: `result` → wird die URL z.B. `http://100.95.224.14:8081/222/callstart` + +#### Baustein 2: CreateHttpUrlWithParams (URL-Objekt erstellen) + +- Aus **Components** → **Net.HTTP** → **CreateHttpUrlWithParams** in den Edit-Bereich ziehen +- Input "url": `result` (By Reference ✓ – Output vom Append) +- Output: `httpUrl` + +#### Baustein 3: HttpRequest (HTTP-Request senden) + +- Aus **Components** → **Net.HTTP** → **HttpRequest** in den Edit-Bereich ziehen +- Input "httpUrl": `httpUrl` (By Reference ✓ – Output von CreateHttpUrlWithParams) +- Input "method": `GET` (By Reference ✗ – fester Text) +- Die anderen Inputs (body, headers etc.) leer lassen + +#### Baustein 4: Log (optional, zum Debuggen) + +- Aus **Components** → **System** → **Log** in den Edit-Bereich ziehen +- Log Level: `INFO` +- Message (mehrere Werte): + - `Busylight Webhook: ` (fester Text) + - `result` (By Reference ✓ – die URL die aufgerufen wurde) + +**Die fertige Funktion sieht so aus:** +``` +CallWebhook(loginId, action): + 1. Append([GUI_WEBHOOK_URL, "/", loginId, "/", action]) → result + 2. CreateHttpUrlWithParams(result) → httpUrl + 3. HttpRequest(httpUrl, "GET") + 4. Log("INFO", ["Busylight Webhook: ", result]) +``` + +--- + +### Schritt 4: Funktion "UpdateDB" löschen + +1. Links unter "Functions" die Funktion **UpdateDB** auswählen +2. **Löschen** (X-Button) + +--- + +### Schritt 5: Call-Funktion anpassen + +In der Funktion **Call** den `switch(_uciCallState)` Block anpassen: + +#### case 'INCOMING' ändern: +- Den alten `UpdateDB(_loginId, GUI_INCOMING)` Aufruf **löschen** +- Stattdessen: **CallWebhook** reinziehen + - `loginId` = `_loginId` (By Reference ✓) + - `action` = `callstart` (By Reference ✗, fester Text) + +#### case 'OUTGOING' ändern: +- Den alten `UpdateDB(_loginId, GUI_OUTGOING)` Aufruf **löschen** +- Stattdessen: **CallWebhook** reinziehen + - `loginId` = `_loginId` (By Reference ✓) + - `action` = `callstart` (By Reference ✗, fester Text) + +#### case 'CONNECTED' ändern: +- Den alten `UpdateDB` Aufruf **löschen** +- Diesen case kann man auch komplett löschen (INCOMING/OUTGOING decken den Start ab) +- ODER: CallWebhook mit `callstart` einsetzen (schadet nicht, ist idempotent) + +#### case 'HANGUP' ändern: +- Den alten `UpdateDB(_loginId, GUI_HANGUP)` Aufruf **löschen** +- Stattdessen: **CallWebhook** reinziehen + - `loginId` = `_loginId` (By Reference ✓) + - `action` = `callend` (By Reference ✗, fester Text) + +#### Alle anderen cases löschen: +- case 'RINGING' → **löschen** (wird nicht gebraucht) +- case 'RINGBACK' → **löschen** +- case 'PARKED' → **löschen** +- case 'CONFERENCE_ACTIVE' → **löschen** +- case 'LOGIN_LOGOUT' → **löschen** +- case 'MUSICONHOLD_TEST' → **löschen** +- case 'VOICEMAIL_MAIN' → **löschen** +- case 'VOICEMAIL_LINKED' → **löschen** +- case 'CONSULT' → **löschen** +- case 'CONFERENCE_CONSULT' → **löschen** +- case 'CONFERENCE_INACTIVE' → **löschen** +- case 'CCBS' → **löschen** + +#### Ergebnis nach Umbau: + +``` +switch(_uciCallState): + case 'INCOMING': + CallWebhook(_loginId, "callstart") + + case 'OUTGOING': + CallWebhook(_loginId, "callstart") + + case 'HANGUP': + CallWebhook(_loginId, "callend") +``` + +--- + +### Schritt 6: if-Bedingungen in den cases vereinfachen + +Im alten Modul steht vor jedem UpdateDB ein `if(!empty(GUI_xxx))`. +Das kann vereinfacht werden zu einem einzigen Check: + +``` +case 'INCOMING': + CallWebhook(_loginId, "callstart") +``` + +Die if-Abfrage ist nicht mehr nötig, da wir keine GUI-Variablen mehr pro Status haben. +Wenn du die if-Abfragen drin lassen willst, ändere sie auf `if(!empty(GUI_WEBHOOK_URL))`. + +--- + +### Schritt 7: Register/Unregister Funktionen + +Die Funktionen **Register** und **Unregister** (links unter Functions) bleiben **unverändert**. +Sie registrieren den Call-Event-Listener beim Aktivieren/Deaktivieren des Moduls. + +--- + +### Schritt 8: Speichern und Testen + +1. **Save** klicken +2. **Apply** klicken +3. Unter **Module** → **Modulinstanzen** die Instanz öffnen +4. `GUI_WEBHOOK_URL` auf `http://100.95.224.14:8081` setzen +5. **Aktivieren** +6. Testanruf machen und im Busylight-Dashboard prüfen ob der Telefon-Badge erscheint + +--- + +## Zusammenfassung der Änderungen + +| Vorher | Nachher | +|--------|---------| +| UpdateDB → MS SQL Server | CallWebhook → HTTP GET | +| GUI_SERVER, GUI_PORT, GUI_USERNAME, GUI_PASSWORT | GUI_WEBHOOK_URL | +| 16 switch-cases | 3 switch-cases (INCOMING, OUTGOING, HANGUP) | +| SQL: `UPDATE [Users] SET [StatusStarface] = ...` | HTTP: `GET /222/callstart` | + +## Fehlerbehebung + +### Webhook kommt nicht an +- Log File im Modulcreator prüfen (Tab "Log File") +- Die URL im Log muss so aussehen: `http://100.95.224.14:8081/222/callstart` +- Vom Starface-Server testen: `curl http://100.95.224.14:8081/222/callstart` + +### Falscher User wird rot +- `_loginId` prüfen - das ist die Starface Login-ID (= Durchwahl) +- Diese muss im Busylight-Portal unter "Benutzer" → "Durchwahl" eingetragen sein + +### Türschild bleibt rot nach Anruf +- HANGUP-Event prüfen - wird `callend` aufgerufen? +- Manuell zurücksetzen: `curl http://100.95.224.14:8081/222/callend`