[Workshop] 02_RSS.pm für Anfänger - Schritt für Schritt erklärt

[betateilchen]

Ausgehend von der ab hier geführten Diskussion

http://forum.fhem.de/index.php/topic,21846.msg159025.html#msg159025

werde ich hier in einer Schritt-für-Schritt-Anleitung erklären, wie man das in fhem vorhandene Modul 02_RSS.pm nutzen kann.

Um diesen Anleitungs-Thread übersichtlich zu halten, bitte ich darum, hier im Thread keine Diskussion zu führen oder Fragen zu stellen.

Für Fragen und Diskussion habe ich diesen Thread eröffnet: Diskussions-Thread zum RSS-Workshop

[betateilchen]

Vorbereitungen für den Workshop:

• Debian Nutzer installieren bitte das Paket msttcorefonts (ich hab keine Ahnung, ob es sowas auch für Fritzbox gibt)
• Legt Euch im Verzeichnis ./FHEM eine leere Datei mit dem Namen "rss.layout" an
• Eventuell brauchen wir im Verlauf des Kurses auch die 99_myUtils.pm - das weiss ich noch nicht genau

Wichtiger Nachtrag:

Das Modul 02_RSS.pm benutzt einige zusätzliche perl Module.
Für Debian Distributionen gelten folgende Paketnamen, die mit "apt-get install" nachinstalliert werden können, was viel schneller geht als über CPAN.

• libgd-graph-perl - zwingend!
• libgd-text-perl - optional, aber dringend empfohlen
• libimage-librsvg-perl - optional, aber dringend empfohlen

In diesem Workshops werden ALLE DREI genannten Module gebraucht!

Im Laufe des Workshops werden wir auch mit dem Modul openweathermap als Datenquelle für die Befüllung des RSS arbeiten.
Dieses Modul benötigt für seine Funktion zumindest das Modul XML::Simple, das man auf Debian im Paket libxml-simple-perl bereitgestellt wird.

[betateilchen]

Die Ausgangsfrage, die zu diesem Workshop führte, war die Frage, wie man eine solche Seite in fhem erstellen kann:

