From 4dd952e209d0c12e0e6964b3f41aa13e5bcbca8e Mon Sep 17 00:00:00 2001
From: apoc <apoc@chaospott.de>
Date: Sun, 14 Feb 2021 18:47:29 +0100
Subject: [PATCH] add README

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1a9b702
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# chaospott_mumble
+
+| Script | Beschreibung |
+| --- | --- |
+| chaospott_mumble.py | Ruft die aktuell verbundenen Chaoten per UDP von Mumble Server ab und gibt die Infos als JSON aus. |
+| chaospott_mumble.js | Skript für die [Scriptable App](https://scriptable.app) auf iOS, das die Mumble User und den Raumstatus als Widget darstellt. |
+
+## Mumble Daten
+
+Wie man im Mumble Client sieht, geben Mumble Server die Info wie viele User aktuell verbunden sind raus noch bevor der Client sich verbunden hat. Der Abruf dieser Infos erfolg per UDP, indem der Client 12 Bytes hin, und der Server 24 Byte zurück schickt:
+
+<pre>Ping 12 bytes
+
+00 00 00 00 <---------------------------- 4 bytes zero: request type = ping
+            fc 60 86 45 3d 47 e5 5f <---- 8 bytes ident: used to identify the reponse
+
+
+Pong 24 bytes
+
+00 01 02 11 <---------------------------------------------------------------- 4 bytes: server version (1.2.17)
+            fc 60 86 45 3d 47 e5 5f <---------------------------------------- 8 bytes: ident, used to identify the reponse
+                                    00 00 00 02 <---------------------------- 4 bytes: Currently connected users count (2)
+                                                00 00 00 64 <---------------- 4 bytes: maximum users (100)
+                                                            00 01 19 40 <---- 4 bytes: allowed bandwidth (72.000 bit/s)
+</pre>
+
+Siehe dazu auch im [Mumble Wiki](https://wiki.mumble.info/wiki/Protocol).
+
+Das ist zwar sehr effizient, für die Web-Welt aber ungeeignet, da browserseitiges Javascript kein UDP verschicken kann. Das Python-Skript ruft die Daten ab und gibt sie als JSON aus. 
+
+<pre>{"max_users": 100, "last_update": 1613317741, "bandwidth": 72000, "server_version": "1.3.3", "connected_users": 3}</pre>
+
+Das kann man dann als Cronjob laufen lassen und in eine Datei ausgeben lassen.
+
+<pre><code>*/1 * * * * status=`/home/apoc/bin/chaospott_mumble.py` && [ "$status" ] && echo $status > /var/www/virtual/apoc/html/chaospott_mumble.json</code></pre>
+
+Bei Fehlern gibt das Skript nichts aus, der Cronjob sorgt dafür, dass die bisherigen Daten nicht überschrieben werden. Anhand <code>last_update</code> kann man sehen wie aktuell die Werte sind.
+
+## Scriptable Script
+
+Das Script benötigt die [Scriptable App](https://scriptable.app) für iOS und stellt dort ein Widget für den Homescreen zur Verfügung, das den Raumstatus und die verbundenen User im Mumble anzeigt.
+
+### Installation
+
+1. Die Scriptable App installieren
+2. Das Skript in die App bekommen, entweder
+   - ein neues Skript in der App anlegen und den Code reinpasten
+   - die Datei runterladen und in der Files App im Scriptable Ordner speichern. Wenn iCloud Drive benutzt wird, kann dieser Schritt auch am Mac erledigt werden
+3. Auf dem Homescreen ein neues Scriptable Widget hinzufügen. Aus iOS Sicht stammt dieses Widget von der Scriptable App. Man muss es daher noch so konfigurieren, dass die App unser Skript benutzt.
+4. Long-press auf das Widget und "Edit Widget" auswählen.
+5. Nun kann das chaospott_mumble Skript ausgewählt werden.
+
+Das Widget wertet sowohl die Space-Api als auch den Mumble Server aus. 
+Für die beiden Etage "Aerie" und "Cellar" sind separate Stati vorhanden. Der Zeitpunkt der letzten Statusänderung insgesamt wird darunter in relativer Zeitangabe angegeben.
+Für den Mumble Server werden die verbundenen User angezeigt und die Uhrzeit des letzten erfolgreichen Abrufs dieses Wertes (nicht der letzten Änderung).
+
+Sollten die Werte aus dem Cache geladen werden müssen, weil sie nicht abgerufen werden konnten, ist die Farbe blass.
+
+Ganz unten steht die Uhrzeit des letzten Skriptdurchlaufs. Unter iOS bestimmt das Betriebssystem wann die Widgets laufen. Das ist üblicherweise nicht häufiger als alle 15 Minuten. Bei Bedarf kann das Skript auch in der App gestartet werden und zeigt dort aktuelle Werte an.