LoxBerry 0.2.3

Diese Anleitung bezieht sich auf Plugin-Entwicklung für LoxBerry 0.2.3 und ist veraltet und abgekündigt.

Verwende diese Anleitung für die Erstellung eines Plugins.

Der LoxBerry kann über Plugins erweitert werden. Plugins bestehen aus einer Reihe von Dateien in einem Standard-ZIP-Archiv, die bei der Installation an die notwendigen Orte im Dateisystem des LoxBerry kopiert werden. Bei diesen Dateien kann es sich z. B. um PHP- oder CGI-Skriptdateien handeln. Des weiteren kann durch das Plugin Software auf dem LoxBerry nachinstalliert werden.

Der folgende Artikel beschreibt den Aufbau eines Plugin-Archivs und beschreibt, wie ein Plugin für den LoxBerry entwickelt werden kann, sodass es sich in die Struktur des LoxBerry nahtlos einfügt. Um die einzelnen Schritte des Artikels nachvollziehen zu können solltest Du Dir jetzt das sogenannte "Sample Plugin" herunterladen, mit dem Du alle Schritte nachvollziehen kannst:

http://plugins.loxberry.de/plugin/sample-plugin/

Ein LoxBerry-Plugin ist nichts anderes als eine Sammlung von Skripten (PHP, Perl, Python, usw.), HTML- oder auch Binary-Dateien, die unterhalb der Weboberfläche des LoxBerry installiert werden. Ziel bei der Entwicklung des Loxberry war es, die vielen sehr guten Skript-Lösungen für den Raspberry Pi, die durch die Loxone Community mittlerweile entwickelt wurden (also z. B. die Google Kalenderanbindung, der Wunderground-Wetterserver, SONOS-Anbindung usw.) für den unerfahrenen Benutzer zugänglich zu machen. D. h. diese Skripte sollen in Form von Plugins über eine grafische Oberfläche installierbar sein - ohne Linux- oder Kommandozeilenkenntnisse.

Zusätzlich haben Plugins auch die Möglichkeit auf dem System fehlende Softwarepakete aus dem Standard Raspbian Repository nachzuinstallieren. Zudem kann ein Plugin auch einen Daemon beim Systemstart starten sowie Cronjobs installieren.

Die einzelnen Komponenten eines Plugins bzw. einer Skriptlösung werden über die Pluginschnittstelle an definierte Orte im Dateisystem des LoxBerry installiert, also HTML-Dateien ins HTML-Verzeichnis des Webservers, CGI-Skripte ins cgi-bin-Verzeichnis des Webservers usw. Somit sind sie anschließend sofort Einsatzbereit und auch der LoxBerry kann direkt auf diese Dateien zugreifen, z. B. um das Plugin in sein hauptmenü zu integrieren.

Selbstverständlich sind auch Updates einzelner Plugins oder auch die Deinstallation möglich - alles über die Weboberfläche des LoxBerry durch den Benutzer durchführbar.

Wenn Du planst Deine Skriptlösung auch für den LoxBerry zur Verfügung zu stellen, dann schaue Dir am Besten einfach schon einmal existierende Plugins unter http://plugins.loxberry.de an und arbeite anschließend diese Anleitung anhand des sogenannten "Sample-Plugins" durch - das Sample Plugin behandelt alle Möglichkeiten der Pluginschnittstelle, sodass mit Hilfe dieses Beispiel-Plugins sehr gut nachvollziehbar ist, wie das Ganze funktioniert.

Alle Dateien des Plugins können im Root-Verzeichnis des ZIP-Archivs oder in einem Unterverzeichnis mit beliebigen Namen liegen.  Obwohl es mit Leerzeichen oder Sonderzeichen keine Probleme geben sollte, verwende bitte für das Unterverzeichnis nur ASCII-Zeichen ohne Leerzeichen. Es ist nicht möglich mehr als ein Untervezeichnis zu verwenden. Die ZIP-Datei darf nicht verschlüsselt oder Passwort-geschützt sein.

Die Dateien und Verzeichnisse des ZIP-Archivs werden bei der Installation der Reihe nach abgearbeitet. Der Ablauf der Installation ist in der folgenden Abbildung dargestellt. Details zu jedem Schritt bzw. jeder Datei beschreiben die folgenden Kapitel.

