Fregata

Fregata stellt eine REST API zur Verfügung mit deren Hilfe EINFACH via Webhooks / REST API Mails via SMTP, Instant Messages (an Telegram & Wechat) und Messages an Slack verschickt werden können.

In diesem Wiki-Artikel soll erklärt werden, wie das ganze im Zusammenspiel mit homee funktioniert. Die hier beschriebenen Methoden lassen sich natürlich auch auf andere Smart Home Systeme übertragen, welche Webhooks / REST-APIs unterstützen.

homee unterstützt von Haus aus bisher noch keinen Versand von Mails und bietet auch keine Schnittstellen zu anderen Messaging-Systemen (Push-Nachrichten mal ausgenommen).

Installation

Die API kann manuell installiert werden - siehe Zusatzinfos am Ende dieses Artikels - oder via homeean.

Die manuelle Installation ist nicht im Fokus dieses Artikels, wir konzentrieren uns auf die Installation und Konfiguration im Zusammenspiel mit homeean. Die manuelle Installation ist auf der Webseite der API dokumentiert.

Die Installationsvoraussetzungen für homeean und die eigentliche Installation sind im nachfolgend verlinkten Wiki-Artikel ausführlich beschrieben:

Installation & Nutzung von homeean

Fregata gehört leider zu den homeean Paketen, die nach der Installation nicht komplett konfiguriert sind, Ihr müsst leider noch einige Dinge manuell einstellen und auf jeden Fall vor der ersten Nutzung den Rasperry Pi neu starten, weil sonst vom Installerskript gesetzte und von Fregata benötigte Umgebungsvariablen u.U. noch nicht funktionieren.

Konfiguration

Nach einem Restart des Systems (idealerweise via sudo shutdown -r now) und der erneuten Anmeldung, solltet Ihr zunächst überprüfen ob Fregata ordnungsgemäss läuft.

Mit sudo systemctl status fregata erhaltet Ihr darüber Auskunft. Wenn die Kommandozeilenausgabe des Befehls
 active (running) beinhaltet, dann ist bis dahin alles gut gegangen.

Wenn nicht, dann könnt Ihr im File /var/log/syslog meist Informationen entnehmen, woran es liegen könnte.

tail -f /var/log/syslog zeigt rollierend alle Meldungen des Syslogs an, in der Regel wird das System versuchen Fregata alle 10 Sekunden neu zu starten, im Fehlerfall wird es dort Fehlermeldungen geben, die Ihr für die Fehlereingrenzung oder die Hilfe durch die Community (siehe weiter unten) einsetzen könnt. Die Ausgabe des Logs könnt Ihr übrigens mit Control bzw. STRG + C wieder abbrechen.

Gehen wir nun mal davon aus (was der Regelfall sein sollte), dass alles gut gegangen ist und Fregata ohne Probleme läuft.

Fregata benötigt nun von Euch noch Konfigurationsdaten, welche Ihr in einem Texteditor Eurer Wahl - wir bevorzugen,  empfehlen und beschreiben im Wiki solche Fälle immer mit nano - eingeben könnt.

Fregata ist in der Sprache Go geschrieben, was die entsprechenden Dateien nicht einfacher zu finden macht. Dazu kommt, dass Fregata in einem "versteckten" Verzeichnis, nämlich im Unterverzeichnis .go und dort im weiteren Unterverzeichnis bin des Home-Verzeichnisses des Users pi (/home/pi- in dem Ihr Euch nach der Anmeldung schon befinden solltet) abgelegt ist.

Als kleine Tipps:
Mit ls lassen sich unter Linux-Verzeichnisse auflisten - Ihr solltet Euch angewöhnen den Befehl immer mit der Ergänzung / den Parametern -la aufzurufen, das hat folgende Vorteile:
1. Werde so (durch das -a) auch versteckte Verzeichnisse und Dateien angezeigt, diese starten in der Regel mit einem . (Punkt) und werden von einem normalen ls nicht dargestellt.
2. Wird die Darstellung (durch das -l) so übersichtlicher

Also: In Zukunft ls -la statt nur ein ls benutzen.

Jeder Linux Befehl hat eine sogenannte man-page, welche mit man befehl aufgerufen werden kann, in der der Befehl selbst und alle seine Parameter erschöpfend erläutert werden. Wenn es mal etwas schneller gehen muss reicht u. U. aber auch ein befehl --help, damit wird nur eine Kurzversion  ausgegeben.

 Die Konfigurationsdatei von Fregata findet sich im folgenden Pfad:

/home/pi/.go/bin und der Name lautet fregata.conf

Um diese Datei editieren zu können müssen wir sie mit einem Editor öffnen, gebt dazu den folgenden Befehl ein:

nano /home/pi/.go/bin/fregata.conf

nano ist ein vollwertiger Texteditor für die Kommandozeile, der einfach zu benutzen ist.

Im oberen Bereich des Bildschirms wird der Text (in unserem Fall die Standardkonfiguration von Fregata), im unteren Bereich des Bildschirms werden die möglichen Funktionen dargestellt. Diese Funktionen werden mit der Taste STRG (oder Alternativ Control/CTRL) und dem dort genannten Buchstaben aufgerufen.

