Skip to end of metadata
Go to start of metadata

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/

Inhalt

1. Was ist ein LoxBerry-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.

 

2. Aufbau der ZIP-Datei

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.

 

 

3. Rootverzeichnis - Datei: plugin.cfg    PFLICHT


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
 KeyValue
1NAMELegt den Namen des Autors oder der Projektgruppe fest.
2EMAILEmail-Adresse des Autors oder der Projektgruppe

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
 KeyValue
1VERSIONVersion des Plugins. Kann verwendet werden um spezielle Aktionen bei einem Update auszuführen (siehe unten). Wird zudem in der Plugin-Verwatung des LoxBerry angezeigt,
2NAMEKurzer Plugin-Name. Keine Leerzeichen, keine Sonderzeichen, nur Kleinbuchstaben! Dieser Name wird als Dateiname verwendet, wenn z. B. in zentralen Ordnern (Cron, Daemon, siehe unten) Skripte für das Plugin angelegt werden sollen. Dieser Name muss im System einzigartig sein. Wenn festgestellt wird, dass bereits ein Plugin installiert ist, welches den gleichen Namen verwendet, wird bei der Installation automatisch "01", "02" usw. angehängt.
3FOLDERVerzeichnis-Name. Keine Leerzeichen, keine Sonderzeichen, nur Kleinbuchstaben! Dieser Name wird als Name der Unterverzeichnisse erwendet, in die die einzelnen Dateien des Plugins installiert werden. Dieser Name muss im System einzigartig sein. Wenn festgestellt wird, dass bereits ein Plugin installiert ist, welches den gleichen Namen verwendet, wird bei der Installation automatisch "01", "02" usw. angehängt.
4TITLE(Langer) Name des Plugins. Dieser wird in der Plugin-Verwaltung des LoxBerry angezeigt und wird auch in den LoxBerry-Menüs verwendet. Hier können Sonderzeichen, Leerzeichen etc. verwendet werden. Der Name sollte nicht länger als 25 Zeichen sein.

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
 KeyValue
1INTERFACEDie Interface-Version, für die das Plugin entwickelt wurde. Aktuell exisitiert lediglich die Version 1.0 des Plugin-Interface. Bitte diese Option daher nicht ändern.

 

4. Rootverzeichnis - Datei: apt    OPTIONAL


Ü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

 

5. Rootverzeichnis - Datei: preinstall.sh    OPTIONAL

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:

 

Nr.InhaltBash-Variable
1Temporärer Ordner, in den das Plugin-Archiv zur Installation entpackt wurde (/tmp/uploads/$1)$1
2Tatsächlich verwendeter Plugin-Name (siehe Kapitel zur Datei plugin.cfg)$2
3Tatsächlich verwendeter Plugin-Installationsordner (siehe Kapitel zur Datei plugin.cfg)$3

4

Plugin-Version (siehe Kapitel zur Datei plugin.cfg)$4
5LoxBerry Basis-Ordner (normalerweise /opt/loxberry)$5

 

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:

 

Logfile TagsHervorhebung
<OK>Grün
<INFO>Schwarrz/Neutral
<WARNUNG>Rot
<ERROR>Rot
<FAIL>Rot

 

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
#!/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

 

6. Rootverzeichnis - Datei: postinstall.sh    OPTIONAL

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:

 

Nr.InhaltBash-Variable
1Temporärer Ordner, in den das Plugin-Archiv zur Installation entpackt wurde (/tmp/uploads/$1)$1
2Tatsächlich verwendeter Plugin-Name (siehe Kapitel zur Datei plugin.cfg)$2
3Tatsächlich verwendeter Plugin-Installationsordner (siehe Kapitel zur Datei plugin.cfg)$3

4

Plugin-Version (siehe Kapitel zur Datei plugin.cfg)$4
5LoxBerry Basis-Ordner (normalerweise /opt/loxberry)$5

 

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:

 

Logfile TagsHervorhebung
<OK>Grün
<INFO>Schwarrz/Neutral
<WARNUNG>Rot
<ERROR>Rot
<FAIL>Rot

 

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
#!/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

 

7. Rootverzeichnis - Datei: preupgrade.sh    OPTIONAL

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:

 

Nr.InhaltBash-Variable
1Temporärer Ordner, in den das Plugin-Archiv zur Installation entpackt wurde (/tmp/uploads/$1)$1
2Tatsächlich verwendeter Plugin-Name (siehe Kapitel zur Datei plugin.cfg)$2
3Tatsächlich verwendeter Plugin-Installationsordner (siehe Kapitel zur Datei plugin.cfg)$3