Diese Datei ist die zentrale Konfigurationsdatei für das Plugin. Es handelt sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF). Der Dateiaufbau ähnelt dem einer typischen INI-Datei unter Windows: Die Daten sind in Blöcke organisiert, jeder Block wird durch den Blocknamen in eckigen Klammern eingeleitet, jede Option innerhalb eines Blockes wird durch KEY=VALUE gesetzt. Kommentare werden durch eine vorangestellte Raute eingeleitet und bei der Interpretation der Datei ignoriert.

1. Block: AUTHOR

[AUTHOR]
# You can also use a Team/Project Name here and a generic email address 
# like info@..., BUT NEVER CHANGE this information in future updates! It
# will be used to identify your Plugin, handle updates etc. If you change
# this information, LoxBerry could not identify your plugin and handle it as
# a different one - therefore updates will fail.
NAME=Max Mustermann
EMAIL=info@yourdomain.de

Wichtiger Hinweis!

Die beiden Variablen NAME und EMAIL werden benutzt um das Plugin im System nach der Installation eindeutig zu identifizieren. Daher dürfen diese beiden Angaben bei späteren Updates des Plugins nicht geändert werden. Ansonsten würde das Plugin nicht als Update sondern als neues, eigenständiges Plugin vom System behandelt werden und somit parallel zum bereits installierten Plugin installiert werden.

2. Block: PLUGIN

[PLUGIN]
# The version of your plugin - important if you would like to write an
# upgrade script.
VERSION=1.0
 
# Short name and prefered subfolder of your Plugin (do not use blanks - they
# will be filtered - and use lowercase only)! Used for script names in
# daemon or cron (NAME) and as unique installation folder. If these names
# already exist on the installation system, we will add 01, 02, 03 and so
# on. Therefore your script should check THESE TWO VARIABLES for figuring
# out subfolder and scriptnames! You will find this information in
# /data/system/plugindatabase.dat after installation!  BUT NEVER CHANGE this
# information in future updates! It will be used to identify your Plugin,
# handle updates etc. If you change this information, Loxberry could not
# identify your plugin and will handle it as a different one - therefore
# updates will definetely fail.
NAME=sampleplugin_name
FOLDER=sampleplugin_folder
 
# Friendly Long Name of your Plugin - 25 Characters maximum! All others maybe 
# replaced by "...". You can use blanks, uppercase/lowercase etc.
TITLE=Sample Plugin

Wichtiger Hinweis!

Die beiden Variablen NAME und FOLDER werden benutzt um das Plugin im System nach der Installation eindeutig zu identifizieren. Daher dürfen diese beiden Angaben bei späteren Updates des Plugins nicht geändert werden. Ansonsten würde das Plugin nicht als Update sondern als neues, eigenständiges Plugin vom System behandelt werden und somit parallel zum bereits installierten Plugin installiert werden.

3. Block: SYSTEM

[SYSTEM]
# Plugin Interface
# Do not change this if you are not knowing what you are doing!
INTERFACE=1.0

Über diese Datei können vom Plugin fehlende Softwarepakete aus dem Raspbian Repository nachinstalliert werden. Es handelt sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF). Kommentare werden durch eine vorangestellte Raute eingeleitet und bei der Interpretation der Datei ignoriert. Jedes zu installierende Paket muss in einer separaten Zeile eingetragen werden.

Vor Installation der Pakete wird der Befehl  apt-get -q -y update ausgeführt, um die Paketquellen zu aktualisieren. Anschließend wird jede Zeile der Reihe nach an den Befehl apt-get -q -y install weitergeleitet und somit die Pakete installiert.

Wenn vom Plugin keine zusätzlichen Pakete benötigt werden, ist es ratsam die Datei apt zu löschen und nicht im Pluginarchiv zur Verfügung zu stellen. So wird die Installation des Plugins deutlich beschleunigt, da bei Existenz der Datei auf jeden Fall der Befehl zum Aktualisieren der Paketquellen ausgeführt wird (egal, ob anschließend ein Paket installiert werden soll oder nicht). Die Aktualisierung der Paketquellen dauert je nach Internetverbindung mehrere Sekunden bis Minuten, sodass es zu einer deutlichen Verzögerung während der Installation des Plugins kommt.

Beispiel: Datei apt

# These packages will be installed by apt-get -y install PACKAGENAME
# One line per package, use exact packagename as you would do for apt-get.
#
package1
package2
package3