(http://up.picr.de/17966931jv.jpg)

Die Grundlagen dazu werde ich hier erklären.

Grundsätzliche Funktion des Moduls 02_RSS.pm

Das Modul stellt einen "echten" RSS Feed bereit, der als einzigen Inhalt eine JPEG Datei in sich trägt. Dieser RSS kann z.B. von Tablets, WLAN Bilderrahmen usw. angezeigt werden.

Den "echten" RSS brauchen wir hier im Workshop nicht wirklich, wir werden nur das darin enthaltene Image benutzen.

 

[betateilchen]

1. Schritt - Definition des RSS in fhem

Code: [Auswählen]


define myrss RSS jpg 192.168.123.241 ./FHEM/rss.layout


Die IP müsst Ihr natürlich durch die IP Eures fhem Servers ersetzen. Man kann dort auch den Hostnamen des fhem-Servers angeben, wenn dieser Name zuverlässig aufgelöst werden kann. Aber bitte nicht "localhost" oder 127.0.0.1 eintragen, sonst ist der RSS nicht von einem anderen PC aus abrufbar! Der Einfachheit halber verwenden wir hier bei der IP Adresse. (Bitte nicht daran stören, wenn hier im Workshop wechselnde IP Adressen auftauchen, bei Euch sollte das immer die gleiche bleiben.)

Es gibt zwei Ergebnisse:

1. ein neu angelegtes Device:

(http://up.picr.de/18004789tl.png)

2. ein neuer Eintrag in der Navigation links, der RSS heißt:

(http://up.picr.de/17974921cp.png)

Den Eintrag RSS könnt Ihr bereits anklicken, dann kommt eine Seite die ungefähr so aussieht:

(http://up.picr.de/17974953ly.png)

Auf dieser Seite stehen Links zu allen in fhem definierten RSS - im Moment steht da nur einer.

Klickt man diesen Link an, kommt man zu dieser Seite:

(http://up.picr.de/17974954bo.png)

Das ist der "echte" RSS Feed, der von RSS Readern verarbeitet werden kann.

Im dargestellten XML findet sich die URL zum RSS-Image:

Code: [Auswählen]

http://192.168.123.158:8083/fhem/rss/myrss.jpg
Diese Adresse sollte Ihr Euch am besten als Lesezeichen ablegen, die brauchen wir immer wieder, um die Ergebnisse unserer Arbeit anzuschauen.

Ich könnt Euch das Ergebnis auch jetzt schon anschauen, es sollte ein schwarzes Rechteck in der Größe 800x600 Pixel erscheinen. Warum das so ist, erkläre ich Euch nach der nächsten

(http://www.wdrmaus.de/codebase/img/start/maus_hinter_schlitz.png)

[betateilchen]

Erklärungen: Woher kommt das schwarze Rechteck?

Ganz einfach: Es wird standardmäßig ein JPEG in der Größe 800 x 600 Pixel generiert, das die Hintergrundfarbe schwarz hat. Bisher haben wir noch kein anderes Verhalten vorgegeben.

Grundsätzlich läßt sich die Größe über das Attribut size steuern, dort kann man z.B. 1024x768 (Achtung: wirklich mit x!) setzen. Bei meinem 7" Tablet, das eine Auflösung von 800x480 Pixel hat, habe ich die Auflösung zum Beispiel auf 800x442 gesetzt, da die Android-Symbole noch von der Nutzfläche abgezogen werden müssen (bei mir 38px hoch) und ich nicht scrollen wollte.

Die Statusseite auf meinem Tablet sieht deshalb so aus:

(http://up.picr.de/17975274qh.jpg)

Der Hintergrund kann auch ein Bild sein, das wird aber jetzt hier noch nicht erklärt, das ist dann "RSS für Fortgeschrittene", wir bleiben hier bei einem farbigen Hintergrund, im Normalfall schwarz. Ich warte auf die Implemenierung der Möglichkeit, die Hintergrundfarbe per Attribut bestimmen zu können, aber Boris als Modul-Maintainer prüft alle Änderungsvorschläge sorgfältig und das dauert manchmal ein bisschen. Ich hoffe, die Umsetzung kommt noch im Laufe dieses Workshops.

[betateilchen]

2. Schritt - Wir erstellen das erste Layout

Mit einem schwarzen Rechteck kann natürlich niemand was anfangen, deshalb werden wir das jetzt mit Inhalt füllen.
Alles was in dem Image dargestellt werden soll, muss in einer Layout-Datei definiert werden. Diese Layout-Datei habt Ihr (hoffentlich) in der Vorbereitungsphase bereits angelegt.

Die Layout-Datei kann direkt aus dem FHEM Frontend bearbeitet werden. Ihr findet die Datei unter "Edit Files" links in der Navigation

(http://up.picr.de/17975497el.png)

Dort könnt Ihr die Datei nun zum Editieren auswählen und bekommt sowas hier angezeigt:

(http://up.picr.de/17975543fh.png)

In das angezeigte Editorfenster tragt Ihr nun bitte folgendes ein und speichert die Datei dann mit dem "Save rss.layout" Button ab:

(http://up.picr.de/17975562yg.png)

Jetzt kommt etwas ganz wichtiges!

Nach jeder Änderung der Layout-Datei muss der RSS intern neu generiert werden. Das passiert mit folgendem Befehl im Frontend

Code: [Auswählen]

set myrss rereadcfg
Danach könnt Ihr das Ergebnis Eurer Arbeit anhand des schon beschriebenen Lesezeichens (die URL zur Imagedatei) anschauen:

(http://up.picr.de/17975608yz.jpg)

Das ist jetzt optisch noch nicht der Knaller, aber keine Sorge, das ändern wir alles noch.

Erklärung zu dem, was grade passiert ist - nach der nächsten Maus

[betateilchen]

Erklärungen - was ist in Schritt 2 passiert?

Wir haben in der Layout-Datei den ersten Eintrag angelegt, der dem RSS Generator sagt, was gemacht werden soll:

Code: [Auswählen]

text 100 100 "Hallo, ich bin Dein RSS!"
Dröseln wir das mal auf:

text = gibt an, dass wir einen Text ausgeben wollen

100 100 = das sind die x und y Koordinaten, WO wir den Text ausgeben wollen, gezählt wird dabei von oben links (0,0) nach unten rechts (800,600)

"Hallo, ich bin Dein RSS!" = das ist der Text, der ausgegeben werden soll

Technisch gesehen, wird der Text quasi als Bild in die schwarze Fläche "gemalt" (gerendert)

Dieses Verfahren ist für alle darzustellenden Objekte, die ich noch beschreiben werde, gleich.

Die Syntax besteht immer aus den Komponenten

- Objekttyp
- Position
- Inhalt

Der Text im vorliegenden Beispiel wurde statisch vorgegeben. Das macht natürlich für sich ändernde Statusanzeigen nicht viel Sinn. Und deshalb kommt jetzt die gute Nachricht: "Man kann den Text selbstverständlich auch dynamisch erzeugen!"

Ändert doch einfach mal die Zeile in der Layout-Datei in folgendes:

Code: [Auswählen]

text 100 100 { fhem("version fhem.pl") }
Und schaut Euch dann das Ergebnis an. (das rereadcfg nicht vergessen!)


Das soll es für heute gewesen sein. Irgendwann hab ich auch mal Feierabend

Morgen machen wir als Erstes den Text optisch "schöner".

[betateilchen]

mir ist grade noch was wichtiges eingefallen 

Im "Vorbereitungs"-Beitrag hier im Thread habe ich noch die zusätzlichen perl-Module aufgelistet, die von 02_RSS.pm genutzt werden.

http://forum.fhem.de/index.php/topic,22520.msg159292.html#msg159292

[betateilchen]

Schritt 3: Wir machen den Text schön.

Die optische Darstellung eines Textes im RSS wird durch 5 Faktoren maßgeblich beeinflußt:

• Schriftart (font)
• Schriftgröße (Höhe in pixel)
• Schriftfarbe
• Rechtschreibung
• Grammatik

Die Punkte 4 und 5 lassen wir hier aussen vor, dafür ist das allgemeine Schulwesen mit seinem Lehrauftrag zuständig 

Für die Punkte 1-3 haben wir Möglichkeiten in der Layoutdatei.

Die Schriftart wird durch das Schlüsselwort "font" bestimmt. Damit wird der komplette Pfad inklusive Dateinamen zu einer TTF Datei angegeben, die wir verwenden wollen.

Beispiel:

Code: [Auswählen]

font /usr/share/fonts/truetype/msttcorefonts/arial.ttf
Die Schriftgröße wird durch das Schlüsselwort "pt" bestimmt. Damit wird die Höhe der Schriftart angegeben, ähnlich wie man das aus Textverarbeitungsprogrammen kennt.

Beispiel:

Code: [Auswählen]

pt 12
Die Schriftfarbe wird durch das Schlüsselwort "rgb" bestimmt. Damit wird die Farbe im Hexcode (wie z.B. in HTML üblich) angegeben.

Beispiel (für die Farbe weiss):

Code: [Auswählen]

rgb "FFFFFF"

Nun kommen wir zur generellen Verarbeitung der Layoutdatei. Diese Datei wird IMMER von oben nach unten abgearbeitet. Es kann also in einer Datei durchaus mehrere Definitionen der Farben und Schriftgrößen geben (auch der Schriftart, damit sollte man aber sparsam umgehen, viele Schriftarten auf einer Seite erschweren die Lesbarkeit erheblich)

Hierbei gilt eine einfache Regel:

Jede Definition eines Parameters gilt so lange, bis in der Layoutdatei eine neue Definition erfolgt.

Was bedeutet das?

Legt Euch bitte die Layout-Datei mit folgendem Inhalt an:

(http://up.picr.de/17979166sl.png)

und kontrolliert dann das Ergebnis, das so aussehen sollte:

(http://up.picr.de/17979170iq.jpg)

Ich denke, das Beispiel erklärt die oben angegebene Regel von selbst.

Achja - Zeilen in der Layout-Datei, die mit # beginnen, sind Kommentare und werden bei der Verarbeitung ignoriert.

[betateilchen]

Schritt 4: Sonderformen von "text"

Zusätzlich zur Ausgabe eines freigewählten (oder eines irgendwie variabel ermittelten) Textes bietet das RSS Modul einfache Möglichkeiten zur Ausgabe von Datum und Uhrzeit.

Fügt bitte am Ende der Layout-Datei aus Schritt 3 folgende Zeilen ein:

Code: [Auswählen]

# nun geben wir das Datum aus
date 400 100

# und jetzt noch die aktuelle Uhrzeit
time 400 200

Und schaut Euch das Ergebnis an.

(http://up.picr.de/17979725xh.jpg)

Das war einfach, oder? 

[betateilchen]

Erklärung - was ist im letzten Schritt passiert?

Ich denke, das erklärt sich weitgehend selbst. Die Syntax von date und time ist ähnlich der Syntax von Text, es werden einfach die x und y Koordinaten angegeben, der auszugebende Text ergibt sich automatisch durch das Schlüsselwort date bzw. time, das wird vom RSS Modul automatisch verarbeitet.

ABER...

Wenn man sich den Screenshot aus dem vorherigen Beispiel anschaut, kommt man irgendwann auf folgende Frage:

"Worauf beziehen sich eigentlich die Positionsangaben in Bezug auf die Ausrichtung des auszugebenden Objektes?"

Bei Text ist das relativ einfach: Die x-Position bezeichnet die Stelle, von der aus der Text nach rechts ausgegeben wird.
Die y-Position bestimmt eine Schriftlinie, "auf der der Text steht". Das heißt, Unterlängen wie bei g j p q y erscheinen unterhalb dieser Linie
Sowohl der Text "Ich bin ein weisser, 12px hoher Text" als auch das Datum wurden an der y-Position 100 ausgegeben.
Denkt Euch eine Linie, die ebenfalls an der y-Position 100 gezogen ist, dann würde das so aussehen:

(http://up.picr.de/17979799hq.jpg)

Ich denke, anhand des Bildes wird klar, was ich mit Schriftlinie meine. (im Bild ist der Vollständigkeit halber auch noch die Linie für die x-Position eingezeichnet)

Dieses Verständnis ist wichtig, um später mehrere Objekte korrekt aneinander ausrichten zu können.

Selbstverständlich kann man auch das Verhalten der Ausrichtung von Objekten an einer angebenen Position noch definieren, aber das kommt erst viel später. Im Moment bleiben wir erstmal beim Standardverhalten.

[betateilchen]

Übrigens: Ihr braucht Euch die einzelnen Beispiele nicht alle speichern, am Ende des Workshops werdet Ihr eine Layout-Datei haben, in der alle besprochenen Teile enthalten sind.

Schritt 5 - wir zeichnen Linien

Legt Euch bitte eine die Layout-Datei wie folgt an:

Code: [Auswählen]

rgb "FFFFFF"
line 0 300 800 300

rgb "FF0000"
line 400 0 400 600

rgb "00FF00"
line 0.1 0.1 0.9 0.9

rgb "FFFF00"
line 0.9 0.1 0.1 0.9

und betrachtet Euch das Ergebnis:

(http://up.picr.de/17980114vv.jpg)

Erklärungen

Die Syntax des line Befehls ist folgende:

Code: [Auswählen]

line <x1> <y1> <x2> <y2> [<thick>]
<x1><y1> bezeichnet den Startpunkt, <x2><y2> bezeichnet den Endpunkt der Linie, die NICHT nur horizontal oder vertikal sein muss!

Die Angabe der Linienstärke <thick> ist optional. Die Standardlinienstärke ist 1px.

Code: [Auswählen]

rgb "FFFFFF"
line 0 300 800 300
bedeutet also:

"Nimm weisse Farbe und ziehe eine Linie von 0,300 nach 800,300. Das entspricht einer durchgehenden Linie vom linken zum rechten Rand."

Würde man diese erste Linie mit einer Dicke von 5 zeichnen wollen, müsste es so aussehen:

Code: [Auswählen]

rgb "FFFFFF"
line 0 300 800 300 5
Das Ergebnis könnt Ihr euch ja mal selbst basteln.

Der zweite Teil

Code: [Auswählen]

rgb "FF0000"
line 400 0 400 600
dürfte sich damit auch selbst erklären.

Aber kommen wir nun zu den zwei weiteren Linien:

Code: [Auswählen]

rgb "00FF00"
line 0.1 0.1 0.9 0.9

rgb "FFFF00"
line 0.9 0.1 0.1 0.9

Was sind denn das für komische Positionsangaben mit 0.1 und 0.9?

Relativ einfach erklärt:

Alle Positionsangaben >= 1 werden als absolute (Pixel-)Positionen interpretiert, also z.B. 300/500

Alle Positionsangaben < 1 werden als relative Positionen, bezogen auf die Gesamtbreite und Gesamthöhe des Bildes  interpretiert.

Das heißt:

Code: [Auswählen]

line 0.1 0.1 0.9 0.9
wird in unserem Beispiel intern umgerechnet in "line 80 60 720 540" und dann gezeichnet.

Um ein Fadenkreuz in die Mitte des RSS zu zeichnen, könnte man also auch schreiben:

Code: [Auswählen]

line 0.5 0 0.5 600
line 0 0.5 800 0.5
Achtung: Die Angabe von "1" zur Kennzeichnung der vollen Breite bzw. Höhe funktioniert leider nicht mehr, das hat Boris irgendwann aus mir bisher unerfindlichen Gründen wieder ausgebaut (es gab die Möglichkeit früher schonmal)


Es gibt auch noch eine dritte Möglichkeit zur Angabe von Positionsdaten, dazu kommen wir später noch.

[betateilchen]

Schritt 6 - Grafiken in den RSS einbinden

Wir können jetzt schon Text (inkl. Datum und Uhrzeit) schreiben und Linien zeichnen. Was noch fehlt, ist das Einbinden von Grafiken in den RSS.

Auch das ist recht einfach möglich, und es folgt dem bereits bekannten, wenn auch im "Inhalt" erweiterten Syntaxprinzip:

Code: [Auswählen]

img <x> <y> <scale> <type> <srcType> <source>
Legt Euch bitte folgendes Layout an:

Code: [Auswählen]

rgb "FFFFFF"

line 0 0.5 800 0.5
line 0.5 0 0.5 600

img 0.5 0.5 1 png url "http://fhem.de/www/images/default/fhemicon.png"

und bewundert das Ergebnis 

(http://up.picr.de/17983753hm.jpg)

Erklärung - nach der nächsten Maus.

[betateilchen]

Erklärung

Code: [Auswählen]

img 0.5 0.5 1 png url "http://fhem.de/www/images/default/fhemicon.png"
aufgedröselt:

img = Schlüsselwort für den auszuführenden Befehl

0.5 0.5 = x/y Position, im Beispiel also genau die Mitte

1 = Skalierungsfaktor, das heißt, die Grafik wird 1:1 wiedergegeben.

png = Grafikformat der einzufügenden Datei/Daten

url = gibt an, dass die Grafikdatei von einer URL gelesen wird. Alternativ gibt es noch "file" und "data" (das erkläre ich auch noch)

"http://..." = die URL mit der Grafikadresse

Achtung: Die Angabe des Formates (z.B. "png") ist unabhängig von der Angabe des Dateinamens notwendig!

Das weiße Fadenkreuz im Beispiel dient nur zur Verdeutlichung, worauf sich die Positionsangaben bei img standardmäßig beziehen: es geht dabei immer um die linke obere Ecke des Bildes.

[betateilchen]

Noch ein wichtiger Hinweis zum Einbinden von img über url:

Niemals eine url verwenden, die vom gleichen fhem bereitgestellt wird!

Wer das versucht, landet in einer Endlosschleife.