4

Plugin-Version (siehe Kapitel zur Datei plugin.cfg)$4
5LoxBerry Basis-Ordner (normalerweise /opt/loxberry)$5

 

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:

 

Logfile TagsHervorhebung
<OK>Grün
<INFO>Schwarrz/Neutral
<WARNUNG>Rot
<ERROR>Rot
<FAIL>Rot

 

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
#!/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

 

8. Rootverzeichnis - Datei: postupgrade.sh    OPTIONAL

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:

 

Nr.InhaltBash-Variable
1Temporärer Ordner, in den das Plugin-Archiv zur Installation entpackt wurde (/tmp/uploads/$1)$1
2Tatsächlich verwendeter Plugin-Name (siehe Kapitel zur Datei plugin.cfg)$2
3Tatsächlich verwendeter Plugin-Installationsordner (siehe Kapitel zur Datei plugin.cfg)$3

4

Plugin-Version (siehe Kapitel zur Datei plugin.cfg)$4
5LoxBerry Basis-Ordner (normalerweise /opt/loxberry)$5

 

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:

 

Logfile TagsHervorhebung
<OK>Grün
<INFO>Schwarrz/Neutral
<WARNUNG>Rot
<ERROR>Rot
<FAIL>Rot

 

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
#!/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

 

8. Unterverzeichnis: config    OPTIONAL

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.

 

9. Unterverzeichnis: cron    OPTIONAL

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:

 

CronjobDateiname
Minütlichcron.1min
Alle 3 Minutencron.3min
Alle 5 Minutencron.5min
Alle 10 Minutencron.10min
Alle 15 Minutencron.15min
Alle 30 Minutencron.30min
Stündlichcron.hourly
Täglichcron.daily
Wöchentlichcron.weekly
Monatlichcron.monthly
Jährlichcron.yearly

 

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. 

 

10. Unterverzeichnis: daemon    OPTIONAL

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.

 

11. Unterverzeichnis: data    OPTIONAL

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).

 

12. Unterverzeichnis: icons    PFLICHT

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.

 

13. Unterverzeichnis: log    OPTIONAL

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

 

14. Unterverzeichnis: templates    OPTIONAL

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

Während diese beiden Dateien eingebunden werden müssen die folgenden Textstrings noch durch passenden Inhalt ersetzt werden:

 

TextstringInhalt
<!--$template_title-->Titel Deiner Seite
<!--$helplink-->URL zur ausführlichen Hilfe, meist dieses Wiki hier
<!--$helptext-->Kurzer Hilfetext, der im rechten Tab/Slide steht

 

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

 

Einbinden der Header- und Footer-Templates
#!/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;

 

15. Unterverzeichnis: webfrontend/html    OPTIONAL

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).

 

16. Unterverzeichnis: webfrontend/cgi   PFLICHT

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.

 

17. Unterverzeichnis: uninstall   OPTIONAL

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.

 

18. Besonderheiten / Hinweise

Konfiguration des LoxBerrys

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.

Miniserver

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

Versenden von Emails

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