Bei der Datei preinstall.sh handelt es sich um ein Bash-Skript, welches vor der Installation ausgeführt wird. Es handelt sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF), die in der Bash ausgeführt wird. Das Skript wird vor der Installation als Benutzer "loxberry" ausgeführt. Es kann verwendet werden um Dinge für die Installation vorzubereiten oder Kommandos auf dem System auszuführen.

Dem Skript werden auf der Kommandozeile folgende Parameter übergeben, die innerhalb des Bashskripts verwendet werden können:

Alle Ausgaben auf STDOUT und STDERR des Skriptes werden in die Logdatei der Plugininstallation geschrieben. So kann man Statusmeldungen mittels "echo" absetzen. Um die Meldungen im Logfile farblich hervorzuheben kann man die folgenden einleitenden Tags am Zeilenanfang des Logeintrags verwenden:

Das Skript muss mit einem Exit-Status von "0" (Null) enden, ansonsten wird während der Installation eine Fehlermeldung ausgegeben, die Installation aber nicht abgebrochen. Benötigt man das Skript nicht, so  ist es ratsam die Datei zu löschen und nicht im Pluginarchiv zur Verfügung zu stellen, um die Installation nicht unnötig zu verzögern.

Beispiel: Datei preinstall.sh Quelle erweitern

#!/bin/sh
 
# Bash script which is executed by bash *BEFORE* installation is started (but
# *AFTER* preupgrade). Use with caution and remember, that all systems may be
# different! Better to do this in your own Pluginscript if possible.
#
# Exit code must be 0 if executed successfully.
#
# Will be executed as user "loxberry".
#
# We add 5 arguments when executing the script:
# command <TEMPFOLDER> <NAME> <FOLDER> <VERSION> <BASEFOLDER>
#
# For logging, print to STDOUT. You can use the following tags for showing
# different colorized information during plugin installation:
#
# <OK> This was ok!"
# <INFO> This is just for your information."
# <WARNING> This is a warning!"
# <ERROR> This is an error!"
# <FAIL> This is a fail!"
 
# To use important variables from command line use the following code:
ARGV0=$0 # Zero argument is shell command
echo "<INFO> Command is: $ARGV0"
 
ARGV1=$1 # First argument is temp folder during install
echo "<INFO> Temporary folder is: $ARGV1"
 
ARGV2=$2 # Second argument is Plugin-Name for scipts etc.
echo "<INFO> (Short) Name is: $ARGV2"
 
ARGV3=$3 # Third argument is Plugin installation folder
echo "<INFO> Installation folder is: $ARGV3"
 
ARGV4=$4 # Forth argument is Plugin version
echo "<INFO> Plugin Version is: $ARGV4"
 
ARGV5=$5 # Fifth argument is Base folder of LoxBerry
echo "<INFO> Base folder is: $ARGV5"
 
# Exit with Status 0
exit 0

Bei der Datei postinstall.sh handelt es sich um ein Bash-Skript, welches nach der Installation ausgeführt wird. Es handelt sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF), die in der Bash ausgeführt wird. Das Skript wird nach der Installation als Benutzer "loxberry" ausgeführt. Es kann verwendet werden um Dinge im System nach der Installation anzupassen oder Kommandos auf dem System auszuführen.

Dem Skript werden auf der Kommandozeile folgende Parameter übergeben, die innerhalb des Bashskripts verwendet werden können:

Alle Ausgaben auf STDOUT und STDERR des Skriptes werden in die Logdatei der Plugininstallation geschrieben. So kann man Statusmeldungen mittels "echo" absetzen. Um die Meldungen im Logfile farblich hervorzuheben kann man die folgenden einleitenden Tags am Zeilenanfang des Logeintrags verwenden:

Das Skript muss mit einem Exit-Status von "0" (Null) enden, ansonsten wird während der Installation eine Fehlermeldung ausgegeben, die Installation aber nicht abgebrochen. Benötigt man das Skript nicht, so  ist es ratsam die Datei zu löschen und nicht im Pluginarchiv zur Verfügung zu stellen, um die Installation nicht unnötig zu verzögern.

Beispiel: Datei postinstall.sh Quelle erweitern

#!/bin/sh
 
# Bashscript which is executed by bash *AFTER* complete installation is done
# (but *BEFORE* postupgrade). Use with caution and remember, that all systems
# may be different! Better to do this in your own Pluginscript if possible.
#
# Exit code must be 0 if executed successfully.
#
# Will be executed as user "loxberry".
#
# We add 5 arguments when executing the script:
# command <TEMPFOLDER> <NAME> <FOLDER> <VERSION> <BASEFOLDER>
#
# For logging, print to STDOUT. You can use the following tags for showing
# different colorized information during plugin installation:
#
# <OK> This was ok!"
# <INFO> This is just for your information."
# <WARNING> This is a warning!"
# <ERROR> This is an error!"
# <FAIL> This is a fail!"
 
