Plugin-Metadata update

Plugins werden in etc/plugin.yaml konfiguriert. Die Parameter sind in der plugin.yaml des jeweiligen Plugins beschrieben.

Ein Plugin besteht aus mindestens zwei Dateien:

dem Programmcode: __init__.py
den Metadaten: plugin.yaml

Hinweis

Das in früheren Versionen verwendete README-Format für die Dokumentation von Plugins ist veraltet. Ein Großteil der Dokumentation ist in die Metadaten-Dokumentation in plugin.yaml übergegangen. Die restliche Dokumentation sollte nur noch im user_doc-Format erfolgen.

Soweit möglich, sollten bestehende README im Rahmen von Aktualisierungen in entsprechende user_doc überführt werden.

Diese Dateien befinden sich in einem Unterordner des /plugins-Ordners. Der Name des Unterordners entspricht dem Namen des Plugins.

Die Metadaten-Datei heißt /plugins/<Name des Plugins>/plugin.yaml. Sie besteht aus sechs Abschnitten:

plugin: - Globale Metadaten des Plugins Die Daten dieses Abschnitts werden verwendet, um die Kompatibilität des Plugins mit der laufenden Version von SmartHomeNG zu prüfen und definieren, wie das Plugin geladen wird

Die Angaben unter description: werden genutzt, um die Plugin-Seite in der SmartHomeNG-Dokumentation zu erzeugen. Standardmäßig wird die deutsche Sprachversion verwendet, wenn diese nicht vorhanden ist, wird die englische genutzt.
parameters: - Parameter, mit denen das Plugin in /etc/plugin.yaml konfiguriert wird. Die Daten dieses Abschnitts werden verwendet, um die Gültigkeit der Plugin-Konfiguration zu prüfen.
item_attributes - Item-Attribute, die durch das Plugin definiert werden Die Daten dieses Abschnitts werden verwendet, um die Attribute der Item-Konfiguration auf Gültigkeit zu prüfen.
item_structs: - Item-Strukturen, die vorgefertigte Item-Pakete des Plugins bereitstellen
logic_parameters: - Logik-Parameter, die in /etc/logic.yaml zur Konfiguration von Logiken genutzt werden
plugin_functions: - Funktionsaufrufe, die das Plugin bereitstellt

Die Metadaten werden weiterhin vorgesehen

für die automatisierte Erstellung der SmartHomeNG-Dokumentation

für die Nutzung in einer grafischen Konfigurationsoberfläche

Note:

Wenn die Implementation der Metadaten-Systematik abgeschlossen ist, werden die folgenden Variablen im Python code von SmartPlugins nicht mehr benötigt. Sie werden aus den globalen Metadaten ausgelesen und im Plugin automatisch bereitgestellt:

ALLOW_MULTIINSTANCE
PLUGIN_VERSION

Es wird empfohlen, die Variable PLUGIN_VERSION trotzdem zu setzen. Dann kann durch den Vergleich der Angaben in __init__.py und plugin.yaml sichergestellt werden, dass die Dateiversionen zueinander passen. Wenn das nicht der Fall ist, wird ein Fehler ausgegeben und das Laden des Plugins verhindert.

Hinweis

Zum Validieren der Metadaten in plugin.yaml kann das Tool /tools/plugin_metadata_checker.py genutzt werden. Dies prüft die Metadaten auf Vollständigkeit und Fehlerfreiheit.

Note:: Bei Modulen heißt der Abschnitt entsprechend module: statt plugin:

Detaillierte Beschreibung

Die einzelnen Abschnitte sind im Folgenden detailliert beschrieben:

plugin

Der globale Metadaten Abschnitt plugin: kennt die folgenden Schlüsselbegriffe:

# Metadata for the Smart-plugin
plugin:
    # Global plugin attributes
    type: web                   # plugin type (gateway, interface, protocol, system, cloud, un-classified)
    description:
        de: 'Plugin für ...'
        en: 'Plugin for ...'
    maintainer: msinn           # Optional: Who maintains this plugin?
#   tester:                     # Optional: Who tests this plugin?
    state: qa-passed
    keywords: weather           # keywords, where applicable
    documentation: 'https://...'        # An url to optional plugin doc - NOT the url to user_doc!!!