14 Comments

  1. Hallo zusammen,

    aus Kapitel 3 habe ich verstanden, dass das Plugin anhand von NAME und EMAIL im System identifizert wird. Was mache ich, wenn eine Person mit einer Email-Adresse mehrere Plugins hat?

    Wäre es nicht hilfreich, wenn es hier einen weiteren Key gäbe, der das Plugin identifizert?

    Grüße

    Matthias

    1. Name des Plugins und eMail ist doch eindeutig, oder übersehe ich was?

      1. Hallo Christian,

        was mache ich denn, wenn eine Person zwei Plugins entwickelt? Sowohl Name als auch Email sind für beide Plugins identisch.Wie unterscheidet das System dann die beiden Plugins?

        Grüße

        Matthias

        1. Aber der Name des Plugins ist doch dann nicht gleich?

          1. Dann ist alles ok. Aus dem Text "Die beiden Variablen NAME und EMAIL werden benutzt um das Plugin im System nach der Installation eindeutig zu identifizieren." habe ich das für mich nicht lesen können.

            Habe jetzt verstanden, dass noch weitere Attribute für die Identifizierung innerhalb des Systems herangezoegen werden und keine Verwechslungsgefahr besteht, wenn jemand mehrere Plugins schreibt. (wink)

            Danke für die Klärung

  2. Brauch eure hilfe fehler beim instalieren von plugin 

    1. Wie bereits im Forum geschrieben, gehen die Plugins nur mit der aktuellen Entwicklungsversion. Bitte noch 1-4 Tage Geduld. Zum Wochenende sollte die neue Version fertig sein.

  3. Bezüglich Update/Neuinstallation:

    Mir war, dass ich hier (oder im Sample) gelesen habe, dass bei einem Update erst das alte Plugin gelöscht wird - gibt es ein Verzeichnis (ich denke an config), das während des Updates nicht gelöscht wird? Das würde die Herumkopiererei beim Update ersparen.

  4. Nein, es werden alle Verzeichnisse gelöscht. Die Herumkopiererei ist ein Kompromiss - stimmt. Aber ich fand es so sauberer, auch weil eventuell die Konfigfiles ja noch an die neue Version angepasst werden müssen. So hat man aus den upgrade-Skripten als Plugin-Entwickler die volle Kontrolle über den Upgrade-Prozess.

  5. Für das dmx plugin benötige ich ein python modul "pyserial".

    Ist es korrekt, dass PIP, das installationsmodul von python, nicht installiert ist? Ist das in einer neueren loxberry version noch vorgesehen? oder muss via packages installiert werden? oder soll das plugin zuerst PIP nachinstallieren und dann das modul via PIP?

    Welche Strategie ist vorgesehen um einen daemon/service am laufen zu halten? Soll/darf man vom plugin her z.B. daemontools installieren? sinnvollerweise würden sich alle plugins an einen gewissen "standard" halten, sonst wird es schnell unübersichtlich...?

  6. und es geht grad weiter mit fragen (wink) :

    pip nachinstalliert, nun mit "pip install pyserial" bzw. "sudo pip install pyserial" versucht das modul nachzuladen. bei beiden varianten kommen permission-bezogene fehler (aber nicht die gleichen).

    was ist speziell mit den loxberry users/permissions für python zu beachten? was wurde gegenüber standard debian/jessie verändert?

    EDIT: Problem gelöst! man muss "pip install <modulname> --user" verwenden, der --user macht den unterschied!

  7. 3 neue challenges / fragen für tips&tricks:

    ich sollte in der "/boot/cmdline.txt" (falls nicht bereits vorhanden) den eintrag "dwc_otg.speed=1 " einfügen. wie bekomm ich das mit der bestehenden plugin strategie hin? einen "fake" daemon, welcher einmal als root die änderung macht und sich danach selbst deinstalliert? hauptsächlich ein permissions problem. hat schon jemand etwas ähnliches gelöst?

    die bestehende daemon strategie enthält keine überwachung/watchdog, korrekt? wenn sich mein "server script" aus irgendwelchen gründen verabschiedet wird es bis zu einem neustart des loxberry nicht nachgeladen... darum möchte ich daemontools verwenden, was sicherstellt, dass das script neu gestartet wird. auch für den fall von geänderten (kommandozeilen)optionen macht ein automatischer neustart die sache einfacher... man muss nur das script beenden und es lädt sich von selbst nach. auch hier wieder: ich kann zwar via das apt file daemontools nachinstallieren, scheitere aber an den permissions um in /etc/service ein verzeichnis bzw. das "run" scriptfile zu erstellen oder anzupassen.

    und zuletzt noch: was ist die einfachste strategie um aus den browser-based settings/cfg file kommandozeilenargumente für den service zu generieren?  

    vielen dank für tips!

    1. Mit Squeezelite hatte ich ähnliche Probleme - bezüglich Rechten schau dir deswegen mal mein daemon im squeezelite Player an. Ich verpasse darin meinen Scripts sudoers-Rechte. Weil das erst im Daemon passiert, ist deswegen auch ein Reboot notwendig.

      Die letzte Frage versteh ich nicht - meinst du das Configfile parsen? Das hab ich in Tipps und Tricks schon mal hinzugefügt (und Michael hat's verbessert!)

      1. danke vielmal christian! (du ganz böser bube, du (wink) (thumbs up) top kommentare auf fb (thumbs up))

        squeezelite werd ich mir in dem fall zwecks reverse engineering anschauen (wink) 

        zur letzten frage:
        naja, config file parsen ist eine mögliche lösung, das bekäme ich hin mit python script/daemon anpassen. das script nimmt aber bereits kommandozeilenparameter und darum war der erste ansatz die optionen im daemon file irgendwie aus den settings herzuleiten / anzupassen.