# To use important variables from command line use the following code:
ARGV0=$0 # Zero argument is shell command
echo "<INFO> Command is: $ARGV0"
 
ARGV1=$1 # First argument is temp folder during install
echo "<INFO> Temporary folder is: $ARGV1"
 
ARGV2=$2 # Second argument is Plugin-Name for scipts etc.
echo "<INFO> (Short) Name is: $ARGV2"
 
ARGV3=$3 # Third argument is Plugin installation folder
echo "<INFO> Installation folder is: $ARGV3"
 
ARGV4=$4 # Forth argument is Plugin version
echo "<INFO> Plugin Version is: $ARGV4"
 
ARGV5=$5 # Fifth argument is Base folder of LoxBerry
echo "<INFO> Base folder is: $ARGV5"
 
# Exit with Status 0
exit 0

Bei der Datei preupgrade.sh handelt es sich um ein Bash-Skript, welches im Falle eines Plugin-Updates noch vor der Installation ausgeführt wird. Es wird daher noch vor dem Skript preinstall.sh ausgeführt. Es handelt sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF), die in der Bash ausgeführt wird. Das Skript wird vor der Installation als Benutzer "loxberry" ausgeführt. Es kann verwendet werden um vor einem Update des Moduls zum Beispiel vorhandene Konfigurationsdateien temporär zu sichern (z. B. nach /tmp), um sie dann nach dem update wieder zurückzuspielen.

Dem Skript werden auf der Kommandozeile folgende Parameter übergeben, die innerhalb des Bashskripts verwendet werden können:

Alle Ausgaben auf STDOUT und STDERR des Skriptes werden in die Logdatei der Plugininstallation geschrieben. So kann man Statusmeldungen mittels "echo" absetzen. Um die Meldungen im Logfile farblich hervorzuheben kann man die folgenden einleitenden Tags am Zeilenanfang des Logeintrags verwenden:

Das Skript muss mit einem Exit-Status von "0" (Null) enden, ansonsten wird während der Installation eine Fehlermeldung ausgegeben, die Installation aber nicht abgebrochen. Benötigt man das Skript nicht, so  ist es ratsam die Datei zu löschen und nicht im Pluginarchiv zur Verfügung zu stellen, um die Installation nicht unnötig zu verzögern.

Beispiel: Datei preupgrade.sh Quelle erweitern

#!/bin/sh
 
# Bash script which is executed in case of an update (if this plugin is already
# installed on the system). This script is executed as very first step (*BEFORE*
# preinstall.sh) and can be used e.g. to save existing configfiles to /tmp 
# during installation. Use with caution and remember, that all systems may be
# different!
#
# Exit code must be 0 if executed successfully.
#
# Will be executed as user "loxberry".
#
# We add 5 arguments when executing the script:
# command <TEMPFOLDER> <NAME> <FOLDER> <VERSION> <BASEFOLDER>
#
# For logging, print to STDOUT. You can use the following tags for showing
# different colorized information during plugin installation:
#
# <OK> This was ok!"
# <INFO> This is just for your information."
# <WARNING> This is a warning!"
# <ERROR> This is an error!"
# <FAIL> This is a fail!"
 
# To use important variables from command line use the following code:
ARGV0=$0 # Zero argument is shell command
echo "<INFO> Command is: $ARGV0"
 
ARGV1=$1 # First argument is temp folder during install
echo "<INFO> Temporary folder is: $ARGV1"
 
ARGV2=$2 # Second argument is Plugin-Name for scipts etc.
echo "<INFO> (Short) Name is: $ARGV2"
 
ARGV3=$3 # Third argument is Plugin installation folder
echo "<INFO> Installation folder is: $ARGV3"
 
ARGV4=$4 # Forth argument is Plugin version
echo "<INFO> Plugin Version is: $ARGV4"
 
ARGV5=$5 # Fifth argument is Base folder of LoxBerry
echo "<INFO> Base folder is: $ARGV5"
 
# Exit with Status 0
exit 0

