wiki.ziemers.de

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
=====Abschlussbericht zum Masterprojekt SS 2020=====

==== Inhalt ====
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Inhalt|Inhalt]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Abstract|Abstract]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Uebersicht|Uebersicht / Inbetriebnahme]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Deconcentrator-JS|Deconcentrator-JS]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Database|Database]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Database Microservice|Database Microservice]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#RASA Trainieren|RASA Trainieren]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Cache|Cache]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Update Wetter Microservice|Update Wetter Microservice]]
  - [[[[wiki:software:beuthbot:berichte:ss2020:abschluss#Geoservice Erweiterung des Wetter Microservices|Geoservice Erweiterung des Wetter Microservices]]

==== Abstract ====

==== Uebersicht ====
Die folgende Liste zeigt die Erweiterungen, welche in diesem Semester umgesetzt wurden.
  * BeuthBot Master Repository erstellt um die Organisation des Projektes zu vereinfachen.
  * Dokumentation des Master Repository, Erweiterung der bestehenden Dokumentation.
  * Ersetzen des Deconcentrators durch Deconcentrator-JS.
  * Einbauen einer Persistenz:
    * Realisierung eines passenden Models für die Persistierung der Daten. 
    * Implementierung des Database-Controllers welcher eine MongoDB nutzt um die User Daten zu speichern.
    * Implementierung des Database-Microservice welcher Datenbank-Anfragen auflöst und sie durchsetzt.
  * Einbau Cache in Registry.
  * Umbau / Verbesserung des Weather-Microservice:
    * Formatierung der Antworten
    * Refactoring des bestehenden Codes
    * Einbau von zeitbezogenen Daten
    * Einbau von ortsbezogenen Daten

==== BeuthBot Master Repository ====

Wie dem Zwischenbericht entnommen werden kann, hatten wir am Anfang ziemliche Schwierigkeiten das gesamte Projekt in Betrieb zu nehmen. Jedes Repository musste einzeln gecloned werden und danach jede Komponente einzeln gestartet werden. Aus dieser Not haben wir ein Master-Repository erstellt, welches die einzelnen Module als Git-Submodules beinhaltet. So ist es nun möglich mit einem einzigen Befehl das gesamte Projekt zu laden. Das Projekt kann unter dem Link https://github.com/beuthbot/beuthbot angeschaut werden.

=== Inbetriebnahme ===

<code>
# clone project
$ git clone --recursive https://github.com/beuthbot/beuthbot.git

# or with ssh
$ git clone --recursive git@github.com:beuthbot/beuthbot.git

# change into directory
$ cd beuthbot

# edit environment file
$ cp .env.sample .env && vim .env

# create docker network
$ docker network create beuthbot_network

# start BeuthBot
$ docker-compose up -d

# check whether the gateway is running on port 3000
$ curl http://localhost:3000          # prints: Hello from BeuthBot Gateway
</code>

=== Komponenten des BeuthBot ===

<uml>
@startuml
actor "User" as U
rectangle "telgram-bot" as TGB
package "BeuthBot" {
  rectangle "gateway" as GW
  rectangle "registry" as RE
  database "cache" as CA
  package "NLU" {
    rectangle "deconcentrator-js" as DC
    rectangle "rasa" as RA
  }
  package "Services" {
    rectangle "weather" as WS
    rectangle "mensa" as MS
    rectangle "database" as DBMS
  }
  package "Database" {
    rectangle "database-controller" as DBC
    database "mongo-db" as MDB
  }
}

U -down-> TGB

GW -left-> TGB
TGB -right-> GW

GW -left-> DC
DC -right-> GW

GW -down-> RE
RE -up-> GW

DC -right-> RA
RA -left-> DC

DBC -right-> MDB
MDB -left-> DBC

GW -left-> DBC
DBC -right-> GW

RE -left-> CA
CA -right-> RE

RE -up-> MS
MS -down-> RE

RE -up-> WS
WS -down-> RE

RE -up-> DBMS
DBMS -down-> RE

DBMS -down-> DBC
DBC -up-> DBMS
@enduml
</uml>

==== Deconcentrator-JS ====

Der [[https://github.com/beuthbot/deconcentrator-js|Deconcentrator-JS]] übernimmt die gleiche Aufgabe wie der [[https://github.com/beuthbot/deconcentrator|Deconcentrator]] und ersetzt diesen. Die Entscheidung den Deconcentrator auszutauschen kam daher, dass es uns am Anfang des Semester nicht möglich war, den Deconcentrator aus dem vorherigen Semester in Betrieb zu nehmen. Auch nach langer Beschäftigung und der Hilfe eines Studenten aus dem letzten Semester blieben Erfolge aus. Da dieses Projekt noch weiter entwickelt werden und somit ein einfacher Einstieg und eine überschaubare Komplexität gewährleistet werden soll, erschien es uns also sinnvoll den Deconcentrator durch den neuen Deconcentrator-JS auszutauschen. Ein weiterer Faktor bestand darin, dass der alte Deconcentrator in Python geschrieben war. Eine Vorgabe des Projekts ist aber die Verwendung der Programmiersprache JavaScript. Mehr Informationen über den Deconcentrator-JS befinden sich [[[[wiki:software:beuthbot:deconcentrator-js|hier im Wiki]]. Das Projekt kann unter dem Link https://github.com/beuthbot/deconcentrator-js angeschaut werden.
==== Database ====
{{page>:wiki:software:beuthbot:database}}

==== Database Microservice ====
{{page>:wiki:software:beuthbot:database-microservice}}
==== RASA Trainieren ====

Neue Funktionen oder Microservices müssen dem BeuthBot "beigebracht" werden. Konkret für Rasa heißt das, dass es neue Trainings-Daten braucht aus denen das Model generiert werden kann. Dieses Model nutzt Rasa zur Laufzeit um Anfragen zu interpretieren. Am Anfang des Semesters haben wir bereits ein funktionierendes Model und die dazugehörigen Trainings-Daten vorgefunden. Die Trainings-Daten wurde mit Hilfe von [[https://github.com/YuukanOO/tracy|Tracy]] generiert. Tracy wird mit einem Web-Interface bedient. Man kann dort Sätze und Entities eingeben aus denen sich Trainings-Daten generieren lassen welche dann exportiert werden können. Die Daten wurden damals manuell eingegeben. Als wir das Model erweitern wollten, hätten wir diese Daten wieder manuell eingeben und ergänzen müssen. Da dies nicht praktikabel erschien haben wir nach alternativen Lösungen gesucht und eine gefunden. [[https://github.com/rodrigopivi/Chatito|Chatito]] ist ein Tool mit dem wie bei Tracy Trainings-Daten generiert werden können. Der Unterschied ist das bei Chatito die Daten nicht manuell über ein Web-Interface eingeben werden, sondern mit einer DSL (Domain Specific Language) in *.chatito-Dateien definiert werden. Chatito generiert dann aus einer beliebigen Anzahl gegebener .chatito-Dateien die Trainings-Daten welche dann von Rasa genutzt werden können um das Model zu erstellen. Die Chatito Dateien liegen im Rasa Projekt im Ordner /training/app/input.

Eine Anleitung zum Trainieren eines neuen Models [[[[wiki:software:beuthbot:rasa:training|ist hier in diesem Wiki]]. Die gleiche Anleitung und mehr Informationen befinden sich in der [[https://github.com/beuthbot/rasa/blob/master/.documentation/TRAINING.md|TRAINING.md]] Datei des Rasa Projektes.
==== Cache ====
{{page>:wiki:software:beuthbot:registry:cache}}

==== Update Wetter Microservice ====

===Beschreibung===

Der Wetterservice ist ein Dienst, welche aktuell über den Telegram Client angesprochen wird. Dabei kann der Service per Chat einfach angesprochen werden ohne das der User im Vorfeld etwas einrichten muss. Dieser Dienst antwortet dabei auf Fragen, welche das Wetter im Allgemeinen, aber auch im Stündlichen betreffen, ebenso wie das vergangene Wetter. Aktuell ist eine Anfrage von bis zu 7 Tage in der Zukunft, sowie 5 Tage in der Vergangenheit möglich. Ab 47 Stunden in der Zukunft kann der Bot nur noch mit dem allgemeinen Wetter antworten, sprich keine stündliche anfrage. 

===Verwendete Technologien===

Node.js( https://nodejs.org/en/ )
Express.js( https://expressjs.com/de )
Axios.js( https://www.npmjs.com/package/axios )
OpenWeatherMap( https://openweathermap.org )

===Open Weather Api===

Open Weather Map ist eine Api, welche einem die Möglichkeit bietet Wettervorhersagen abzurufen. Dabei bietet sie 4 verschiedene Arten von Calls: 
/weather -> Aktuellen Wettervorhersage
/onecall -> Aktuellen Wettervorhersage, bis 7 Tage in die Zukunft
/forecast -> Wettervorhersage bis zu 5 Tage in die Zukunft
/history -> Wettervorhersage bis zu 5 Tage in die Vergangenheit
In dieses Service wurden /onecall und /history verwendet, da /forecast nur 5 Tage in die Zukunft geht und auch nur in 3 Stunden abständen. Ebenso wurde /weather nicht genommen, das nur das aktuelle Wetter zurückgibt, welches in /onecall schon enthalten ist. Um diese Api nutzen zu können muss erst einmal ein Key auf der Seite generiert werden, welcher dann am Ende jeweils als Parameter an die URL angehängt werden muss.

=== Geoservice Erweiterung des Wetter Microservices ===
{{page>:wiki:software:beuthbot:weather-service:geo-service}}

===weather.js===

Hier wird die Request vom Service registry aufgenommen und eine Response erstellt und gesendet. Als erstes wird die Request in message und Ort aufgeteilt. Daraufhin wird der Ort, welcher in der Request mitgesendet wurde in Längen.- und Breitengrad via eines Geoservices umgerechnet und wieder gegeben. Dies muss passieren, da die OpenWeatherMap Api bei einigen Anfragen nicht die Ortschaft selbst, sondern nur die Latitude und longitude nimmt. Ist kein Ort in der Request vorhanden wird standardmäßig Berlin oder der durch die Persistenz abgespeicherte Wohnungsort genommen. Daraufhin wird geprüft, ob die Request eine Uhrzeit enthält, um festzustellen ob eine allgemeine oder eine zeitspezifische Anfrage gestellt wurde. Bevor die Bearbeitung anfängt, wird vorher festgestellt, ob das Angefragte Datum auf dem Rahmen fällt, sprich z.B. zu weit in der Zukunft. Ist alles Regelkonform, wird festgelegt, in welchem Zeitraum das Wetter angefragt wird, welches dann an den richtigen Codeblock weitergeleitet wird. Im Block angekommen wird als erstes immer ein Api Call an OpenWeatherMap über die Datei weatherService mit dem Datum und den Koordinaten getätigt, welches dann in der Variable weather gespeichert wird. Danach werden weather( Response vom api call ), date( Datum ) und city( Stadtname ) an generatedMessage und die jeweilige Methode weitergeleitet, welche dann die fertige Nachricht zurückgibt. Diese wird letztendlich als Response an des User weitergeleitet. 

===weatherService.js===

Diese Datei besitzt zwei Methoden, welche jeweils mit axios einen Api call an OpenWeatherMap machen und diesen zurückgeben. Beide Funktionen benötigen jeweils die Koordinaten des gefragten Bereiches. Die Methode getForecast gibt ein JSON zurück in welchem das aktuelle, das stündliche und das tägliche Wetter befindet, welche dann später in generatedMessage.js wiederverwertet werden. Die Funktion getHistory hingegen benötigt noch die spezifische Zeit als long Wert und gibt ebenfalls ein JSON zurück, allerdings nur mit dem exakt gefragten Moment, sowie ein Objekt mit den Stündlichen vergangenen Wetterdaten. 

===generatedMessage.js===

Diese ist die zuletzt aufgerufene Datei, in welcher drei Methoden existieren, welche den Response Text für Telegram zusammenstellen. Jede Funktion benötigt die Parameter weather( Response vom weatherService.js api call ), date( Datum ) und city( Stadtname ). Es müssen diverse Zeitformate erstellt, bzw. angepasst werden, welche dann in der Response eingefügt werden. Ebenso befindet sich in der Response von OpenWeatherMap ein Icon String, welches dann in folgende Text Icons umgewandelt wird: ☀️, ⛅, ☁️, 🌧️, 🌦️, 🌩️, ❄️, 🌫️. Diese ganzen umgewandelten Daten werden daraufhin in einen fest definierten String integriert und als messageText zurückgegeben. 

===Telegram Weather Request and Response===

==Allgemeine Wetteranfrage==

Dies ist eine Chatanfrage ohne dabei einen spezifischen Ort zu nennen. Wenn keine Ort genannt wird, wird standardmäßig der Sitzt der Beuth Hochschule, also Berlin genommen oder aber der User hat seinen Wohnort gesetzt, dann wird dieser genommen, es seiden die Geo Api kenn diesen nicht.

{{:wiki:software:beuthbot:berichte:ss2020:aktuelles_wetter.png?400|}}

==Mit spezifischer Uhrzeit==

Bei dieser Chatanfrage wurde zusätzlich die Uhrzeit mit angegeben. Wenn es sich um die nächsten 47 Stunden handelt, dann wird dementsprechend ein Response mit der Uhrzeit gesendet. Überschreitet das Datum allerdings 47 Stunde, so wird es wie eine allgemeine Anfrage gehandhabt.

{{:wiki:software:beuthbot:berichte:ss2020:nur_uhrzeit.png?400|}}

==Ort ohne Uhrzeit==

Wir ein Ort, allerdings keine Uhrzeit mit geschickt, so handhabt der Bot die Anfrage wir im ersten Bild, nur das er denn mitgesendeten Ort nimmt, es seiden die Geo Api kennt diesen nicht, dann wir standardmäßig Berlin genommen.

{{:wiki:software:beuthbot:berichte:ss2020:ort_ohne_uhrzeit.png?400|}}

==Ort mit Uhrzeit==

Wird neben der Uhrzeit noch ein Ort gesendet und überschreitet es nicht 47 Stunden in die Zukunft, kann der Bot da Wetter an dem Ort mit der spezifisch mitgesendeten Uhrzeit zurückgeben, vorausgesetzt die Geo Api kennt diesen auch.

{{:wiki:software:beuthbot:berichte:ss2020:ort_mit_uhrzeit.png?400|}}

=== Complete Sequence Diagram ===
<uml>
@startuml
participant registry
box "weather-service internal"
    participant "routes/weather.js"
    participant "services/geoService.js"
    participant "services/weatherService.js"
    participant "services/generateResponse.js"
end box
participant "Nominatim API"
participant "OpenWeatherMap API"

registry -> "routes/weather.js": Initial Request
activate "routes/weather.js"
"routes/weather.js" -> "services/geoService.js": Coordinates Call
activate "services/geoService.js"
"services/geoService.js" -> "Nominatim API": API Lookup
activate "Nominatim API"
return API Response
return Coordinates Result
"routes/weather.js" -> "services/weatherService.js": Weather Call
activate "services/weatherService.js"
"services/weatherService.js" -> "OpenWeatherMap API": API Lookup
activate "OpenWeatherMap API"
return API Response
return Weather Result
"routes/weather.js" -> "services/generateResponse.js": Generate Message Call
activate "services/generateResponse.js"
return Response Message
return Final Response
@enduml
</uml>
wiki.ziemers.de

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Seiten-Werkzeuge