Im Editor könnt Ihr Euch mit den Cursortasten bewegen und Texte beliebig ergänzen / ändern. Die Funktionen sind unten kurz erklärt und werden situativ angepasst (z.B. beim Speichern von Dateien).

STRG + X wird den Editor beenden (wenn Ihr Änderungen durchgeführt habt, wird Euch nano warnen und das Speichern anbieten)

STRG + O speichert die Datei

STRG + W lässt Euch die Datei durchsuchen

STRG + G startet die Hilfe, welche Ihr jederzeit wieder mit STRG + X beenden könnt

Macht Euch mit nano vertraut, es ist ein mächtiges Werkzeug.

So wird die Konfigurationsdatei aussehen:

Bildschirmfoto-2018-03-31-um-21.58.10.png

Ihr sehr auf dem Bild, dass standardmässig alle APIs (slack, macos, telegram, wechat, smtp) deaktiviert sind (enabled = false). Um eine API nutzen zu können muss sie zunächst enabled werden, das macht Ihr indem Ihr aus dem jeweiligen enabled = false einfach enabled = true macht.

Achtung: Ändert nichts an den Einrückungen (die einzelnen Konfigurationsparameter einer API sind immer leicht eingerückt) und achtet darauf, dass Ihr die "" erhaltet und nicht überschreibt.

In unserem Beispiel wollen wir konkret die Mail-API freischalten, diese sollte dann hinterher wie folgt aussehen (Änderungen zum Originalfile sind fett hevorgehoben):

[smtp]
  enabled = true
  host = "smtp.providerdomain.tld"
  port = 25
  username = "username@maildomain.tld
  password = "Meist Euer Mailpasswort
  from = "Absendermailadresse@domain.tld"

Die API wurde im Beispiel mit true aktiviert, Euer SMTP-Server, Euer Username und Euer Passwort eingetragen und eine Absenderadresse eingetragen (diese kann, je nach Provider, beliebig sein).

Wenn Ihr diese Daten nicht kennt, dann nutzt die Dokumentationen Eures Mailproviders - meist hilft ein googeln nach: SMTP Server Einstellungen Providername

Wenn Ihr ohnehin schon gerade dabei seid, könnt Ihr auch gleich noch die Einstellungen unter [logging] wie folgt verändern:

[logging]
  file = "/home/pi/fregata.log"
  level = "INFO"

Damit wird ein Logfile unter dem Pfad /home/pi mit dem Namen fregata.log angelegt, in dem alle Aufrufe der API mitgeloggt werden, was die Fehlersuche erleichtern kann.

Speichert nun die Datei mit STRG + O unter demselben Namen (dazu einfach Return drücken) und beendet dann den Editor mit STRG + X

Damit Eure Änderungen wirksam werden, müsst Ihr nun fregata neu starten

sudo systemctl restart fregata

Mit dem folgenden Befehl überprüft Ihr ob Fregata wieder ordnungsgemäss läuft

sudo systemctl status fregata

Wenn das der Fall ist (wie es auf der allgemeinen Wiki Seite zu homeean ausführlich beschrieben ist), dann könnt Ihr beginnen die API mit Webhooks zu nutzen.

Wenn die Installation oder Konfiguration von Fregata nicht erfolgreich war, dann meldet Euch im Support-Thread auf der homee Community mit einer Fehlerbeschreibung.

Beispiele

Jetzt lässt sich aus einem Webhook heraus einfach eine Mail verschicken (siehe Screenshot), ich habe es mit 1&1 (smtp.1und1.de, meiner Mailadresse und meinem Mailpasswort) getestet.

58a168441081cfdf084eaff6e577c0f3b674c8fc.png

Einstellungen im Webhook:
URL: http://[IP-Eures-Raspis]:2017/fregata/v1/smtp
Methode: Post
Content Type: application/json

Body (einfach kopieren, einfügen im Body und anpassen):
{"from": "absenderadresse@domain.de", "to": ["empfaenger@domain.de"], "subject": "Subject der Mail", "body": "Eigentlicher Mailtext"}

Das Vorgehen für Instant Messages ist gleich, die API-Aufrufe sind jedoch leicht unterschiedlich, wie in der Fregata-API Dokumentation (nach Klick auf den Post-Button der jeweiligen API ersichtlich).

Für Slack wäre der API-Aufruf entsprechend per Post an die URL /slack statt /smtp zu senden und das JSON-Objekt müsste dann wie unten zu sehen (und in der API-Dokumentation herauskopierbar) formatiert sein.

Bildschirmfoto-2018-03-29-um-13.21.16.png

 So einfach bringt Ihr homee das Senden von Mails und Instant Messages bei.


Zusatzinfos

Mehr generelle Infos zur API (inkl. der offiziellen Dokumentation) gibt es hier:
https://github.com/xuqingfeng/fregata

Die API-Endpoints sind hier im Detail dokumentiert:
https://xuqingfeng.github.io/fregata/api.html

Thread zur API in der homee Community, wo Ihr weitere Fragen stellen könnt:
https://community.hom.ee/t/homeean-fregata-mail-im-api/10667

Nach der Installation erreichst Du die API via:
http://[IP-Eures-Raspis]:2017/v1/

No Comments
Back to top