Bei der Datei postupgrade.sh handelt es sich um ein Bash-Skript, welches im Falle eines Plugin-Updates am Ende der Installation ausgeführt wird. Es wird daher noch nach dem Skript postinstall.sh ausgeführt. Es handelt sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF), die in der Bash ausgeführt wird. Das Skript wird nach der Installation als Benutzer "loxberry" ausgeführt. Es kann verwendet werden um zum Beispiel vor dem Update gesicherte Konfigurationsdateien wieder zurückzuspielen.

Dem Skript werden auf der Kommandozeile folgende Parameter übergeben, die innerhalb des Bashskripts verwendet werden können:

Alle Ausgaben auf STDOUT und STDERR des Skriptes werden in die Logdatei der Plugininstallation geschrieben. So kann man Statusmeldungen mittels "echo" absetzen. Um die Meldungen im Logfile farblich hervorzuheben kann man die folgenden einleitenden Tags am Zeilenanfang des Logeintrags verwenden:

Das Skript muss mit einem Exit-Status von "0" (Null) enden, ansonsten wird während der Installation eine Fehlermeldung ausgegeben, die Installation aber nicht abgebrochen. Benötigt man das Skript nicht, so  ist es ratsam die Datei zu löschen und nicht im Pluginarchiv zur Verfügung zu stellen, um die Installation nicht unnötig zu verzögern.

Beispiel: Datei postupgrade.sh Quelle erweitern

#!/bin/sh
 
# Bash script which is executed in case of an update (if this plugin is already
# installed on the system). This script is executed as very last step (*AFTER*
# postinstall) and can be for example used to save back or convert saved
# userfiles from /tmp back to the system. Use with caution and remember, that
# all systems may be different! Better to do this in your own Pluginscript if
# possible.
#
# Exit code must be 0 if executed successfully.
#
# Will be executed as user "loxberry".
#
# We add 5 arguments when executing the script:
# command <TEMPFOLDER> <NAME> <FOLDER> <VERSION> <BASEFOLDER>
#
# For logging, print to STDOUT. You can use the following tags for showing
# different colorized information during plugin installation:
#
# <OK> This was ok!"
# <INFO> This is just for your information."
# <WARNING> This is a warning!"
# <ERROR> This is an error!"
# <FAIL> This is a fail!"
 
# To use important variables from command line use the following code:
ARGV0=$0 # Zero argument is shell command
echo "<INFO> Command is: $ARGV0"
 
ARGV1=$1 # First argument is temp folder during install
echo "<INFO> Temporary folder is: $ARGV1"
 
ARGV2=$2 # Second argument is Plugin-Name for scipts etc.
echo "<INFO> (Short) Name is: $ARGV2"
 
ARGV3=$3 # Third argument is Plugin installation folder
echo "<INFO> Installation folder is: $ARGV3"
 
ARGV4=$4 # Forth argument is Plugin version
echo "<INFO> Plugin Version is: $ARGV4"
 
ARGV5=$5 # Fifth argument is Base folder of LoxBerry
echo "<INFO> Base folder is: $ARGV5"
 
# Exit with Status 0
exit 0

Alle Dateien aus diesem Verzeichnis werden im System unter /opt/loxberry/config/plugins/NAME/ installiert. NAME wird dabei ersetzt durch den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3). In diesem Verzeichnis sollten Konfigurstionsdateien abgelegt werden, die vom Plugin verwendet werden. Benötigt das Plugin keine Konfigurationsdateien so kann dieses Verzeichnis auch leer sein.

Die Dateien aus diesem Verzeichnis werden im System als Cronjob installiert. Es muss sich dabei jeweils um ein Bash-Skript handeln. Es muss sich um ASCII-Dateien im Unix-Dateiformat (Zeilenende: Linefeed, LF) handeln, die in der Bash ausgeführt werden können. Der Name der Datei entscheidet, für welchen Cronjob die Datei installiert wird. Die Cronjobs werden als Benutzer "loxberry" ausgeführt. Folgende Cronjobs stehen zur Verfügung:

Bei der Installation wird das Skript umbenannt in den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3) und im korrekten Unterverzeichnis unter /opt/loxberry/system/cron installiert. 

Hier kann eine Datei mit Namen "daemon" abgelegt werden. Es muss sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF) handeln, die in der Bash ausgeführt werden kann. Diese Datei wird während des Bootvorgangs des LoxBerrys als Init-Skript ausgeführt. Bei der Installation wird die Datei umbenannt in den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3) und im Verzeichnis /opt/loxberry/system/daemons/plugins installiert.

