Add README.md

This commit is contained in:
klux2@hs-mittweida.de 2020-02-04 16:03:52 +01:00
parent ae10cdae12
commit c74b819bff

83
README.md Normal file
View file

@ -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 <Bot.py>` 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.