diff --git a/README.md b/README.md new file mode 100644 index 0000000..8570a5a --- /dev/null +++ b/README.md @@ -0,0 +1,83 @@ +Bei diesem Projekt handelt es sich um einen Telegram-Bot, der täglich (und auf +Anfrage) den Speiseplan der Mensa Mittweida abruft und an registrierte Chats +versendet. Der Bot wurde in Python geschrieben und nutzt die +[Telepot](https://github.com/nickoala/telepot)-Bibliothek zur Kommunikation +mit der Telegram-API. + +## Was kann der Bot +### alle Nutzer +- Registrierung und Entfernen von Chats (`/start` bzw. `/stop`) +- schnelles Abrufen des Plans (`/essen`, ggf. mit *en* oder *de* dahinter) +- Ändern der Sprache (`/settings` (damit kann dieser Befehl automatisch über +die Optionen aufgerufen werden)) +- Anzeige von Informationen/Befehlen (`/help`; gleicher Grund wie oben) +### nur für in der Konfigurationsdatei festgelegte Admins +- Anzeige des aktuellen Status (`/status`) +- einfache Logging-Funktion (`/logging [on/off]`, ohne Parameter für aktuellen Status) + +## Vorraussetzungen +### Hardware +Der Bot sollte möglichst immer aktiv sein. Dafür eignet sich z. B. ein +Raspberry Pi gut. Eine Installation auf einem Cloudcomputer ist vermutlich auch +möglich, allerdings ist der Bot nicht darauf ausgelegt und könnte so evtl. zu +hohen Kosten führen, da er immer aktiv auf Nachrichten lauscht (ich weiß nicht, +wie genau das umgesetzt wurde, vielleicht ist es auch nicht so). Auf einem +"normalen" Rechner läuft der Bot auch, allerdings naatürlich nur, solange auch +der Rechner an ist. + +### Sonstiges +Für einen Bot wird ein Bot-Token benötigt. Dieser kann über den +[BotFather](https://t.me/botfather) angefordert werden. Darüber können auch +Bild, Name (momentan "*HSMensaW*"), Beschreibung (wird im Bot-Chat oben +angezeigt; momentan "*Dieser Bot versendet täglich um 10 Uhr den aktuellen +Mensaplan der Hochschule Mittweida (wenn sie geöffnet hat). Außerdem kann der +aktuelle Plan abgerufen werden. Mit dem Befehl /info werden alle anderen +Befehle angezeigt.*") und Über-Text (wird im "Profil" des Bots angezeigt; +momentan "*Versendet täglich um 10 Uhr den aktuellen Mensaplan der Hochschule +Mittweida.*") angepasst werden. + +## Installation +### Abhängigkeiten +Der Bot läuft mit Python 3. Die benötigten Bibliotheken (*telepot*, *babel* und +*googletrans*) können (normalerweise, evtl. auch ohne die "3"; ggf anpassen) +über folgenden Befehl installiert werden: + + pip3 install telepot babel googletrans + +### Minimalkonfiguration +Der Bot liest beim Start die Konfiguration aus einer Konfigurationsdatei +(*config.json*) ein (und schreibt ggf. eine geänderte Konfiguration dorthin). +Auch beim ersten Start muss diese Datei existieren und mindestens folgenden +Inhalt haben: + + { + "telegram_bot_token": "123456789:ABC-t3l36RaM_t0K3n", + "url": "https://app.hs-mittweida.de/speiseplan/all", + "ids": {}, + "config_ids": [], + "logging_enabled": false + } + +Sinnvollerweise sollte auch mindestens eine Config-ID gesetzt sein +([Chat-ID](https://stackoverflow.com/q/31078710) des Besitzers). Eine echte +Konfigurationsdatei könnte so aussehen: + + { + "telegram_bot_token": "123456789:ABC-t3l36RaM_t0K3n", + "url": "https://app.hs-mittweida.de/speiseplan/all", + "ids": { + "12345678": "GERMAN" + "11235813": "ENGLISH" + "-98765432": "GERMAN_ENGLISH" + }, + "config_ids": [ + 12345678 + ], + "logging_enabled": false + } + +### Start +Der Bot kann über `python3 ` gestartet werden (die aktuelle Version +heißt *HSMensaW_botA.py*). Danach sollte er problemlos laufen. *stdout* und +*stderr* werden jeweils in eine Datei (*out.log* bzw. *err.log*) umgeleitet, +wobei es dort u. U. erst nach dem Beenden des Bots auftaucht. \ No newline at end of file