Die Besonderheit: Da dieses Skript während des Bootvorgangs als Init-Skript ausgeführt wird, wird sie mit Root-Rechten ausgeführt. Das Daemon-File stellt somit die einzigste Möglichkeit dar, aus einem Plugin heraus Dinge mit Rootrechten durchzuführen.

Hier können sämtliche Dateien, die das Plugin zusätzlich benötigt, abgelegt werden. Denkbar sind zum Beispiel ASCII oder auch Binary-Dateien. Auch zur Zwischenspeicherung kann dieses Verzeichnis später vom Plugin verwendet werden (Cache-Dateien oder ähnliches). Bei der Installation werden alle Dateien aus diesem Verzeichnis nach /opt/loxberry/data/plugins/NAME installiert. NAME wird dabei ersetzt durch den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3).

Dieses Verzeichnis enthält die Icons im PNG-Format, die im Menü des LoxBerrys verwendet werden. Es müssen Icon-Dateien in folgenden Größen hinterlegt werden: 64x64, 128x128, 256x256 und 512x512. Die Dateien müssen im PNG.Format mit transparentem Hintergrund vorliegen. Die Dateien müssen folgende Namen haben: "icon_64.png", "icon_128.png" usw.

Bitte verwendet Icons im Stil der anderen LoxBerry-Icons, um ein einheitliches Aussehen des Menüs zu erhalten. Passende Icons können hier kostenlos heruntergeladen werden: http://download.loxberry.de/development/icons/

Werden keine Icons durch das Plugin zur Verfügung gestellt, verwendet der LoxBerry Default-Icons.

Hier können Logdateien abgelegt werden, falls das Plugin Daten loggen möchte. Die Dateien aus diesem Unterverzeichnis werden bei der Installation nach /opt/loxberry/log/plugins/NAME kopiert. NAME wird dabei ersetzt durch den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3). Die Dateien werden später automatisch über die Software "logrotate" rotiert und gepackt, sodass das Dateisystem des LoxBerry nicht voll gefahren werden kann.

Zur Anzeige von Logdateien bringt der LoxBerry einen Logviewer mit, der für solche Zwecke verwendet werden sollte: http://IP_LOXBERRY/admin/system/tools/logfile.cgi

Dein Plugin sollte Template-Dateien verwenden, um seine Konfiguration im LoxBerry-Menü darzustellen. Bitte stelle wenn möglich mindestens Templates in deutscher und englischer Sprache zur Verfügung. Die Dateien aus diesem Unterverzeichnis werden bei der Installation nach /opt/logberry/templates/plugins/NAME kopiert. NAME wird dabei ersetzt durch den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3).

Um das Look & Feel des LoxBerrys zu erhalten und Dein Plugin im Stil des LoxBerry-Systems darzustellen, solltest Du zunächst das Header-Template des LoxBerrys in Deiner Webseite einbinden, dann Deinen Imhalt einfügen und anschließend das Footer-Template des LoxBerrys anhängen. Die Dateien findest Du hier:

/opt/loxberry/templates/system/SPRACHE/header.html

/opt/loxberry/templates/system/SPRACHE/header.html

Unter Perl könnte das Einbinden der Template-Dateien z. B. so aussehen:

Einbinden der Header- und Footer-Templates Quelle erweitern

#!/usr/bin/perl
use warnings;
use strict;
no strict "refs"; # we need it for template system
 
my $home = File::HomeDir->my_home;
my $lang;
my $installfolder;
my $cfg;
our $helptext;
our $template_title;
 
# Read Settings
$cfg = new Config::Simple("$home/config/system/general.cfg");
$installfolder = $cfg->param("BASE.INSTALLFOLDER");
$lang = $cfg->param("BASE.LANG");
# Title
$template_title = "Sample Plugin";
 
# Create help page
$helptext = "This is a sample short help text showed up in the right slider.";
$helptext = $helptext . "<br><br>HTML markup is <b>supported</b>.";
$helptext = $helptext . "<br><br>Maybe better to load this from a template file...";
 
print "Content-Type: text/html\n\n";
 
# Load header and replace HTML Markup <!--$VARNAME--> with perl variable $VARNAME
open(F,"$installfolder/templates/system/$lang/header.html") || die "Missing template system/$lang/header.html";
while (<F>) {
$_ =~ s/<!--\$(.*?)-->/${$1}/g;
print $_;
}
close(F);
 