#    support: https://knx-user-forum.de/forum/supportforen/smarthome-py      # url of the support thread or forum

    version: 1.4.3
    sh_minversion: 1.7           # minimum shNG version to use this plugin (leave empty if no special requirement)
#    sh_maxversion:              # maximum shNG version to use this plugin (leave empty if latest)
#    py_minversion: 3.6          # minimum Python version needed for this plugin (leave empty if no special requirement)
#    py_maxversion:              # maximum Python version to use this plugin (leave empty if no special requirement)
    multi_instance: true        # plugin supports multi instance (if not specified, False is assumed)
    restartebly: unknown
#    startorder: normal          # should only be set on special plugins
    configuration_needed: true  # False: The plugin will be enabled by the Admin GUI without configuration

    classname: <plugin_class>   # Name of the class that implements the plugin

Beschreibung der Schlüsselbegriffe im Abschnitt plugin:

type: Beschreibt den Typ des Plugins (gültige Werte: gateway, interface, protocol, system, web oder leer für ein nicht klassifiziertes Plugin.

Die Typen sind wie folgt definiert:

keine Anbindung von Geräten/Diensten: System-Plugin

Ansteuerung eines Gerätes je Plugin-Instanz: Interface-Plugin

Ansteuerung mehrerer Geräte je Plugin-Instanz: Gateway-Plugin

reine Unterstützung von Übertragungsprotokollen: Protokoll-Plugin

Anbindung von Internet-Diensten: Web-Plugin

description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional.

maintainer: Hier kann angegeben werden, wer das Plugin pflegt und weiterentwickelt

tester: Optional können hier die Nutzer angegeben werden, die sich bereit erklärt haben das Plugin zu testen

state: Entwicklungs-Status des Plugins (gültige Werte: develop, ready, qa-passed)

keywords: Liste der Schlüsselwörter die das Plugin beschreiben (durch Leerzeichen getrennt)

documentation: url die auf eine weiterführende Dokumentation verweist (damit sind nicht die Dateien user_doc.rst oder die veraltete README.md gemeint)

support: url die auf einen Support Thread oder ein Support Forum verweist

version: VersionsNumber des Plugins. Sie wird beim Laden mit der Versionsnummer die im Code definierert ist verglichen.

sh_minversion: Minimale SmartHomeNG Version mit der das Plugin kmpatibel ist. Falls sh_minversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder älteren Version von SmartHomeNG kompatibel ist.

sh_maxversion: Maximale SmartHomeNG Version mit der das Plugin kmpatibel ist. Falls sh_maxversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder neueren Version von SmartHomeNG kompatibel ist.

py_minversion: Minimale Python Version mit der das Plugin kmpatibel ist. Falls py_minversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder älteren Python Version komatibel ist die von SmartHomeNG unterstützt wird.

py_maxversion: Maximale Python Version mit der das Plugin kmpatibel ist. Falls py_maxversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder neueren Python Version komatibel ist die von SmartHomeNG unterstützt wird.

multi_instance: Ist das Plugin in der Lage in mehreren Instanzen gestartet zu werden? (True, False)

configuration_needed: Normalerweise wird in der Admin GUI ein Plugin im Status disabled hinzugefügt und muss erst konfiguriert werden. Wenn dieser Parameter auf False gesetzt wird, wird das Plugin im Status enabled hinzugefügt. Das ist sinnvoll bei Plugins, die ohne Konfiguration lauffähig sind. (True, False)

restartable: Is the Plugin Restart bzw. Reload fählg? (gültige Werte: True, False, unknown)

startorder Dieser Parameter darf nur bei speziellen Plugins gesetzt werden, die besondere Anforderungen an die Startreihenfolge haben (wie z.B. das database Plugin). Gültige Werte sind early, normal und late. Plugins mit startorder early werden vor den anderen Plugins gestartet (und beim Beenden nach den anderen Plugins beendet)

classname: Name der Python Klasse die das Plugin implementiert un die zum Start des Plugins initialisiert wird.

classpath: Wird normalerweise nicht angegeben - Nur angeben, wenn das Plugin außerhalb des /plugins Verzeichnisses gespeichert ist,

parameters

Parameter-Metadaten werden benutzt um die Gültigkeit von Parametern zu prüfen, die im Verzeichnis ../etc konfiguriert wurden. Falls für einen Parameter ein ungültiger Wert konfiguriert wurde, wird eine Warnung im Logfile von SmartHomeNG eingetragen.

Wenn ein gültiger Wert konfiguriert wurde, wird der Parameter an das Plugin/Modul übergeben, und zwar als der Datentyp, der in den Metadaten definiert wurde.

Der parameters: Abschnitt hat für jeden definierten Parameter einen Unter-Abschnitt, der den Parameter genauer beschreibt. Der Schlüssel des Unter-Abschnitts ist der Name des Parameters. Parameter Namen sollten keine Großbuchstaben und Sonderzeichen enthalten. Sie dürfen nicht mit einer Ziffer beginnen.

Die Definitionen im Abschnitt parameters: werden für die Gültigkeitsprüfung der konfigurierten Werte, sowie zur Dokumentation und zur Konfiguration in der Admin GUI benutzt.

parameters:
    param1:
        type: int
        default: 1234
        description:
            de: 'Deutsche Beschreibung'
            en: 'English description'
        valid_list:
          - 1234
          - 2222
          - 4321

    param2:
        type: ...

Hinweis

Der Parameter webif_pagelength wird jedem Plugin automatisch hinzugefügt und sollte daher NICHT manuell im plugin.yaml File hinterlegt werden.

Beschreibung der Schlüssel im Abschnitt für einen Parameter bzw. ein Attribut:

type: Beschreibt den Datatyp des Parameters bzw. Attributes. Gültige Datentypen sind:
Einfache Datentypen:
bool - ein boolscher Wert

int - ein ganzzahliger Wert

scene - ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiert

float - ein numerischer Wert der Nachkommastellen enthalten darf

num - das Equivalent zum Typ `float

str - ein String`

ip - ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiert

ipv4 - ein String, der eine ipv4-Adresse repräsentiert

ipv6 - ein String, der eine ipv6-Adresse repräsentiert

mac - ein String, der eine MAC Adresse repräsentiert

knx_ga - ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiert

foo - der universelle Datatyp
Komplexe Datentypen:
dict - ein Dictionary

list - eine Liste bei der jedes Element vom Datentyp foo ist

list(len) - eine Liste fester Länge bei der jedes Element vom Datentyp foo ist und deren Anzahl Elemente len ist

list(subtype) - eine Liste bei der jedes Element vom Datentyp subtype ist ¹ (z.B.: list(int) or list(ipv4))

list(subtype, subtype, ...) - eine Liste bei der jedes Element von einem angegebenen Datentyp ist. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

list(len,subtype, subtype, ...) - eine Liste fester Länge bei der bei der für jedes Element ein subtype angegeben wird. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

¹ subtype kann nur ein einfacher Datentyp sein
gui_type: Optional: Spezifiziert genauer, wie der Parameter in der Admin GUI shngadmin behandelt werden soll. Die Handhabung der Parameter in der Admin GUI wird durch den Parameter type bestimmt. type ist jedoch auf die Datentypen beschränkt, die SmartHomeNG kennt. Für das Editieren kann es jedoch wünschenswert sein, unterschiedlche Feld-Editoren für den selben Datentyp zu verwenden.

Bisher werden nur zwei Werte für gui_type unterstützt:
- wide_str wird benutzt, um ein breiteres Editor Feld zu verwenden (z.B. für Strings die einen längeren Inhalt haben können/sollen.
- readonly wird benutzt, wenn der Parameter nicht in der GUI konfiguriert werden soll, z.B. wenn das Webinterface des Plugins diesen Parameter konfiguriert.
default: Optional: Gibt einen Standardwert vor, der verwendet wird, falls bei der Konfiguration des Parameters in ../etc/plugin.yaml bzw. ../etc/module.yaml kein Wert angegeben wird.
description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional
valid_list: Optional: Liste der erlaubten Werte für den Parameter (case sensitive)
valid_list_ci: Optional: Liste der erlaubten Werte für den Parameter (nicht case sensitive) Der Wert wird dem Plugin/Modul in lower case übergeben. Falls valid_list_ci angegeben ist, wird eine evtl spezifizierte valid_list ignoriert.
valid_list_description: Optional: Beschreibung der Werte, die in valid_list: bzw. valid_list_ci: spezifiziert sind. Falls definiert, muss valid_list_description: Sub-Keys haben, um die Beschreibung in mehreren Sprachen (de, en, fr, pl, …) anzugeben.

Jeder Sprach-Sub-Key muss eine Liste sein, die für jeden Eintrag in valid_list eine Beschreibung enthält.
valid_min: Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein minimal Wert angegeben werden
valid_max Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein maximal Wert angegeben werden
mandatory: Optional: Falls auf True gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert für default: definiert ist.

Plugins/Module ohne Parameter

Falls ein Plugin oder Modul keine Parameter hat, wird das durch den folgenden Eintrag in der Datei plugin.yaml angezeigt:

parameters: NONE

Hinweis

Bitte beachten, dass hier NONE vollständig in Großbuchstaben geschrieben werden muss.

item_attributes

Der Abschnitt item_attributes: hat für jedes definierte Item Attribut einen Unter-Abschnitt, der das Attribut genauer beschreibt. Der Schlüssel des Unter-Abschnitts ist der Name des Attributes. Attributnamen sollten keine Großbuchstaben und Sonderzeichen enthalten. Sie dürfen nicht mit einer Ziffer beginnen.

Die Definitionen im Abschnitt item_attributes: werden für die Gültigkeitsprüfung der konfigurierten Werte in den Konfigurationsdateien im Verzeichnis ../items, sowie zur Dokumentation und in der Zukunft zur Konfiguration in der Admin GUI benutzt.

item_attributes:
    attribute1:
        type: int
        default: 1234
        description:
            de: 'Deutsche Beschreibung des Attributes'
            en: 'English description of the attribute'
        valid_list:
          - 1234
          - 2222
          - 4321

    attribute2:
        type: ...

Beschreibung der Schlüssel im Abschnitt für einen Parameter bzw. ein Attribut:

type: Beschreibt den Datatyp des Parameters bzw. Attributes. Gültige Datentypen sind:
Einfache Datentypen:
bool - ein boolscher Wert

int - ein ganzzahliger Wert

scene - ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiert

float - ein numerischer Wert der Nachkommastellen enthalten darf

num - das Equivalent zum Typ `float

str - ein String`

ip - ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiert

ipv4 - ein String, der eine ipv4-Adresse repräsentiert

ipv6 - ein String, der eine ipv6-Adresse repräsentiert

mac - ein String, der eine MAC Adresse repräsentiert

knx_ga - ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiert

foo - der universelle Datatyp
Komplexe Datentypen:
dict - ein Dictionary

list - eine Liste bei der jedes Element vom Datentyp foo ist

list(len) - eine Liste fester Länge bei der jedes Element vom Datentyp foo ist und deren Anzahl Elemente len ist

list(subtype) - eine Liste bei der jedes Element vom Datentyp subtype ist ¹ (z.B.: list(int) or list(ipv4))

list(subtype, subtype, ...) - eine Liste bei der jedes Element von einem angegebenen Datentyp ist. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

list(len,subtype, subtype, ...) - eine Liste fester Länge bei der bei der für jedes Element ein subtype angegeben wird. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

¹ subtype kann nur ein einfacher Datentyp sein
gui_type: Optional: Spezifiziert genauer, wie der Parameter in der Admin GUI shngadmin behandelt werden soll. Die Handhabung der Parameter in der Admin GUI wird durch den Parameter type bestimmt. type ist jedoch auf die Datentypen beschränkt, die SmartHomeNG kennt. Für das Editieren kann es jedoch wünschenswert sein, unterschiedlche Feld-Editoren für den selben Datentyp zu verwenden.

Bisher werden nur zwei Werte für gui_type unterstützt:
- wide_str wird benutzt, um ein breiteres Editor Feld zu verwenden (z.B. für Strings die einen längeren Inhalt haben können/sollen.
- readonly wird benutzt, wenn der Parameter nicht in der GUI konfiguriert werden soll, z.B. wenn das Webinterface des Plugins diesen Parameter konfiguriert.
default: Optional: Gibt einen Standardwert vor, der verwendet wird, falls bei der Konfiguration des Parameters in ../etc/plugin.yaml bzw. ../etc/module.yaml kein Wert angegeben wird.
description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional
valid_list: Optional: Liste der erlaubten Werte für den Parameter (case sensitive)
valid_list_ci: Optional: Liste der erlaubten Werte für den Parameter (nicht case sensitive) Der Wert wird dem Plugin/Modul in lower case übergeben. Falls valid_list_ci angegeben ist, wird eine evtl spezifizierte valid_list ignoriert.
valid_list_description: Optional: Beschreibung der Werte, die in valid_list: bzw. valid_list_ci: spezifiziert sind. Falls definiert, muss valid_list_description: Sub-Keys haben, um die Beschreibung in mehreren Sprachen (de, en, fr, pl, …) anzugeben.

Jeder Sprach-Sub-Key muss eine Liste sein, die für jeden Eintrag in valid_list eine Beschreibung enthält.
valid_min: Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein minimal Wert angegeben werden
valid_max Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein maximal Wert angegeben werden
mandatory: Optional: Falls auf True gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert für default: definiert ist.

duplicate_use: Optional: Falls auf True erfolgt keine Warnung, falls das Item-Attribut in unterschiedlichen Plugins definiert ist. Dazu muss duplicate_use in allen Plugin Definitionen angegeben werden, in denen das Attribut genutzt wird. Außerdem müssen die Definitionen der Item Attribute in den verschiedenen Plugins übereinstimmen.

Plugins ohne Item Attribute

Falls ein Plugin keine Item Attribute hat, wird das durch den folgenden Eintrag in der Datei plugin.yaml angezeigt:

item_attributes: NONE

Hinweis

Bitte beachten, dass hier NONE vollständig in Großbuchstaben geschrieben werden muss.

item_structs

Der Abschnitt item_structs: erlaubt die Definition von Struktur Templates, also von Sub-Trees von Items, die an verschiedenen Stellen in den Item Tree eingefügt werden können.

Definitionen von item_structs: haben das folgende Format:

item_structs:
    struct1:

        item1:
            type: int
        item2:
            item3:
                name: 'my item 3'
                type: str
                plg_attr1: 'plugin specific'
            item4:
                type: bool
                initial_value: True

    struct2:

        ... (sub-tree with item definitions)

Zur Konfiguration von SmartHomeNG werden diese structs durch die Angabe einer Referenz in den Item Tree eingefügt. Das erfolgt in den Konfigurationsdateien für Items im Verzeichnis ../items:

item_name_of_struct:
    struct: <plugin name>.<struct name>

Falls struct1 des oben angegebenen Beispiels in einem Plugin mit dem Namen example_plugin definiert wurde, sieht die Konfiguration um die Struktur einzufügen folgendermaßen aus:

item_name_of_struct:
    struct: example_plugin.struct1

Geschachtelte Strukturen

Beginnend mit SmartHomeNG v1.7 können Struktur Definitionen ineinander verschachtelt werden.

Wie Items die eine Struktur mit dem struct Attribut referenzieren, kann auch eine Struktur Definition eine eine andere Struktur referenzieren. SmartHomeNG löst alle Struktur Referenzen in Strukturen auf, bevor der Item Tree geladen wird.

Bemerkung

Bitte beachten: Wenn Sub-Struktur Referenzen aufgelöst werden, gibt es zwei Unterschiede in der Art wie Item Definitionen geladen werden. Diese Unterschiede werden nur sichtbar, falls Strukturen Item Attribute redefinieren.

Redefininieren von Attributen

Wenn Items definiert werden ist es möglich, das selbe Attribut eines Items in mehreren YAML Dateien zu definieren. Beim Einlesen der Item Definitionen „gewinnt“ die Attribut Definition die zuletzt eingelesen wurde.

In struct/sub-struct Definitionen hingegen, „gewinnt“ die erste Definition eines Attributes.

Beim auflösen von sub-structs soll normalerweise der übergeordnete Level gewinnen. Das ermöglicht es zum Beispiel in einer Item Definition eine Attribut Definition zu überschreiben, welche in einer Struktur bereits festgelegt wurde. Damit das so erfolgt, muss das betreffende Attribut im Item in der Reihenfolge vor dem struct Attribut definiert werden. Falls das Attribut im Item erst nach dem struct Attribut definiert wird, „gewinnt“ die Definition in der Structure. Dieses Verhalten gilt analog beim verschachteln von Strukturen.

Redefininieren von list-Attributen

Wenn Attribute die redefiniert werden Listen sind, findet kein überschreiben der Definition statt. Stattdessen werden die Listen aneinander gehängt. Das geschieht in der Reihenfolge in der die Attribut Definitionen eingelesen werden.

Definitionen für multi-instance Plugins

Wenn ein Plugin Multi-Instance fähig ist, ist es wahrscheinlich, dass Item Strukturen Instanz-spezifische Attribute enthalten. In Item Definitionen wird bei solchen Attributen @<instance-name> an den Attribut Namen angefügt.

Um in Strukturen zu kennzeichnen, welche Attribute einen Instanz Namen hinzugefügt bekommen sollen, wird bei diesen Attributen der konstante String @instance hinzugefügt. Dieser String wird beim Aufbau des Item Trees durch den realen Instanz Namen ersetzt.

item_structs:
    struct1:

        item1:
            type: int
        item2:
            item3:
                name: 'my item 3'
                type: str
                plg_attr1@instance: 'plugin specific'
            item4:
                type: bool
                initial_value: True

In der Item Konfiguration in den Dateien im Verzeichnis ../items wird der Instanz Name der Struktur mitgegeben. Das sieht z.B. folgendermaßen aus:

item_name_of_struct:
    struct: example_plugin.struct1
    instance: plg_instance

Im geladenen Item (bei Verwendung der Admin GUI), wird item3 dann ein Attribut haben, das plg_attr1@plg_instance benannt ist.

Plugins ohne item-structs

Falls ein Plugin keine Item Attribute hat, wird das durch den folgenden Eintrag in der Datei plugin.yaml angezeigt:

item_structs: NONE

Hinweis

Bitte beachten, dass hier NONE vollständig in Großbuchstaben geschrieben werden muss.

logic_parameters

Die Daten der Logic Parameter werden für die Generierung der Dokumentation verwendet. Außerdem werden diese Parameter für die Konfiguration von Logiken in der Admin GUI verwendet. Falls die konfigurierten Daten nicht gültig sind, werden Warnungen in das Logfile von SmartHomeNG geschrieben.

Der Abschnitt logic_parameters: enthält einen Abschnitt für jeden Parameter der für eine Logik verwendet werden kann. Der Name dieses Unter-Abschnitts ist der Name des Parameters der Logik.

logic_parameters:
    param1:
        type: int
        default: 1234
        description:
            de: 'Deutsche Beschreibung'
            en: 'English description'
        valid_list:
          - 1234
          - 2222
          - 4321

    param2:
        type: ...

Beschreibung der Schlüssel im Abschnitt für einen Parameter bzw. ein Attribut:

type: Beschreibt den Datatyp des Parameters bzw. Attributes. Gültige Datentypen sind:
Einfache Datentypen:
bool - ein boolscher Wert

int - ein ganzzahliger Wert

scene - ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiert

float - ein numerischer Wert der Nachkommastellen enthalten darf

num - das Equivalent zum Typ `float

str - ein String`

ip - ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiert

ipv4 - ein String, der eine ipv4-Adresse repräsentiert

ipv6 - ein String, der eine ipv6-Adresse repräsentiert

mac - ein String, der eine MAC Adresse repräsentiert

knx_ga - ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiert

foo - der universelle Datatyp
Komplexe Datentypen:
dict - ein Dictionary

list - eine Liste bei der jedes Element vom Datentyp foo ist

list(len) - eine Liste fester Länge bei der jedes Element vom Datentyp foo ist und deren Anzahl Elemente len ist

list(subtype) - eine Liste bei der jedes Element vom Datentyp subtype ist ¹ (z.B.: list(int) or list(ipv4))

list(subtype, subtype, ...) - eine Liste bei der jedes Element von einem angegebenen Datentyp ist. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

list(len,subtype, subtype, ...) - eine Liste fester Länge bei der bei der für jedes Element ein subtype angegeben wird. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

¹ subtype kann nur ein einfacher Datentyp sein
gui_type: Optional: Spezifiziert genauer, wie der Parameter in der Admin GUI shngadmin behandelt werden soll. Die Handhabung der Parameter in der Admin GUI wird durch den Parameter type bestimmt. type ist jedoch auf die Datentypen beschränkt, die SmartHomeNG kennt. Für das Editieren kann es jedoch wünschenswert sein, unterschiedlche Feld-Editoren für den selben Datentyp zu verwenden.

Bisher werden nur zwei Werte für gui_type unterstützt:
- wide_str wird benutzt, um ein breiteres Editor Feld zu verwenden (z.B. für Strings die einen längeren Inhalt haben können/sollen.
- readonly wird benutzt, wenn der Parameter nicht in der GUI konfiguriert werden soll, z.B. wenn das Webinterface des Plugins diesen Parameter konfiguriert.
default: Optional: Gibt einen Standardwert vor, der verwendet wird, falls bei der Konfiguration des Parameters in ../etc/plugin.yaml bzw. ../etc/module.yaml kein Wert angegeben wird.
description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional
valid_list: Optional: Liste der erlaubten Werte für den Parameter (case sensitive)
valid_list_ci: Optional: Liste der erlaubten Werte für den Parameter (nicht case sensitive) Der Wert wird dem Plugin/Modul in lower case übergeben. Falls valid_list_ci angegeben ist, wird eine evtl spezifizierte valid_list ignoriert.
valid_list_description: Optional: Beschreibung der Werte, die in valid_list: bzw. valid_list_ci: spezifiziert sind. Falls definiert, muss valid_list_description: Sub-Keys haben, um die Beschreibung in mehreren Sprachen (de, en, fr, pl, …) anzugeben.

Jeder Sprach-Sub-Key muss eine Liste sein, die für jeden Eintrag in valid_list eine Beschreibung enthält.
valid_min: Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein minimal Wert angegeben werden
valid_max Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein maximal Wert angegeben werden
mandatory: Optional: Falls auf True gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert für default: definiert ist.

Plugins ohne Logic Parameter

Falls ein Plugin keine Logik Parameter hat, wird das durch den folgenden Eintrag in der Datei plugin.yaml angezeigt:

logic_parameters: NONE

Hinweis

Bitte beachten, dass hier NONE vollständig in Großbuchstaben geschrieben werden muss.

plugin_functions

Dieser Abschnitt beschreibt die öffentlichen Funktionen, die in einem Plugin implementiert sind.

plugin_functions: enthält einen Abschnitt für jede implementierte Funktion, die öffenlich (also von außerhalb des Plugins aufrufbar) sein soll. Der Name des Abschnitts ist der Name der Funktion.

Jede Funktionsdefinition enhält einen Abschnitt parameters:, welcher die Parameter der Funktion im Detail beschreibt.

Die Definitionen im Abschnitt plugin_functions: werden für die Erstellung der Dokumentation genutzt. In der Zukunft sollen die Definitionen für die Konfiguration in der Admin GUI genutzt werden.

plugin_functions:
    example_function:
        type: str
        description:
            de: 'Deutsche Beschreibung der Funktion'
            en: 'English description of the function'
        parameters:
            param1:
                type: int
                default: 1234
                description:
                    de: 'Deutsche Beschreibung des Funktionsparameters'
                    en: 'English description of the function's parameter'
                valid_list:
                  - 1234
                  - 2222
                  - 4321

            param2:
                type: ...

Beschreibung der Schlüssel im Abschnitt für einen Parameter bzw. ein Attribut:

type: Beschreibt den Datatyp des Parameters bzw. Attributes. Gültige Datentypen sind:
Einfache Datentypen:
bool - ein boolscher Wert

int - ein ganzzahliger Wert

scene - ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiert

float - ein numerischer Wert der Nachkommastellen enthalten darf

num - das Equivalent zum Typ `float

str - ein String`

ip - ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiert

ipv4 - ein String, der eine ipv4-Adresse repräsentiert

ipv6 - ein String, der eine ipv6-Adresse repräsentiert

mac - ein String, der eine MAC Adresse repräsentiert

knx_ga - ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiert

foo - der universelle Datatyp
Komplexe Datentypen:
dict - ein Dictionary

list - eine Liste bei der jedes Element vom Datentyp foo ist

list(len) - eine Liste fester Länge bei der jedes Element vom Datentyp foo ist und deren Anzahl Elemente len ist

list(subtype) - eine Liste bei der jedes Element vom Datentyp subtype ist ¹ (z.B.: list(int) or list(ipv4))

list(subtype, subtype, ...) - eine Liste bei der jedes Element von einem angegebenen Datentyp ist. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

list(len,subtype, subtype, ...) - eine Liste fester Länge bei der bei der für jedes Element ein subtype angegeben wird. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

¹ subtype kann nur ein einfacher Datentyp sein
gui_type: Optional: Spezifiziert genauer, wie der Parameter in der Admin GUI shngadmin behandelt werden soll. Die Handhabung der Parameter in der Admin GUI wird durch den Parameter type bestimmt. type ist jedoch auf die Datentypen beschränkt, die SmartHomeNG kennt. Für das Editieren kann es jedoch wünschenswert sein, unterschiedlche Feld-Editoren für den selben Datentyp zu verwenden.

Bisher werden nur zwei Werte für gui_type unterstützt:
- wide_str wird benutzt, um ein breiteres Editor Feld zu verwenden (z.B. für Strings die einen längeren Inhalt haben können/sollen.
- readonly wird benutzt, wenn der Parameter nicht in der GUI konfiguriert werden soll, z.B. wenn das Webinterface des Plugins diesen Parameter konfiguriert.
default: Optional: Gibt einen Standardwert vor, der verwendet wird, falls bei der Konfiguration des Parameters in ../etc/plugin.yaml bzw. ../etc/module.yaml kein Wert angegeben wird.
description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional
valid_list: Optional: Liste der erlaubten Werte für den Parameter (case sensitive)
valid_list_ci: Optional: Liste der erlaubten Werte für den Parameter (nicht case sensitive) Der Wert wird dem Plugin/Modul in lower case übergeben. Falls valid_list_ci angegeben ist, wird eine evtl spezifizierte valid_list ignoriert.
valid_list_description: Optional: Beschreibung der Werte, die in valid_list: bzw. valid_list_ci: spezifiziert sind. Falls definiert, muss valid_list_description: Sub-Keys haben, um die Beschreibung in mehreren Sprachen (de, en, fr, pl, …) anzugeben.

Jeder Sprach-Sub-Key muss eine Liste sein, die für jeden Eintrag in valid_list eine Beschreibung enthält.
valid_min: Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein minimal Wert angegeben werden
valid_max Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein maximal Wert angegeben werden
mandatory: Optional: Falls auf True gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert für default: definiert ist.

Plugins ohne Plugin Funktionen

Falls ein Plugin keine öffentlichen Plugin Funktionen definiert, wird das durch den folgenden Eintrag in der Datei plugin.yaml angezeigt:

plugin_functions: NONE

Hinweis

Bitte beachten, dass hier NONE vollständig in Großbuchstaben geschrieben werden muss.

Funktionen ohne Parameter

Falls eine Plugin-Funktion keine Parameter hat, darf der Eintrag parameters: nicht in die plugin.yaml aufgenommen werden. Er entfällt ohne weitere Angaben.

Aufruf von Funktionen

Wenn Plugin-Funktionen in einer Logik verwendet werden sollen, kann dies in der folgenden Form erfolgen:

result = sh.plugins.return_plugin("<Plugin-Name>").<Funktionsname>(<Argumente>)