# My content
print "<center>";
print "<br><br>This is the Sample Plugin. It just do nothing.<br><br><br>";
print "Goodbye.";
print "</center>";
 
# Load footer and replace HTML Markup <!--$VARNAME--> with perl variable $VARNAME
open(F,"$installfolder/templates/system/$lang/footer.html") || die "Missing template system/$lang/header.html";
while (<F>) {
$_ =~ s/<!--\$(.*?)-->/${$1}/g;
print $_;
}
close(F);
 
exit;

Dieses Verzeicnis enthält Dateien, die per Webserver ausgeliefert werden sollen (vergleichbar mit /var/www). Hier sollten alle statischen Dateien wie z. B. Javascript-Dateien, Bilder etc. abgelegt werden. Die Dateien werden bei der Installation ins Verzeichnis /opt/loxberry/webfrontend/html/plugins/NAME kopiert. NAME wird dabei ersetzt durch den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3).

Dieses Verzeichnis enthält CGI-Dateien (meist Perl), die per Webserver ausgeführt werden sollen (vergleichbar mit /usr/lib/cgi-bin). Die Dateien werden bei der Installation ins Verzeichnis /opt/loxberry/webfrontend/cgi/plugins/NAME kopiert. NAME wird dabei ersetzt durch den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3).

Es muss mindestens die Datei index.cgi exisiteren. Diese wird aus dem Hauptmenü des LoxBerrys verlinkt.

Hier kann eine Datei mit Namen "uninstall" abgelegt werden. Es muss sich um eine ASCII-Datei im Unix-Dateiformat (Zeilenende: Linefeed, LF) handeln, die in der Bash ausgeführt werden kann. Diese Datei wird während des Bootvorgangs des LoxBerrys als Init-Skript ausgeführt. Bei der Installation wird die Datei umbenannt in den Pluginnamen aus plugin.cfg (vergleiche Kapitel 3) und im Verzeichnis /opt/loxberry/data/system/uninstall zwischengespeichert. Während der DEinstallation des Plugins wird die Datei nach /opt/loxberry/system/daemon/uninstall verschoben und hier beim nächsten Reboot ausgeführt. 

Die Besonderheit: Da dieses Skript während des Bootvorgangs als Init-Skript ausgeführt wird, wird es mit Root-Rechten ausgeführt. Somit können bei der Deinstallation noch Dinge im System des LoxBerrys mit Rootrechten aufgeräumt werden, sofern das Plugin außerhalb der Standardverzeichnisse des LoxBerrys Dinge verändert oder abgelegt hat.

Alle während der Einrichtung des LoxBerrys gemachten Angaben findest Du in der ASCII-Datei /opt/loxberry/config/general.cfg. Die Datei sollte selbsterklärend sein. Der Dateiaufbau ähnelt dem einer typischen INI-Datei unter Windows: Die Daten sind in Blöcke organisiert, jeder Block wird durch den Blocknamen in eckigen Klammern eingeleitet, jede Option innerhalb eines Blockes wird durch KEY=VALUE gesetzt. Kommentare werden durch eine vorangestellte Raute eingeleitet.

Bei der Einrichtung des LoxBerrys können mehrere Miniserver eingerichtet werden. Dein Plugin sollte das berücksichtigen. Details zu allen eingerichteten miniservern findest Du in der zentralen Konfigurationsdatei /opt/loxberry/config/system/general.cfg

Zudem können Miniserver entweder über die lokale IP-Adresse oder den lokalen Hostnamen als auch über den CloudDNS-Service von Loxone eingebunden werden. Auch diesen Umstand sollte Dein Plugin berücksichtigen. Wir haben ein Hilfstool erstellt, mit dem man über die MAC-Adresse des Miniservers, die Du ebenfalls in der Datei /opt/loxberry/config/general.cfg findest, die korrekte IP-Adresse samt Port anfragen kannst:

/opt/loxberry/bin/showclouddns.pl

oder

 /opt/loxberry//webfrontend/cgi/system/tools/showclouddns.cgi

Soll Dein Plugin Emails versenden, so kannst Du diese einfach über sendmail verschicken: /usr/sbin/sendmail Voraussetzung ist, dass der User einen Mailserver für ausgehende Emails eingerichtet hat.

Die komplette Konfiguration des Mailservers findest Du in der Konfigurationsdatei /opt/loxberry/config/system/mail.cfg